Merge pull request #3143 from Elv13/doc_client_layout

Document the client layout properties

.travis.yml

@@ -248,7 +248,10 @@ script:
       cd "$BUILD_IN_DIR"
       travis_run_in_fold "build_in_dir" cmake $CMAKE_ARGS "$SOURCE_DIRECTORY"
     fi
-  - travis_run_in_fold "make" make
+  - travis_run_in_fold "make" make ; sleep 5
+  - make ; sleep 5
+  - make ; sleep 5
+  - make ; sleep 5
   - |
     if [ "$TRAVIS_TEST_RESULT" = 0 ]; then
       travis_run_in_fold "make.install" sudo env PATH=$PATH make install

docs/03-declarative-layout.md

@@ -1,7 +1,13 @@
-# The AwesomeWM widget system
+# The Widget system
 
 This document explains how to define, place and manage widgets.
 
+## The default configuration
+
+This is what the widgets present in the default configuration are named:
+
+@DOC_awful_popup_defaultconfig_EXAMPLE@
+
 ## The default widgets
 
 ### Widgets
@@ -28,7 +34,59 @@ configurable rules.
 
 @DOC_layout_WIDGET_LIST@
 
-### Other
+### Awful widgets
+
+This modules contains the higher level window manager widgets. Since most of them
+are used by the default config, here is how it maps:
+
+@DOC_awful_wibar_defaultwibar_EXAMPLE@
+
+@DOC_awidget_WIDGET_LIST@
+
+### Titlebar widgets
+
+The titlebar comes with some convinient default widgets. It simplify the most
+basic "Windows/macOS" like titlebars.
+
+@DOC_awful_titlebar_defaulttitlebar_EXAMPLE@
+
+Note that titlebars can also be added on
+each side. This is how "active" titlebars (click to resize) can be implemented.
+The default `rc.lua` does not add active borders:
+
+![](../images/client_geo.svg)
+
+<table class="widget_list" border="1">
+ <tr>
+   <th>Widget</th><th>Description</th>
+ </tr>
+ <tr>
+  <td>`awful.titlebar.widget.iconwidget`</td><td>The client icon (see `client.icon`)</td>
+ </tr>
+ <tr>
+  <td>`awful.titlebar.widget.titlewidget`</td><td>The client title (see `client.name`)</td>
+ </tr>
+ <tr>
+  <td>`awful.titlebar.widget.floatingbutton`</td><td> Toggle the floating (toggled) vs. tiling mode (untoggled). </td>
+ </tr>
+ <tr>
+  <td>`awful.titlebar.widget.maximizedbutton`</td><td>Toggle the maximized mode (toggled). Note that this is the<br/>"full" maximized mode, not vertical or horizontal maximization.<br/>See `client.maximized`.</td>
+ </tr>
+ <tr>
+  <td>`awful.titlebar.widget.stickybutton`</td><td>When toggled, a client will be displayed in all (screen) tags. See `client.sticky`)</td>
+ </tr>
+ <tr>
+  <td>`awful.titlebar.widget.ontopbutton`</td><td>When toggled, the client will be part of the `ontop` layer (see `client.ontop`).</td>
+ </tr>
+ <tr>
+  <td>`awful.titlebar.widget.closebutton`</td><td></td>
+ </tr>
+ <tr>
+  <td>`titlebar.widget.minimizebutton`</td><td></td>
+ </tr>
+</table>
+
+### Notification widgets
 
 Notifications also have their own widgets.
 

docs/05-awesomerc.md.lua

@@ -18,10 +18,15 @@ The Awesome API is distributed across many libraries (also called modules).
 Here are the modules that we import:
 
 <table class='widget_list' border=1>
+  <tr style='font-weight: bold;'>
+   <th align='center'>Library</th>
+   <th align='center'>Description</th>
+  </tr>
   <tr><td>`gears`</td><td>Utilities such as color parsing and objects</td></tr>
   <tr><td>`wibox`</td><td>Awesome own generic widget framework</td></tr>
   <tr><td>`awful`</td><td>Everything related to window managment</td></tr>
   <tr><td>`naughty`</td><td>Notifications</td></tr>
+  <tr><td>`ruled`</td><td>Define declarative rules on various events</td></tr>
   <tr><td>`menubar`</td><td>XDG (application) menu implementation</td></tr>
   <tr><td>`beautiful`</td><td>Awesome theme module</td></tr>
 </table>

docs/08-client-layout-system.md

@@ -0,0 +1,54 @@
+# The AwesomeWM client layout system
+
+This document explains how to use clients layouts and how awesome manage them.
+
+**Client layout**  refers to the mechanism awesome uses to place client on the screen. The layout definition can be a basic system where clients are all *floating* like in a normal *DE* (eg GNOME, KDE, ...) or tiled on the screen like in *tilled window manager* (eg i3, BSPWM, ...). It is also possible to define complex client layout mixing both concepts and even implementing a *[stateful](https://en.wikipedia.org/wiki/State_(computer_science)) placement strategy*.
+
+Awesome WM manages client layouts per tag. It means each tag has its own layout selection and uses them independently from other tags. When multiple tags are selected at once, Awesome uses only client layouts from the first selected tag and apply it to all current clients.
+
+## Layouts configuration
+
+Layout can be configured by setting properties from the tag instance.
+
+Example of creating a new tag with client layout parameters:
+```lua
+awful.tag.add("My Tag", {
+    screen = screen.primary,
+    layout = awful.layout.suit.tile,
+    master_fill_policy = "master_width_factor",
+    gap_single_client = false,
+    gap = 15
+})
+```
+
+Example of changing client layout parameters on an existing tag:
+```lua
+-- Change the gap for the tag `my_tag`:
+my_tag.useless_gap = 10
+
+-- Change the master_width_factor for the tag `my_tag`:
+my_tag.master_width_factor = 0.5
+```
+
+Here is a list of common properties used to configure tags:
+
+<table class='widget_list' border=1>
+<tr>
+<th align='center'>Property</th>
+<th align='center'>Type</th>
+<th align='center'>Description</th>
+</tr>
+<tr><td>gap</td><td>number</td><td>The gap (spacing, also called useless_gap) between clients.</td></tr>
+<tr><td>gap_single_client</td><td>boolean</td><td>Enable gaps for a single client.</td></tr>
+<tr><td>master_fill_policy</td><td>string</td><td>Set size fill policy for the master client(s).</td></tr>
+<tr><td>master_count</td><td>integer</td><td>Set the number of master windows.</td></tr>
+<tr><td>icon</td><td>path or surface</td><td>Set the tag icon.</td></tr>
+<tr><td>column_count</td><td>integer</td><td>Set the number of columns.</td></tr>
+</table>
+
+
+## Creating new client layouts
+
+* arrange function (params definition)
+* needs a name property
+* mouse_resize_handler function

docs/config.ld

@@ -20,7 +20,7 @@ merge=true
 use_markdown_titles=true
 wrap=true
 full_description = [[
-Welcome to the documentation for the awesome window manager. Below you find an
+Welcome to the documentation for the Awesome window manager. Below you find an
 overview of the individual parts which links to the full documentation.
 
 If you are a new user, you may want to read @{07-my-first-awesome.md} to get
@@ -28,6 +28,49 @@ started. In @{05-awesomerc.md}, the default configuration is explained.
 
 If you already used awesome in the past, @{89-NEWS.md} and @{17-porting-tips.md}
 should be useful for you.
+
+### Default configuration components name:
+
+<center><img src="../doc/images/AUTOGEN_awful_popup_defaultconfig.svg"></center>
+
+### Guides
+
+<div class="index_guides">
+    <div>
+        <a href="../doc/documentation/07-my-first-awesome.md.html">Getting started</a>
+        <a href="../doc/documentation/90-FAQ.md.html">FAQ</a>
+        <a href="../doc/documentation/01-readme.md.html">Read me</a>
+        <a href="../doc/documentation/89-NEWS.md.html">NEWS</a>
+    </div>
+    <div>
+        <a href="../doc/documentation/03-declarative-layout.md.html">The widget system</a>
+        <a href="../doc/documentation/09-options.md.html">Startup options</a>
+        <a href="../doc/documentation/05-awesomerc.md.html">The default rc.lua</a>
+        <a href="../doc/documentation/08-client-layout-system.md.html">Window management</a>
+    </div>
+</div>
+
+## Major libraries
+
+AwesomeWM ship multiple libraries. Here is an overview of the purpose and scope
+of those libraries.
+
+<table class='widget_list' border=1>
+  <tr style='font-weight: bold;'>
+   <th align='center'>Library</th>
+   <th align='center'>Description</th>
+  </tr>
+  <tr><td>`gears`</td><td>Utilities such as color parsing and objects</td></tr>
+  <tr><td>`wibox`</td><td>Awesome own generic widget framework</td></tr>
+  <tr><td>`awful`</td><td>Everything related to window managment</td></tr>
+  <tr><td>`awful.widget`</td><td>Window management related widgets</td></tr>
+  <tr><td>`awful.layout`</td><td>The default stateless client tiling module.</td></tr>
+  <tr><td>`ruled`</td><td>Define declarative rules on various events</td></tr>
+  <tr><td>`naughty`</td><td>Notifications</td></tr>
+  <tr><td>`menubar`</td><td>XDG (application) menu implementation</td></tr>
+  <tr><td>`beautiful`</td><td>Awesome theme module</td></tr>
+</table>
+
 ]]
 topics={
     '00-authors.md',
@@ -38,6 +81,7 @@ topics={
     '05-awesomerc.md',
     '06-appearance.md',
     '07-my-first-awesome.md',
+    '08-client-layout-system.md',
     '09-options.md',
     '16-using-cairo.md',
     '17-porting-tips.md',

docs/ldoc.css

@@ -482,3 +482,24 @@ pre .url { color: #272fc2; text-decoration: underline; }
     color: rgb(128, 128, 128);
     border-radius: 7px;
 }
+
+.index_guides div {
+    margin: 0 auto;
+    display: table;
+    margin-bottom: 10px;
+}
+
+.index_guides div a {
+    display: inline-block;
+    border: solid 1px #cccccc;
+    width: 200px;
+    margin-left: 10px;
+    margin-right: 10px;
+    text-align: center;
+    padding-top: 20px;
+    padding-bottom: 20px;
+}
+
+.index_guides div a:hover {
+    background-color: #99b3ec;
+}

docs/widget_lists.cmake

@@ -52,5 +52,6 @@ endfunction()
 generate_widget_list( "container" )
 generate_widget_list( "layout"    )
 generate_widget_list( "widget"    )
+generate_widget_list( "awidget"   )
 
 # vim: filetype=cmake:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80:foldmethod=marker

lib/awful/mouse/init.lua

@@ -31,12 +31,25 @@ local mouse = {
 mouse.object = {}
 mouse.wibox = {}
 
---- The default snap distance.
+--- The default distance before snapping clients together.
+--
+-- @DOC_screen_client_snap_EXAMPLE@
+--
 -- @tfield integer awful.mouse.snap.default_distance
 -- @tparam[opt=8] integer default_distance
 -- @see awful.mouse.snap
 
+--- The default distance before activating screen edge snap.
+-- @tfield integer awful.mouse.snap.aerosnap_distance
+-- @tparam[opt=16] integer default_distance
+-- @see awful.mouse.snap
+
 --- Enable screen edges snapping.
+--
+--
+--
+--@DOC_awful_placement_aero_snap_EXAMPLE@
+--
 -- @tfield[opt=true] boolean awful.mouse.snap.edge_enabled
 
 --- Enable client to client snapping.
@@ -57,9 +70,9 @@ mouse.wibox = {}
 -- @beautiful beautiful.snap_shape
 -- @tparam function shape A `gears.shape` compatible function
 
---- The gap between snapped contents.
+--- The gap between snapped clients.
 -- @beautiful beautiful.snapper_gap
--- @tparam number (default: 0)
+-- @tparam[opt=0] number snapper_gap
 
 --- Get the client object under the pointer.
 -- @deprecated awful.mouse.client_under_pointer

lib/awful/mouse/snap.lua

@@ -25,7 +25,8 @@ local capi = {
 }
 
 local module = {
-    default_distance = 8
+    default_distance  = 8,
+    aerosnap_distance = 16
 }
 
 local placeholder_w = nil
@@ -258,7 +259,7 @@ resize.add_move_callback(function(c, geo, args)
     -- Screen edge snapping (areosnap)
     if (module.edge_enabled ~= false)
       and args and (args.snap == nil or args.snap) then
-        detect_areasnap(c, 16)
+        detect_areasnap(c, module.aerosnap_distance)
     end
 
     -- Snapping between clients

lib/awful/permissions/init.lua

@@ -542,7 +542,7 @@ end, "mouse_enter")
 -- depending if the client is tiled, floating, maximized and then from its state
 -- (urgent, new, active, normal)
 --
--- @signalhandler awful.ewmh.update_border
+-- @signalhandler awful.permissions.update_border
 -- @usebeautiful beautiful.border_color_marked
 -- @usebeautiful beautiful.border_color_active
 -- @usebeautiful beautiful.border_color_normal

lib/awful/screen.lua

@@ -234,6 +234,7 @@ end
 -- @tfield integer table.right The padding on the right.
 -- @tfield integer table.top The padding on the top.
 -- @tfield integer table.bottom The padding on the bottom.
+-- @usebeautiful beautiful.maximized_honor_padding Honor the screen padding when maximizing.
 
 function screen.object.get_padding(self)
     local p = data.padding[self] or {}

lib/awful/tag.lua

@@ -713,6 +713,13 @@ end
 -- See the layout suit documentation for information about how the master width
 -- factor is used.
 --
+-- @DOC_screen_mwfact_EXAMPLE@
+--
+-- When multiple columns are used, the master width remains the same, but
+-- the other columns split the remaining space among them:
+--
+-- @DOC_screen_mwfact2_EXAMPLE@
+--
 -- **Signal:**
 --
 -- * *property::mwfact* (deprecated)
@@ -724,6 +731,7 @@ end
 -- @see column_count
 -- @see master_fill_policy
 -- @see gap
+-- @see awful.tag.incmwfact
 
 function tag.object.set_master_width_factor(t, mwfact)
     if mwfact >= 0 and mwfact <= 1 then
@@ -1088,9 +1096,17 @@ end
 
 --- The gap (spacing, also called `useless_gap`) between clients.
 --
--- This property allow to waste space on the screen in the name of style,
+-- This property allows to waste space on the screen in the name of style,
 -- unicorns and readability.
 --
+-- In this example, the value of `gap` is set to 20:
+--
+-- @DOC_screen_gaps_EXAMPLE@
+--
+-- Compared to setting to the (very high) value of 50:
+--
+-- @DOC_screen_gaps2_EXAMPLE@
+--
 -- **Signal:**
 --
 -- * *property::useless_gap*
@@ -1098,6 +1114,7 @@ end
 -- @property gap
 -- @param number The value has to be greater than zero.
 -- @see gap_single_client
+-- @see awful.tag.incgap
 
 function tag.object.set_gap(t, useless_gap)
     if useless_gap >= 0 then
@@ -1141,12 +1158,26 @@ end
 
 --- Enable gaps for a single client.
 --
+-- If the gaps are used purely for readability when multiple
+-- clients are tiled, then it may make sense to disable it
+-- when there is only a single client (to recover that space).
+-- In that case, set `gap_single_client` to `false`.
+--
+-- Default (with a 20px gap):
+--
+-- @DOC_screen_gap_single_client_true_EXAMPLE@
+--
+-- when set to false:
+--
+-- @DOC_screen_gap_single_client_false_EXAMPLE@
+--
 -- **Signal:**
 --
 -- * *property::gap\_single\_client*
 --
 -- @property gap_single_client
 -- @param boolean Enable gaps for a single client
+-- @see awful.tag.incgap
 
 function tag.object.set_gap_single_client(t, gap_single_client)
     tag.setproperty(t, "gap_single_client", gap_single_client == true)
@@ -1195,18 +1226,33 @@ end
 
 --- Set size fill policy for the master client(s).
 --
+-- Some multi-column layouts can be configured so that the space is
+-- redistributed when there is not enough clients to fill all columns.
+--
 -- ** Possible values**:
 --
 -- * *expand*: Take all the space
--- * *master_width_factor*: Only take the ratio defined by the
+-- * *master\_width\_factor*: Only take the ratio defined by the
 --   `master_width_factor`
 --
+-- This is the default behavior of the `tile.left` layout (*expand*):
+--
+-- @DOC_screen_mfpol2_EXAMPLE@
+--
+-- This is what happends when set to `master_width_factor`:
+--
+-- @DOC_screen_mfpol_EXAMPLE@
+--
+-- The remaining space that would have been used for the second column is
+-- redistributed on both side.
+--
 -- **Signal:**
 --
 -- * *property::master_fill_policy*
 --
 -- @property master_fill_policy
 -- @param string "expand" or "master_width_factor"
+-- @see awful.tag.togglemfpol
 
 function tag.object.get_master_fill_policy(t)
     return tag.getproperty(t, "master_fill_policy")
@@ -1276,6 +1322,7 @@ end
 --
 -- @property master_count
 -- @param integer nmaster Only positive values are accepted
+-- @see awful.tag.incnmaster
 
 function tag.object.set_master_count(t, nmaster)
     if nmaster >= 0 then
@@ -1343,12 +1390,16 @@ end
 
 --- Set the tag icon.
 --
+-- @DOC_wibox_awidget_taglist_icon_EXAMPLE@
+--
 -- **Signal:**
 --
 -- * *property::icon*
 --
 -- @property icon
 -- @tparam path|surface icon The icon
+-- @see awful.widget.taglist
+-- @see gears.surface
 
 -- accessors are implicit.
 
@@ -1383,6 +1434,8 @@ end
 
 --- Set the number of columns.
 --
+-- @DOC_sequences_tag_column_count_EXAMPLE@
+--
 -- **Signal:**
 --
 -- * *property::ncol* (deprecated)
@@ -1390,6 +1443,7 @@ end
 --
 -- @property column_count
 -- @tparam integer ncol Has to be greater than 1
+-- @see awful.tag.incncol
 
 function tag.object.set_column_count(t, ncol)
     if ncol >= 1 then

lib/awful/titlebar.lua

@@ -654,7 +654,7 @@ end
 -- This way, you can e.g. modify the font that is used.
 -- @param c The client for which a titlewidget should be created.
 -- @return The title widget.
--- @staticfct awful.titlebar.widget.titlewidget
+-- @constructorfct awful.titlebar.widget.titlewidget
 function titlebar.widget.titlewidget(c)
     local ret = textbox()
     local function update()
@@ -672,7 +672,7 @@ end
 -- available. This way, you can e.g. disallow resizes.
 -- @param c The client for which an icon widget should be created.
 -- @return The icon widget.
--- @staticfct awful.titlebar.widget.iconwidget
+-- @constructorfct awful.titlebar.widget.iconwidget
 function titlebar.widget.iconwidget(c)
     return clienticon(c)
 end
@@ -690,7 +690,7 @@ end
 -- @param selector A function that selects the image that should be displayed.
 -- @param action Function that is called when the button is clicked.
 -- @return The widget
--- @staticfct awful.titlebar.widget.button
+-- @constructorfct awful.titlebar.widget.button
 function titlebar.widget.button(c, name, selector, action)
     local ret = imagebox()
 
@@ -778,7 +778,7 @@ end
 
 --- Create a new float button for a client.
 -- @param c The client for which the button is wanted.
--- @staticfct awful.titlebar.widget.floatingbutton
+-- @constructorfct awful.titlebar.widget.floatingbutton
 function titlebar.widget.floatingbutton(c)
     local widget = titlebar.widget.button(c, "floating", aclient.object.get_floating, aclient.floating.toggle)
     update_on_signal(c, "property::floating", widget)
@@ -787,7 +787,7 @@ end
 
 --- Create a new maximize button for a client.
 -- @param c The client for which the button is wanted.
--- @staticfct awful.titlebar.widget.maximizedbutton
+-- @constructorfct awful.titlebar.widget.maximizedbutton
 function titlebar.widget.maximizedbutton(c)
     local widget = titlebar.widget.button(c, "maximized", function(cl)
         return cl.maximized
@@ -800,7 +800,7 @@ end
 
 --- Create a new minimize button for a client.
 -- @param c The client for which the button is wanted.
--- @staticfct awful.titlebar.widget.minimizebutton
+-- @constructorfct awful.titlebar.widget.minimizebutton
 function titlebar.widget.minimizebutton(c)
     local widget = titlebar.widget.button(c, "minimize",
                                           function() return "" end,
@@ -811,14 +811,14 @@ end
 
 --- Create a new closing button for a client.
 -- @param c The client for which the button is wanted.
--- @staticfct awful.titlebar.widget.closebutton
+-- @constructorfct awful.titlebar.widget.closebutton
 function titlebar.widget.closebutton(c)
     return titlebar.widget.button(c, "close", function() return "" end, function(cl) cl:kill() end)
 end
 
 --- Create a new ontop button for a client.
 -- @param c The client for which the button is wanted.
--- @staticfct awful.titlebar.widget.ontopbutton
+-- @constructorfct awful.titlebar.widget.ontopbutton
 function titlebar.widget.ontopbutton(c)
     local widget = titlebar.widget.button(c, "ontop",
                                           function(cl) return cl.ontop end,
@@ -829,7 +829,7 @@ end
 
 --- Create a new sticky button for a client.
 -- @param c The client for which the button is wanted.
--- @staticfct awful.titlebar.widget.stickybutton
+-- @constructorfct awful.titlebar.widget.stickybutton
 function titlebar.widget.stickybutton(c)
     local widget = titlebar.widget.button(c, "sticky",
                                           function(cl) return cl.sticky end,

lib/awful/widget/button.lua

@@ -1,11 +1,7 @@
 ---------------------------------------------------------------------------
 -- A simple button widget.
 --
---    button.buttons = {
---        awful.button({}, 1, nil, function ()
---            print("Mouse was clicked")
---        end)
---    }
+-- @DOC_wibox_awidget_defaults_button_EXAMPLE@
 --
 -- @author Julien Danjou <julien@danjou.info>
 -- @copyright 2008-2009 Julien Danjou
@@ -18,6 +14,7 @@ local imagebox = require("wibox.widget.imagebox")
 local widget = require("wibox.widget.base")
 local surface = require("gears.surface")
 local cairo = require("lgi").cairo
+local gtable = require("gears.table")
 
 local button = { mt = {} }
 
@@ -25,10 +22,13 @@ local button = { mt = {} }
 -- a real button.
 --
 -- @constructorfct awful.widget.button
--- @param args Widget arguments. "image" is the image to display.
+-- @tparam table args Widget arguments.
+-- @tparam string args.image "image" is the image to display (mandatory).
+-- @tparam table args.buttons The buttons.
 -- @return A textbox widget configured as a button.
 function button.new(args)
-    if not args or not args.image then
+    args = args or {}
+    if not args.image then
         return widget.empty_widget()
     end
 
@@ -47,10 +47,14 @@ function button.new(args)
     end
     w:set_image(args.image)
 
-    w.buttons = {
+    local btns = gtable.clone(args.buttons or {}, false)
+
+    table.insert(btns,
         abutton({}, 1, function () orig_set_image(w, img_press) end,
                        function () orig_set_image(w, img_release) end)
-    }
+    )
+
+    w.buttons = btns
 
     w:connect_signal("mouse::leave", function(self) orig_set_image(self, img_release) end)
 

lib/awful/widget/watch.lua

@@ -24,6 +24,10 @@
 --
 -- ![Example screenshot](../images/awful_widget_watch.png)
 --
+-- Here is the most basic usage:
+--
+-- @DOC_wibox_awidget_defaults_watch_EXAMPLE@
+--
 -- @author Benjamin Petrenko
 -- @author Yauheni Kirylau
 -- @copyright 2015, 2016 Benjamin Petrenko, Yauheni Kirylau

objects/client.c

@@ -667,6 +667,8 @@ lua_class_t client_class;
  * cause several other changes to the state in order to ensure that
  * a client's position and its screen are consistent.
  *
+ * @DOC_sequences_client_screen_EXAMPLE@
+ *
  * @property screen
  * @tparam screen screen
  * @propemits false false
@@ -714,18 +716,79 @@ lua_class_t client_class;
  * @property border_width
  * @tparam integer border_width
  * @propemits false false
+ * @usebeautiful beautiful.border_width_active
+ * @usebeautiful beautiful.border_width_normal
+ * @usebeautiful beautiful.border_width_new
+ * @usebeautiful beautiful.border_width_urgent
+ * @usebeautiful beautiful.border_width_floating
+ * @usebeautiful beautiful.border_width_floating_active
+ * @usebeautiful beautiful.border_width_floating_normal
+ * @usebeautiful beautiful.border_width_floating_new
+ * @usebeautiful beautiful.border_width_floating_urgent
+ * @usebeautiful beautiful.border_width_maximized
+ * @usebeautiful beautiful.border_width_maximized_active
+ * @usebeautiful beautiful.border_width_maximized_normal
+ * @usebeautiful beautiful.border_width_maximized_new
+ * @usebeautiful beautiful.border_width_maximized_urgent
+ * @usebeautiful beautiful.border_width_fullscreen
+ * @usebeautiful beautiful.border_width_fullscreen_active
+ * @usebeautiful beautiful.border_width_fullscreen_normal
+ * @usebeautiful beautiful.border_width_fullscreen_new
+ * @usebeautiful beautiful.border_width_fullscreen_urgent
+ * @usebeautiful beautiful.fullscreen_hide_border Hide the border on fullscreen clients.
+ * @usebeautiful beautiful.maximized_hide_border Hide the border on maximized clients.
  * @see request::border
+ * @see awful.permissions.update_border
+ * @see border_color
  */
 
 /**
  * The client border color.
  *
+ * @DOC_awful_client_border_width_EXAMPLE@
+ *
+ * Note that setting this directly will override and disable all related theme
+ * variables.
+ *
  * @property border_color
  * @tparam color border_color Any string, gradients and patterns will be converted to a
  *  cairo pattern.
  * @propemits false false
+ * @usebeautiful beautiful.border_color_marked The fallback color when the
+ *  client is marked.
+ * @usebeautiful beautiful.border_color_active The fallback color when the
+ *  client is active (focused).
+ * @usebeautiful beautiful.border_color_normal The fallback color when the
+ *  client isn't active/floating/new/urgent/maximized/floating/fullscreen.
+ * @usebeautiful beautiful.border_color_new The fallback color when the
+ *  client is new.
+ * @usebeautiful beautiful.border_color_urgent The fallback color when the
+ *  client is urgent.
+ * @usebeautiful beautiful.border_color_floating The fallback color when the
+ *  client is floating and the other colors are not set.
+ * @usebeautiful beautiful.border_color_floating_active The color when the
+ *  client is floating and is active (focused).
+ * @usebeautiful beautiful.border_color_floating_normal The color when the
+ *  client is floating and not new/urgent/active.
+ * @usebeautiful beautiful.border_color_floating_new
+ * @usebeautiful beautiful.border_color_floating_urgent The color when the
+ *  client is floating and urgent.
+ * @usebeautiful beautiful.border_color_maximized
+ * @usebeautiful beautiful.border_color_maximized_active
+ * @usebeautiful beautiful.border_color_maximized_normal
+ * @usebeautiful beautiful.border_color_maximized_new
+ * @usebeautiful beautiful.border_color_maximized_urgent The color when the
+ *  client is urbent and maximized.
+ * @usebeautiful beautiful.border_color_fullscreen
+ * @usebeautiful beautiful.border_color_fullscreen_active
+ * @usebeautiful beautiful.border_color_fullscreen_normal
+ * @usebeautiful beautiful.border_color_fullscreen_new
+ * @usebeautiful beautiful.border_color_fullscreen_urgent The color when the
+ *  client is fullscreen and urgent.
  * @see request::border
+ * @see awful.permissions.update_border
  * @see gears.color
+ * @see border_width
  */
 
 /**
@@ -735,6 +798,22 @@ lua_class_t client_class;
  * @tparam boolean urgent
  * @propemits false false
  * @see request::border
+ * @usebeautiful beautiful.border_color_urgent The fallback color when the
+ *  client is urgent.
+ * @usebeautiful beautiful.border_color_floating_urgent The color when the
+ *  client is floating and urgent.
+ * @usebeautiful beautiful.border_color_maximized_urgent The color when the
+ *  client is urbent and maximized.
+ * @usebeautiful beautiful.border_color_fullscreen_urgent The color when the
+ *  client is fullscreen and urgent.
+ * @usebeautiful beautiful.border_width_urgent The fallback border width when
+ *  the client is urgent.
+ * @usebeautiful beautiful.border_width_floating_urgent The border width when
+ *  the client is floating and urgent.
+ * @usebeautiful beautiful.border_width_maximized_urgent The border width when
+ *  the client is maximized and urgent.
+ * @usebeautiful beautiful.border_width_fullscreen_urgent The border width when
+ *  the client is fullscreen and urgent.
  */
 
 /**
@@ -815,6 +894,12 @@ lua_class_t client_class;
  * @propemits false false
  * @request client geometry fullscreen granted When the client must be resized
  *  because it became (or stop being) fullscreen.
+ * @see maximized_horizontal
+ * @see maximized_vertical
+ * @see immobilized_horizontal
+ * @see immobilized_vertical
+ * @see maximized
+
  */
 
 /**
@@ -828,6 +913,11 @@ lua_class_t client_class;
  * @request client geometry maximized granted When the client must be resized
  *  because it became (or stop being) maximized.
  * @see request::border
+ * @see maximized_horizontal
+ * @see maximized_vertical
+ * @see fullscreen
+ * @see immobilized_horizontal
+ * @see immobilized_vertical
  */
 
 /**
@@ -840,6 +930,11 @@ lua_class_t client_class;
  * @propemits false false
  * @request client geometry maximized_horizontal granted When the client must be resized
  *  because it became (or stop being) maximized horizontally.
+ * @see maximized_vertical
+ * @see fullscreen
+ * @see immobilized_horizontal
+ * @see immobilized_vertical
+ * @see maximized
  */
 
 /**
@@ -852,6 +947,11 @@ lua_class_t client_class;
  * @propemits false false
  * @request client geometry maximized_vertical granted When the client must be resized
  *  because it became (or stop being) maximized vertically.
+ * @see maximized_horizontal
+ * @see fullscreen
+ * @see immobilized_horizontal
+ * @see immobilized_vertical
+ * @see maximized
  */
 
 /**
@@ -994,6 +1094,8 @@ lua_class_t client_class;
  * per screens rather than globally like some other
  * implementations.
  *
+ * @DOC_sequences_client_sticky_EXAMPLE@
+ *
  * @property sticky
  * @tparam boolean sticky
  * @propemits false false
@@ -1224,6 +1326,13 @@ lua_class_t client_class;
  *
  * This corresponds to EWMH's `_NET_WM_STRUT` and `_NET_WM_STRUT_PARTIAL`.
  *
+ * In the example below, 2 object affect the workarea (using their struts):
+ *
+ * * The top wibar add a `top=24`
+ * * The bottom-left client add `bottom=100, left=100`
+ *
+ * @DOC_screen_struts_EXAMPLE@
+ *
  * @tparam table struts A table with new strut values, or none.
  * @treturn table A table with strut values.
  * @method struts

tests/examples/awful/client/border_width.lua

@@ -0,0 +1,85 @@
+--DOC_NO_USAGE --DOC_GEN_IMAGE --DOC_ASTERISK
+local awful     = require("awful") --DOC_HIDE
+local wibox     = require("wibox") --DOC_HIDE
+local beautiful = require("beautiful")
+
+screen[1]._resize {width = 480, height = 200} --DOC_HIDE
+
+local wb = awful.wibar { position = "top" }--DOC_HIDE
+
+--DOC_HIDE Create the same number of tags as the default config
+awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, screen[1], awful.layout.layouts[1]) --DOC_HIDE
+
+--DOC_HIDE Only bother with widgets that are visible by default
+local mykeyboardlayout = awful.widget.keyboardlayout() --DOC_HIDE
+local mytextclock = wibox.widget.textclock() --DOC_HIDE
+local mytaglist = awful.widget.taglist(screen[1], awful.widget.taglist.filter.all, {}) --DOC_HIDE
+local mytasklist = awful.widget.tasklist(screen[1], awful.widget.tasklist.filter.currenttags, {}) --DOC_HIDE
+
+client.connect_signal("request::titlebars", function(c)--DOC_HIDE
+    local top_titlebar = awful.titlebar(c, {--DOC_HIDE
+        height    = 20,--DOC_HIDE
+        bg_normal = beautiful.bg_normal,--DOC_HIDE
+    })--DOC_HIDE
+
+    top_titlebar : setup {--DOC_HIDE
+        { -- Left--DOC_HIDE
+            awful.titlebar.widget.iconwidget(c),--DOC_HIDE
+            layout  = wibox.layout.fixed.horizontal--DOC_HIDE
+        },--DOC_HIDE
+        { -- Middle--DOC_HIDE
+            { -- Title--DOC_HIDE
+                align  = "center",--DOC_HIDE
+                widget = awful.titlebar.widget.titlewidget(c)--DOC_HIDE
+            },--DOC_HIDE
+            layout  = wibox.layout.flex.horizontal--DOC_HIDE
+        },--DOC_HIDE
+        { -- Right--DOC_HIDE
+            awful.titlebar.widget.floatingbutton (c),--DOC_HIDE
+            awful.titlebar.widget.maximizedbutton(c),--DOC_HIDE
+            awful.titlebar.widget.stickybutton   (c),--DOC_HIDE
+            awful.titlebar.widget.ontopbutton    (c),--DOC_HIDE
+            awful.titlebar.widget.closebutton    (c),--DOC_HIDE
+            layout = wibox.layout.fixed.horizontal()--DOC_HIDE
+        },--DOC_HIDE
+        layout = wibox.layout.align.horizontal--DOC_HIDE
+    }--DOC_HIDE
+end)--DOC_HIDE
+
+
+wb:setup { --DOC_HIDE
+    layout = wibox.layout.align.horizontal, --DOC_HIDE
+    { --DOC_HIDE
+        mytaglist, --DOC_HIDE
+        layout = wibox.layout.fixed.horizontal, --DOC_HIDE
+    }, --DOC_HIDE
+    mytasklist, --DOC_HIDE
+    { --DOC_HIDE
+        layout = wibox.layout.fixed.horizontal, --DOC_HIDE
+        mykeyboardlayout, --DOC_HIDE
+        mytextclock, --DOC_HIDE
+    }, --DOC_HIDE
+} --DOC_HIDE
+
+require("gears.timer").run_delayed_calls_now()--DOC_HIDE
+
+local function gen_client(label)--DOC_HIDE
+    local c = client.gen_fake {hide_first=true} --DOC_HIDE
+
+    c:geometry {--DOC_HIDE
+        x      = 105,--DOC_HIDE
+        y      = 60,--DOC_HIDE
+        height = 60,--DOC_HIDE
+        width  = 230,--DOC_HIDE
+    }--DOC_HIDE
+    c._old_geo = {c:geometry()} --DOC_HIDE
+    c:set_label(label) --DOC_HIDE
+    c:emit_signal("request::titlebars")--DOC_HIDE
+    return c --DOC_HIDE
+end --DOC_HIDE
+
+    local c = gen_client("A manually set border_color") --DOC_HIDE
+    c.border_color = "#ff00ff"
+
+--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80
+

tests/examples/awful/placement/aero_snap.lua

@@ -0,0 +1,33 @@
+--DOC_HIDE_ALL
+--DOC_GEN_IMAGE
+local placement = require("awful.placement")
+screen[1]._resize {width = 180, height = 120} --DOC_HIDE
+screen._add_screen {x = 190, y = 0, width = 180, height = 120} --DOC_HIDE
+screen._add_screen {x = 380, y = 0, width = 180, height = 120} --DOC_HIDE
+
+for _, pos in ipairs{"left", "right"} do
+    local c1 = client.gen_fake {x = 80, y = 55, width=78, height=50}
+    placement.align(client.focus, {position = pos, honor_workarea=true})
+    c1:_hide_all()
+    placement.maximize_vertically(client.focus, {position = pos, honor_workarea=true})
+    c1:set_label(pos)
+end
+
+for _, pos in ipairs{"top", "bottom"} do
+    local c1 = client.gen_fake {x = 80, y = 55, width=75, height=48,screen=screen[2]}
+    placement.align(client.focus, {position = pos, honor_workarea=true})
+    c1:_hide_all()
+    placement.maximize_horizontally(client.focus, {position = pos, honor_workarea=true})
+    c1:set_label(pos)
+end
+
+for _, pos in ipairs{"top_left", "top_right", "bottom_left", "bottom_right"} do
+    local c1 = client.gen_fake {x = 280, y = 55, width=79, height=48, screen=screen[3]}
+    c1:_hide_all()
+    placement.align(client.focus, {position = pos, honor_workarea=true})
+    c1:set_label(pos)
+end
+
+return {hide_lines=true}
+
+--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

tests/examples/awful/placement/align.lua

@@ -7,7 +7,7 @@ for _, pos in ipairs{
     "left", "right", "top", "bottom", "centered",
 } do
 local c1 = client.gen_fake {x = 80, y = 55, width=75, height=50}
-c1:_hide()
+c1:_hide_all()
 placement.align(client.focus, {position = pos, honor_workarea=true})
 c1:set_label(pos)
 end

tests/examples/awful/placement/maximize.lua

@@ -10,6 +10,7 @@ for k, pos in ipairs{ --DOC_HIDE
 local c1 = client.gen_fake {--DOC_HIDE
     x = screen[k].geometry.x+40, --DOC_HIDE
     y = screen[k].geometry.y+40, width=75, height=50, screen=screen[k]} --DOC_HIDE
+    c1:_hide_all() --DOC_HIDE
     placement.maximize(c1, {axis = pos ~= "" and pos or nil}) --DOC_HIDE
 
     if k == 1 then --DOC_HIDE

tests/examples/awful/placement/maximize_horizontally.lua

@@ -8,6 +8,7 @@ screen[1]._resize {width = 128, height = 96} --DOC_HIDE
 local placement = require("awful.placement") --DOC_HIDE
 
 local c = client.gen_fake {x = 45, y = 35, width=40, height=30} --DOC_HIDE
+c:_hide_all() --DOC_HIDE
 placement.maximize_horizontally(c)
 
 assert(c.width + 2*c.border_width == screen[1].geometry.width) --DOC_HIDE

tests/examples/awful/placement/maximize_vertically.lua

@@ -8,6 +8,7 @@ screen[1]._resize {width = 128, height = 96} --DOC_HIDE
 local placement = require("awful.placement") --DOC_HIDE
 
 local c = client.gen_fake {x = 45, y = 35, width=40, height=30} --DOC_HIDE
+c:_hide_all() --DOC_HIDE
 placement.maximize_vertically(c)
 
 assert(c.height+2*c.border_width == screen[1].geometry.height)--DOC_HIDE

tests/examples/awful/placement/next_to.lua

@@ -3,14 +3,14 @@ local awful = { placement = require("awful.placement") }--DOC_HIDE
 screen[1]._resize {x= 0, width = 640, height=200} --DOC_HIDE
 
 local parent_client = client.gen_fake {x = 0, y = 0, width=350, height=70} --DOC_HIDE
-parent_client:_hide() --DOC_HIDE
+parent_client:_hide_all() --DOC_HIDE
 awful.placement.centered(client.focus) --DOC_HIDE
 parent_client:set_label("Parent client") --DOC_HIDE
 
 for _, pos in ipairs{"left", "right", "top", "bottom"} do
     for _, anchor in ipairs{"front", "middle", "back"} do
         local c1 = client.gen_fake {x = 0, y = 0, width=80, height=20} --DOC_HIDE
-        c1:_hide() --DOC_HIDE
+        c1:_hide_all() --DOC_HIDE
         local _,p,a = --DOC_HIDE
         awful.placement.next_to(
             client.focus,

tests/examples/awful/popup/defaultconfig.lua

@@ -0,0 +1,137 @@
+--DOC_GEN_IMAGE
+--DOC_HIDE_ALL
+--DOC_NO_USAGE
+--DOC_NO_DASH
+require("_date")
+local awful     = require("awful")
+local gears     = require("gears")
+local naughty   = require("naughty")
+local wibox     = require("wibox")
+local beautiful = require("beautiful") --DOC_HIDE
+local look      = require("_default_look")
+
+screen[1]._resize {width = 640, height = 340}
+
+-- This example is used to show the various type of wibox awesome provides
+-- and mimic the default config look
+
+look.mypromptbox.text = "Run:"
+
+local c = client.gen_fake {hide_first=true}
+
+c:geometry {
+    x      = 205,
+    y      = 260,
+    height = 60,
+    width  = 230,
+}
+c._old_geo = {c:geometry()}
+c:set_label("A client (window)")
+
+require("gears.timer").run_delayed_calls_now()
+-- The titlebar
+
+c:emit_signal("request::titlebars", "rules", {})--DOC_HIDE
+
+local overlay_w = wibox {
+    bg = "#00000000",
+    visible = true,
+    ontop = true,
+}
+
+awful.placement.maximize(overlay_w)
+
+local canvas = wibox.layout.manual()
+canvas.forced_height = 480
+canvas.forced_width  = 640
+overlay_w:set_widget(canvas)
+
+local function create_info(text, x, y, width, height)
+    canvas:add_at(wibox.widget {
+        {
+            {
+                text = text,
+                align = "center",
+                ellipsize = "none",
+                wrap = "word",
+                widget = wibox.widget.textbox
+            },
+            margins = 10,
+            widget = wibox.container.margin
+        },
+        forced_width  = width,
+        forced_height = height,
+        shape = gears.shape.rectangle,
+        border_width = 1,
+        border_color = beautiful.border_color,
+        bg = "#ffff0055",
+        widget = wibox.container.background
+    }, {x = x, y = y})
+end
+
+local function create_line(x1, y1, x2, y2)
+    return canvas:add_at(wibox.widget {
+        fit = function()
+            return x2-x1+6, y2-y1+6
+        end,
+        draw = function(_, _, cr)
+            cr:set_source_rgb(0,0,0)
+            cr:set_line_width(1)
+            cr:arc(1.5, 1.5, 1.5, 0, math.pi*2)
+            cr:arc(x2-x1+1.5, y2-y1+1.5, 1.5, 0, math.pi*2)
+            cr:fill()
+            cr:move_to(1.5,1.5)
+            cr:line_to(x2-x1+1.5, y2-y1+1.5)
+            cr:stroke()
+        end,
+        layout = wibox.widget.base.make_widget,
+    }, {x=x1, y=y1})
+end
+
+naughty.connect_signal("request::display", function(n)
+    naughty.layout.box {notification = n}
+end)
+
+naughty.notification {
+    title    = "A notification",
+    message  = "With a message! ....",
+    position = "top_right",
+}
+
+create_info("awful.widget.launcher", 0, 70, 135, 30)
+create_info("awful.widget.prompt", 145, 80, 127, 30)
+create_info("awful.widget.taglist", 20, 30, 120, 30)
+create_info("awful.widget.tasklist", 240, 50, 130, 30)
+create_info("wibox.widget.systray", 380, 50, 130, 30)
+create_info("awful.widget.keyboardlayout", 315, 15, 170, 30)
+create_info("wibox.widget.textclock", 480, 130, 140, 30)
+create_info("awful.widget.layoutbox", 490, 170, 150, 30)
+create_info("naughty.layout.box", 450, 90, 130, 30)
+
+create_info("awful.titlebar.widget.iconwidget", 10, 260, 190, 30)
+create_info("awful.titlebar.widget.titlewidget", 90, 225, 190, 30)
+create_info("awful.titlebar.widget.floatingbutton", 150, 190, 205, 30)
+create_info("awful.titlebar.widget.maximizedbutton", 150, 155, 220, 30)
+create_info("awful.titlebar.widget.stickybutton", 200, 125, 195, 30)
+create_info("awful.titlebar.widget.ontopbutton", 390, 210, 200, 30)
+create_info("awful.titlebar.widget.closebutton", 445, 260, 190, 30)
+
+create_line(5, 10, 5, 70) --launcher
+create_line(75, 10, 75, 30) --taglist
+create_line(150, 10, 150, 80) -- prompt
+create_line(550, 65, 550, 90) -- notification
+create_line(305, 10, 305, 50) -- tasklist
+create_line(480, 10, 480, 15) -- keyboard
+create_line(600, 5, 600, 130)  --textclock
+create_line(630, 5, 630, 170) -- layoutbox
+create_line(500, 5, 500, 50) -- systray
+
+create_line(385, 150, 385, 259) -- sticky
+create_line(365, 180, 365, 259) -- maximize
+create_line(345, 215, 345, 259) -- floating
+create_line(405, 235, 405, 259) -- ontop
+create_line(195, 270, 203, 270) -- icon
+create_line(437, 270, 445, 270) -- close
+create_line(245, 250, 245, 259) -- title
+
+--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

tests/examples/awful/template.lua

@@ -39,16 +39,18 @@ if not rawget(screen, "no_outline") then
     for s in screen do
         cr:save()
         -- Draw the screen outline
-        cr:set_source(color("#00000044"))
-        cr:set_line_width(1.5)
-        cr:set_dash({10,4},1)
-        cr:rectangle(s.geometry.x+0.75,s.geometry.y+0.75,s.geometry.width-1.5,s.geometry.height-1.5)
-        cr:stroke()
+        if s._no_outline ~= true then
+            cr:set_source(color("#00000044"))
+            cr:set_line_width(1.5)
+            cr:set_dash({10,4},1)
+            cr:rectangle(s.geometry.x+0.75,s.geometry.y+0.75,s.geometry.width-1.5,s.geometry.height-1.5)
+            cr:stroke()
 
-        -- Draw the workarea outline
-        cr:set_source(color("#00000033"))
-        cr:rectangle(s.workarea.x,s.workarea.y,s.workarea.width,s.workarea.height)
-        cr:stroke()
+            -- Draw the workarea outline
+            cr:set_source(color("#00000033"))
+            cr:rectangle(s.workarea.x,s.workarea.y,s.workarea.width,s.workarea.height)
+            cr:stroke()
+        end
 
         -- Draw the padding outline
         --TODO
@@ -67,7 +69,7 @@ local rect = {x1 = 0 ,y1 = 0 , x2 = 0 , y2 = 0}
 for _, obj in ipairs {drawin, client} do
     for _, d in ipairs(obj.get()) do
         local w = d.get_wibox and d:get_wibox() or d
-        if w and w.geometry then
+        if w and w.geometry and w.visible then
             local geo = w:geometry()
             rect.x1 = math.min(rect.x1, geo.x                                       )
             rect.y1 = math.min(rect.y1, geo.y                                       )
@@ -97,6 +99,7 @@ end
 local function client_widget(c, col, label)
     local geo = c:geometry()
     local bw = c.border_width or beautiful.border_width or 0
+    local bc = c.border_color or beautiful.border_color
 
     local l = wibox.layout.align.vertical()
     l.fill_space = true
@@ -142,7 +145,7 @@ local function client_widget(c, col, label)
             layout = wibox.layout.stack
         },
         border_width = bw,
-        border_color = beautiful.border_color,
+        border_color = bc,
         shape_clip   = true,
         fg           = beautiful.fg_normal or "#000000",
         bg           = col,
@@ -177,7 +180,7 @@ end
 
 for _, d in ipairs(drawin.get()) do
     local w = d.get_wibox and d:get_wibox() or nil
-    if w then
+    if w and w.visible then
         local geo = w:geometry()
         total_area:add_at(w:to_widget(), {x = geo.x, y = geo.y})
     end

tests/examples/awful/titlebar/defaulttitlebar.lua

@@ -0,0 +1,144 @@
+--DOC_GEN_IMAGE
+--DOC_HIDE_ALL
+--DOC_NO_USAGE
+--DOC_NO_DASH
+require("_date")
+local gears     = require("gears")
+local wibox     = require("wibox")
+local beautiful = require("beautiful") --DOC_HIDE
+local look      = require("_default_look")
+
+local offset = 0
+
+screen[1]._resize {width = 640, height = 240, y=offset}
+screen[1]._no_outline = true
+look.mywibox.visible = false
+
+local c = client.gen_fake {hide_first=true}
+
+c:geometry {
+    x      = 205,
+    y      = 110,
+    height = 60,
+    width  = 230,
+}
+c._old_geo = {c:geometry()}
+c:set_label("A client (window)")
+
+require("gears.timer").run_delayed_calls_now()
+
+-- The titlebar
+c:emit_signal("request::titlebars", "rules", {})--DOC_HIDE
+
+local overlay_w = wibox {
+    bg = "#00000000",
+    visible = true,
+    ontop = true,
+    y=0,
+    x=0,
+    width  = screen[1].geometry.width,
+    height = screen[1].geometry.height+offset,
+}
+
+local canvas = wibox.layout.manual()
+canvas.forced_height = 170
+canvas.forced_width  = 640
+overlay_w:set_widget(canvas)
+
+local function create_info(text, x, y, width, height)
+    y = y + offset
+    canvas:add_at(wibox.widget {
+        {
+            {
+                text = text,
+                align = "center",
+                ellipsize = "none",
+                wrap = "word",
+                widget = wibox.widget.textbox
+            },
+            margins = 3,
+            widget = wibox.container.margin
+        },
+        forced_width  = width,
+        forced_height = height,
+        shape = gears.shape.rectangle,
+        border_width = 1,
+        border_color = beautiful.border_color,
+        bg = "#ffff0055",
+        widget = wibox.container.background
+    }, {x = x, y = y})
+end
+
+local function create_section(x1, y, x2, text)
+    canvas:add_at(wibox.widget {
+        fit = function()
+            return x2-x1+6, 10
+        end,
+        draw = function(_, _, cr)
+            cr:set_source_rgb(0.8, 0.6, 1)
+            cr:set_line_width(1)
+            cr:move_to(1.5, 0)
+            cr:line_to(1.5, 10)
+            cr:stroke()
+            cr:move_to(x2-x1-1.5, 0)
+            cr:line_to(x2-x1-1.5, 10)
+            cr:stroke()
+            cr:move_to(1.5, 5)
+            cr:line_to(x2-x1-1.5, 5)
+            cr:stroke()
+        end,
+        layout = wibox.widget.base.make_widget,
+    }, {x=x1, y=y})
+
+    canvas:add_at(wibox.widget {
+        text = text,
+        align = "center",
+        ellipsize = "none",
+        wrap = "word",
+        forced_width = x2-x1,
+        widget = wibox.widget.textbox
+    }, {x=x1, y=y-12})
+
+end
+
+local function create_line(x1, y1, x2, y2)
+    y1, y2 = y1 + offset, y2 + offset
+    return canvas:add_at(wibox.widget {
+        fit = function()
+            return x2-x1+6, y2-y1+6
+        end,
+        draw = function(_, _, cr)
+            cr:set_source_rgb(0,0,0)
+            cr:set_line_width(1)
+            cr:arc(1.5, 1.5, 1.5, 0, math.pi*2)
+            cr:arc(x2-x1+1.5, y2-y1+1.5, 1.5, 0, math.pi*2)
+            cr:fill()
+            cr:move_to(1.5,1.5)
+            cr:line_to(x2-x1+1.5, y2-y1+1.5)
+            cr:stroke()
+        end,
+        layout = wibox.widget.base.make_widget,
+    }, {x=x1, y=y1})
+end
+
+create_info("awful.titlebar.widget.iconwidget", 10, 110, 190, 17)
+create_info("awful.titlebar.widget.titlewidget", 90, 85, 190, 17)
+create_info("awful.titlebar.widget.floatingbutton", 150, 65, 205, 17)
+create_info("awful.titlebar.widget.maximizedbutton", 150, 45, 220, 17)
+create_info("awful.titlebar.widget.stickybutton", 200, 25, 195, 17)
+create_info("awful.titlebar.widget.ontopbutton", 390, 85, 200, 17)
+create_info("awful.titlebar.widget.closebutton", 445, 110, 190, 17)
+
+create_line(385, 40, 385, 109) -- sticky
+create_line(365, 60, 365, 109) -- maximize
+create_line(345, 80, 345, 109) -- floating
+create_line(405, 100, 405, 109) -- ontop
+create_line(195, 120, 203, 120) -- icon
+create_line(437, 120, 445, 120) -- close
+create_line(245, 100, 245, 109) -- title
+
+create_section(205, 185, 205+230, 'wibox.layout.align.horizontal')
+create_section(205, 200, 205+24, '')
+create_section(230, 200, 330, '')
+create_section(330, 200, 435, '')
+--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

tests/examples/awful/wibar/defaultwibar.lua

@@ -0,0 +1,139 @@
+--DOC_GEN_IMAGE
+--DOC_HIDE_ALL
+--DOC_NO_USAGE
+--DOC_NO_DASH
+require("_date")
+local gears     = require("gears")
+local wibox     = require("wibox")
+local beautiful = require("beautiful") --DOC_HIDE
+local look      = require("_default_look")
+
+local offset = 60
+
+screen[1]._resize {width = 640, height = 140, y=offset}
+screen[1]._no_outline = true
+
+-- This example is used to show the various type of wibox awesome provides
+-- and mimic the default config look
+
+look.mypromptbox.text = "Run:"
+
+require("gears.timer").run_delayed_calls_now()
+-- The titlebar
+
+local overlay_w = wibox {
+    bg = "#00000000",
+    visible = true,
+    ontop = true,
+    y=0,
+    x=0,
+    width  = screen[1].geometry.width,
+    height = screen[1].geometry.height+offset,
+}
+
+local canvas = wibox.layout.manual()
+canvas.forced_height = 170
+canvas.forced_width  = 640
+overlay_w:set_widget(canvas)
+
+local function create_info(text, x, y, width, height)
+    y = y + offset
+    canvas:add_at(wibox.widget {
+        {
+            {
+                text = text,
+                align = "center",
+                ellipsize = "none",
+                wrap = "word",
+                widget = wibox.widget.textbox
+            },
+            margins = 3,
+            widget = wibox.container.margin
+        },
+        forced_width  = width,
+        forced_height = height,
+        shape = gears.shape.rectangle,
+        border_width = 1,
+        border_color = beautiful.border_color,
+        bg = "#ffff0055",
+        widget = wibox.container.background
+    }, {x = x, y = y})
+end
+
+local function create_section(x1, y, x2, text)
+    canvas:add_at(wibox.widget {
+        fit = function()
+            return x2-x1+6, 10
+        end,
+        draw = function(_, _, cr)
+            cr:set_source_rgb(0.8, 0.6, 1)
+            cr:set_line_width(1)
+            cr:move_to(1.5, 0)
+            cr:line_to(1.5, 10)
+            cr:stroke()
+            cr:move_to(x2-x1-1.5, 0)
+            cr:line_to(x2-x1-1.5, 10)
+            cr:stroke()
+            cr:move_to(1.5, 5)
+            cr:line_to(x2-x1-1.5, 5)
+            cr:stroke()
+        end,
+        layout = wibox.widget.base.make_widget,
+    }, {x=x1, y=y})
+
+    canvas:add_at(wibox.widget {
+        text = text,
+        align = "center",
+        ellipsize = "none",
+        wrap = "word",
+        forced_width = x2-x1,
+        widget = wibox.widget.textbox
+    }, {x=x1, y=y-12})
+
+end
+
+local function create_line(x1, y1, x2, y2)
+    y1, y2 = y1 + offset, y2 + offset
+    return canvas:add_at(wibox.widget {
+        fit = function()
+            return x2-x1+6, y2-y1+6
+        end,
+        draw = function(_, _, cr)
+            cr:set_source_rgb(0,0,0)
+            cr:set_line_width(1)
+            cr:arc(1.5, 1.5, 1.5, 0, math.pi*2)
+            cr:arc(x2-x1+1.5, y2-y1+1.5, 1.5, 0, math.pi*2)
+            cr:fill()
+            cr:move_to(1.5,1.5)
+            cr:line_to(x2-x1+1.5, y2-y1+1.5)
+            cr:stroke()
+        end,
+        layout = wibox.widget.base.make_widget,
+    }, {x=x1, y=y1})
+end
+
+create_info("awful.widget.launcher", 0, 40, 135, 17)
+create_info("awful.widget.prompt", 145, 15, 127, 17)
+create_info("awful.widget.taglist", 15, 15, 120, 17)
+create_info("awful.widget.tasklist", 240, 40, 130, 17)
+create_info("wibox.widget.systray", 380, 40, 130, 17)
+create_info("awful.widget.keyboardlayout", 315, 15, 170, 17)
+create_info("wibox.widget.textclock", 480, 60, 140, 17)
+create_info("awful.widget.layoutbox", 490, 80, 150, 17)
+
+create_line(5, 10, 5, 40) --launcher
+create_line(75, 10, 75, 15) --taglist
+create_line(150, 10, 150, 15) -- prompt
+create_line(305, 10, 305, 40) -- tasklist
+create_line(480, 10, 480, 15) -- keyboard
+create_line(600, 5, 600, 60)  --textclock
+create_line(630, 5, 630, 80) -- layoutbox
+create_line(500, 5, 500, 40) -- systray
+
+create_section(0, 10, 640, 'wibox.layout.align.horizontal')
+create_section(0, 30, 160, 'align first section (left)')
+create_section(0, 50, 160, 'wibox.layout.fixed.horizontal')
+create_section(165, 30, 460, 'align second section (middle)')
+create_section(465, 30, 640, 'align third section (right)')
+create_section(465, 50, 640, 'wibox.layout.fixed.horizontal')
+--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

tests/examples/screen/client_snap.lua

@@ -0,0 +1,46 @@
+--DOC_GEN_IMAGE --DOC_NO_USAGE --DOC_HIDE_ALL
+
+screen[1]._resize {x = 0, width = 640, height = 480}
+
+
+local awful = {
+    wibar = require("awful.wibar"),
+    tag = require("awful.tag"),
+    tag_layout = require("awful.layout.suit.floating")
+}
+
+
+require("awful.mouse.snap").default_distance = 32
+
+screen[1].padding = {
+    left   = 40,
+    right  = 40,
+    top    = 20,
+    bottom = 20,
+}
+
+local wibar = awful.wibar {
+    position = "top",
+    height   = 24,
+}
+
+awful.tag.add("1", {
+    screen   = screen[1],
+    selected = true,
+    layout   = awful.tag_layout.right,
+    gap      = 20
+})
+
+local clients = {
+    ['client #1'] = client.gen_fake{floating=true, x = 60, y = 60, height = 160, width=200},
+    ['client #2'] = client.gen_fake{floating=true, x = 300, y = 150, height = 160, width=200},
+}
+
+return {
+    factor                = 2    ,
+    show_boxes            = true,
+    draw_wibar            = wibar,
+    draw_clients          = clients,
+    display_screen_info   = false,
+    draw_client_snap      = true, --FIXME
+}

tests/examples/screen/gap_single_client_false.lua

@@ -0,0 +1,42 @@
+--DOC_GEN_IMAGE --DOC_NO_USAGE --DOC_HIDE_ALL
+
+screen[1]._resize {x = 0, width = 640, height = 480}
+
+local awful = {
+    wibar = require("awful.wibar"),
+    tag = require("awful.tag"),
+    tag_layout = require("awful.layout.suit.tile")
+}
+
+screen[1].padding = {
+    left   = 40,
+    right  = 40,
+    top    = 20,
+    bottom = 20,
+}
+
+local wibar = awful.wibar {
+    position = "top",
+    height   = 24,
+}
+
+awful.tag.add("1", {
+    screen            = screen[1],
+    selected          = true,
+    layout            = awful.tag_layout.right,
+    gap               = 20,
+    gap_single_client = false,
+})
+
+local clients = {
+    ['client #1'] = client.gen_fake{},
+}
+
+return {
+    factor                = 2    ,
+    show_boxes            = true,
+    draw_wibar            = wibar,
+    draw_clients          = clients,
+    display_screen_info   = false,
+    draw_gaps             = true,
+}

tests/examples/screen/gap_single_client_true.lua

@@ -0,0 +1,42 @@
+--DOC_GEN_IMAGE --DOC_NO_USAGE --DOC_HIDE_ALL
+
+screen[1]._resize {x = 0, width = 640, height = 480}
+
+local awful = {
+    wibar = require("awful.wibar"),
+    tag = require("awful.tag"),
+    tag_layout = require("awful.layout.suit.tile")
+}
+
+screen[1].padding = {
+    left   = 40,
+    right  = 40,
+    top    = 20,
+    bottom = 20,
+}
+
+local wibar = awful.wibar {
+    position = "top",
+    height   = 24,
+}
+
+awful.tag.add("1", {
+    screen            = screen[1],
+    selected          = true,
+    layout            = awful.tag_layout.right,
+    gap               = 20,
+    gap_single_client = true, -- its the default
+})
+
+local clients = {
+    ['client #1'] = client.gen_fake{},
+}
+
+return {
+    factor                = 2    ,
+    show_boxes            = true,
+    draw_wibar            = wibar,
+    draw_clients          = clients,
+    display_screen_info   = false,
+    draw_gaps             = true,
+}

tests/examples/screen/gaps.lua

@@ -0,0 +1,43 @@
+--DOC_GEN_IMAGE --DOC_NO_USAGE --DOC_HIDE_ALL
+
+screen[1]._resize {x = 0, width = 640, height = 480}
+
+local awful = {
+    wibar = require("awful.wibar"),
+    tag = require("awful.tag"),
+    tag_layout = require("awful.layout.suit.tile")
+}
+
+screen[1].padding = {
+    left   = 40,
+    right  = 40,
+    top    = 20,
+    bottom = 20,
+}
+
+local wibar = awful.wibar {
+    position = "top",
+    height   = 24,
+}
+
+awful.tag.add("1", {
+    screen   = screen[1],
+    selected = true,
+    layout   = awful.tag_layout.right,
+    gap      = 20
+})
+
+local clients = {
+    ['client #1'] = client.gen_fake{},
+    ['client #2'] = client.gen_fake{},
+    ['client #3'] = client.gen_fake{}
+}
+
+return {
+    factor                = 2    ,
+    show_boxes            = true,
+    draw_wibar            = wibar,
+    draw_clients          = clients,
+    display_screen_info   = false,
+    draw_gaps             = true,
+}

tests/examples/screen/gaps2.lua

@@ -0,0 +1,43 @@
+--DOC_GEN_IMAGE --DOC_NO_USAGE --DOC_HIDE_ALL
+
+screen[1]._resize {x = 0, width = 640, height = 480}
+
+local awful = {
+    wibar = require("awful.wibar"),
+    tag = require("awful.tag"),
+    tag_layout = require("awful.layout.suit.tile")
+}
+
+screen[1].padding = {
+    left   = 40,
+    right  = 40,
+    top    = 20,
+    bottom = 20,
+}
+
+local wibar = awful.wibar {
+    position = "top",
+    height   = 24,
+}
+
+awful.tag.add("1", {
+    screen   = screen[1],
+    selected = true,
+    layout   = awful.tag_layout.right,
+    gap      = 50
+})
+
+local clients = {
+    ['client #1'] = client.gen_fake{},
+    ['client #2'] = client.gen_fake{},
+    ['client #3'] = client.gen_fake{}
+}
+
+return {
+    factor                = 2    ,
+    show_boxes            = true,
+    draw_wibar            = wibar,
+    draw_clients          = clients,
+    display_screen_info   = false,
+    draw_gaps             = true,
+}

tests/examples/screen/mfpol.lua

@@ -0,0 +1,53 @@
+--DOC_GEN_IMAGE --DOC_NO_USAGE --DOC_HIDE_ALL
+
+screen[1]._resize {x = 0, width = 640, height = 480}
+
+
+local awful = {
+    wibar = require("awful.wibar"),
+    tag = require("awful.tag"),
+    tag_layout = require("awful.layout.suit.tile")
+}
+
+function awful.spawn(_, args)
+    local c = client.gen_fake{}
+    c:tags({args.tag})
+    assert(#c:tags() == 1)
+    assert(c:tags()[1] == args.tag)
+end
+
+screen[1].padding = {
+    left   = 40,
+    right  = 40,
+    top    = 20,
+    bottom = 20,
+}
+
+local wibar = awful.wibar {
+    position = "top",
+    height   = 24,
+}
+
+awful.tag.add("1", {
+    screen              = screen[1],
+    selected            = true,
+    layout              = awful.tag_layout.right,
+    gap                 = 5,
+    master_width_factor = 0.66,
+    master_fill_policy  = "master_width_factor"
+})
+
+local clients = {
+    ['Single client'] = client.gen_fake{},
+}
+for _,c in ipairs(clients) do
+    c:tags{"1"}
+end
+
+return {
+    factor                = 2    ,
+    show_boxes            = true,
+    draw_wibar            = wibar,
+    draw_clients          = clients,
+    display_screen_info   = false,
+}

tests/examples/screen/mfpol2.lua

@@ -0,0 +1,53 @@
+--DOC_GEN_IMAGE --DOC_NO_USAGE --DOC_HIDE_ALL
+
+screen[1]._resize {x = 0, width = 640, height = 480}
+
+
+local awful = {
+    wibar = require("awful.wibar"),
+    tag = require("awful.tag"),
+    tag_layout = require("awful.layout.suit.tile")
+}
+
+function awful.spawn(_, args)
+    local c = client.gen_fake{}
+    c:tags({args.tag})
+    assert(#c:tags() == 1)
+    assert(c:tags()[1] == args.tag)
+end
+
+screen[1].padding = {
+    left   = 40,
+    right  = 40,
+    top    = 20,
+    bottom = 20,
+}
+
+local wibar = awful.wibar {
+    position = "top",
+    height   = 24,
+}
+
+awful.tag.add("1", {
+    screen              = screen[1],
+    selected            = true,
+    layout              = awful.tag_layout.right,
+    gap                 = 5,
+    master_width_factor = 0.66,
+    master_fill_policy  = "expand"
+})
+
+local clients = {
+    ['Single client'] = client.gen_fake{},
+}
+for _,c in ipairs(clients) do
+    c:tags{"1"}
+end
+
+return {
+    factor                = 2    ,
+    show_boxes            = true,
+    draw_wibar            = wibar,
+    draw_clients          = clients,
+    display_screen_info   = false,
+}

tests/examples/screen/mwfact.lua

@@ -0,0 +1,55 @@
+--DOC_GEN_IMAGE --DOC_NO_USAGE --DOC_HIDE_ALL
+
+screen[1]._resize {x = 0, width = 640, height = 480}
+
+
+local awful = {
+    wibar = require("awful.wibar"),
+    tag = require("awful.tag"),
+    tag_layout = require("awful.layout.suit.tile")
+}
+
+function awful.spawn(_, args)
+    local c = client.gen_fake{}
+    c:tags({args.tag})
+    assert(#c:tags() == 1)
+    assert(c:tags()[1] == args.tag)
+end
+
+screen[1].padding = {
+    left   = 40,
+    right  = 40,
+    top    = 20,
+    bottom = 20,
+}
+
+local wibar = awful.wibar {
+    position = "top",
+    height   = 24,
+}
+
+awful.tag.add("1", {
+    screen              = screen[1],
+    selected            = true,
+    layout              = awful.tag_layout.right,
+    gap                 = 5,
+    master_width_factor = 0.66
+})
+
+local clients = {
+    ['master #1 (66%)'] = client.gen_fake{},
+    ['slave  #1 (33%)'] = client.gen_fake{},
+    ['slave  #2 (33%)'] = client.gen_fake{}
+}
+for _,c in ipairs(clients) do
+    c:tags{"1"}
+end
+
+return {
+    factor                = 2    ,
+    show_boxes            = true,
+    draw_wibar            = wibar,
+    draw_clients          = clients,
+    display_screen_info   = false,
+    draw_mwfact           = true,
+}

tests/examples/screen/mwfact2.lua

@@ -0,0 +1,58 @@
+--DOC_GEN_IMAGE --DOC_NO_USAGE --DOC_HIDE_ALL
+
+screen[1]._resize {x = 0, width = 640, height = 480}
+
+
+local awful = {
+    wibar = require("awful.wibar"),
+    tag = require("awful.tag"),
+    tag_layout = require("awful.layout.suit.tile")
+}
+
+function awful.spawn(_, args)
+    local c = client.gen_fake{}
+    c:tags({args.tag})
+    assert(#c:tags() == 1)
+    assert(c:tags()[1] == args.tag)
+end
+
+screen[1].padding = {
+    left   = 40,
+    right  = 40,
+    top    = 20,
+    bottom = 20,
+}
+
+local wibar = awful.wibar {
+    position = "top",
+    height   = 24,
+}
+
+awful.tag.add("1", {
+    screen              = screen[1],
+    selected            = true,
+    layout              = awful.tag_layout.right,
+    gap                 = 5,
+    master_width_factor = 0.6,
+    column_count        = 2
+})
+
+local clients = {
+    ['master #1 (60%)'] = client.gen_fake{},
+    ['#1 (20%)'] = client.gen_fake{},
+    ['#2 (20%)'] = client.gen_fake{},
+    ['#3 (20%)'] = client.gen_fake{},
+    ['#4 (20%)'] = client.gen_fake{}
+}
+for _,c in ipairs(clients) do
+    c:tags{"1"}
+end
+
+return {
+    factor                = 2    ,
+    show_boxes            = true,
+    draw_wibar            = wibar,
+    draw_clients          = clients,
+    display_screen_info   = false,
+    draw_mwfact           = true,
+}

tests/examples/screen/struts.lua

@@ -0,0 +1,60 @@
+--DOC_GEN_IMAGE --DOC_NO_USAGE --DOC_ASTERISK
+
+screen[1]._resize {x = 0, width = 640, height = 480} --DOC_HIDE
+
+local awful = { --DOC_HIDE
+    wibar = require("awful.wibar"), --DOC_HIDE
+    tag = require("awful.tag"), --DOC_HIDE
+    tag_layout = require("awful.layout.suit.tile") --DOC_HIDE
+}
+
+    -- Wibars and docked clients are the main users of the struts.
+    local wibar = awful.wibar {
+        position = "top",
+        height   = 24, -- this will set the wibar won :struts() to top=24
+    }
+
+awful.tag.add("1", { --DOC_HIDE
+    screen   = screen[1], --DOC_HIDE
+    selected = true, --DOC_HIDE
+    layout   = awful.tag_layout.right, --DOC_HIDE
+    gap      = 4 --DOC_HIDE
+}) --DOC_HIDE
+
+local c = client.gen_fake{} --DOC_HIDE
+
+    -- This is the client in the bottom left.
+    c.name     = "w. struts"
+    c.floating = true
+
+--DOC_NEWLINE
+
+    c:geometry {
+        x      = 0,
+        y      = 380,
+        height = 100,
+        width  = 100,
+    }
+
+--DOC_NEWLINE
+
+    c:struts {
+        left   = 100,
+        bottom = 100
+    }
+
+local clients = { --DOC_HIDE
+    ['w. struts'] = c, --DOC_HIDE
+    ['client #1'] = client.gen_fake{}, --DOC_HIDE
+    ['client #2'] = client.gen_fake{}, --DOC_HIDE
+    ['client #3'] = client.gen_fake{}, --DOC_HIDE
+} --DOC_HIDE
+
+return { --DOC_HIDE
+    factor                = 2   , --DOC_HIDE
+    show_boxes            = true, --DOC_HIDE
+    draw_wibar            = wibar, --DOC_HIDE
+    draw_clients          = clients, --DOC_HIDE
+    display_screen_info   = false, --DOC_HIDE
+    draw_struts           = true, --DOC_HIDE
+} --DOC_HIDE

tests/examples/screen/template.lua

@@ -76,12 +76,13 @@ local function stripe_pat(col, angle, line_width, spacing)
 end
 
 local colors = {
-    geometry    = "#000000",
-    workarea    = "#0000ff",
-    tiling_area = "#ff0000",
-    padding_area= "#ff0000",
-    wibar       = "#000000",
+    geometry      = "#000000",
+    workarea      = "#0000ff",
+    tiling_area   = "#ff0000",
+    padding_area  = "#ff0000",
+    wibar         = "#000000",
     tiling_client = "#ff0000",
+    gaps          = "#9900ff",
 }
 
 local function draw_area(_, rect, name, offset, highlight)
@@ -142,6 +143,7 @@ local function write_on_area_middle(rect, text, offset)
     cr:show_layout(playout)
 end
 
+-- For clients/wibars with struts only.
 local function draw_struct(_, struct, name, offset, label)
     draw_solid_area(_, struct, name, offset)
     if type(label) == 'string' then
@@ -149,6 +151,15 @@ local function draw_struct(_, struct, name, offset, label)
     end
 end
 
+-- For floating or tiled clients.
+local function draw_client(_, c, name, offset, label, alpha)
+    draw_solid_area(_, c, name, offset, alpha)
+    if type(label) == 'string' then
+        write_on_area_middle(c, label, offset)
+    end
+end
+
+
 local function compute_ruler(_, rect, name)
     table.insert(hrulers, {
         label = name, x = rect.x, width = rect.width
@@ -176,7 +187,37 @@ end
 
 local dx = 5
 
-local function show_ruler_label(offset, padding, ruler, playout)
+local playout, playout_height = nil, nil
+
+local function get_playout()
+    if playout then return playout end
+
+    local pctx    = PangoCairo.font_map_get_default():create_context()
+    playout       = Pango.Layout.new(pctx)
+    local pdesc   = Pango.FontDescription()
+    pdesc:set_absolute_size(11 * Pango.SCALE)
+    playout:set_font_description(pdesc)
+
+    return playout
+end
+
+local function get_text_height()
+    if playout_height then return playout_height end
+
+    local l = get_playout()
+    local attr, parsed = Pango.parse_markup("<b>GeometryWorkareaPaddingMargins</b>", -1, 0)
+    l.attributes, l.text = attr, parsed
+
+    local _, logical = playout:get_pixel_extents()
+
+    playout_height = logical.height
+
+    return playout_height
+end
+
+local function show_ruler_label(offset, padding, ruler, playout2)
+    if not ruler.label then return end
+
     local lbl
 
     if ruler.x then
@@ -187,13 +228,85 @@ local function show_ruler_label(offset, padding, ruler, playout)
             ruler.y.."    height = "..ruler.height.."</i>"
     end
 
+    local attr, parsed = Pango.parse_markup(lbl, -1, 0)
+    playout2.attributes, playout2.text = attr, parsed
+    local _, logical = playout2:get_pixel_extents()
+    cr:move_to((offset.x - logical.width) /2, offset.y+padding)
+    cr:show_layout(playout2)
+end
+
+local function show_aligned_label(dx2, offset, padding, ruler)
+    local lbl
+
+    if ruler.x then
+        lbl = ruler.width
+    else
+        lbl = ruler.height
+    end
+
     local attr, parsed = Pango.parse_markup(lbl, -1, 0)
     playout.attributes, playout.text = attr, parsed
     local _, logical = playout:get_pixel_extents()
-    cr:move_to((offset.x - logical.width) /2, offset.y+padding)
+
+    if ruler.x then
+        local off = (ruler.width*factor - logical.width)/2
+        cr:move_to(ruler.x*factor+off, offset.y+padding)
+    else
+        local off = (ruler.height*factor - logical.width)/2
+        cr:move_to(-ruler.y*factor-dx2*factor-off, padding)
+    end
+
     cr:show_layout(playout)
 end
 
+local function draw_vruler(s, dx2, sx, ruler, layer)
+    local pad = 5+(layer-1)*dx2
+    cr:set_source(color(ruler.color or (colors[ruler.label].."66")))
+    cr:move_to(sx+layer*dx2, ruler.y*factor)
+    cr:line_to(sx+layer*dx2, ruler.y*factor+ruler.height*factor)
+    cr:stroke()
+
+    cr:move_to(sx+layer*dx2-2.5,ruler.y*factor)
+    cr:line_to(sx+layer*dx2+2.5, ruler.y*factor)
+    cr:stroke()
+
+    cr:move_to(sx+layer*dx2-2.5,ruler.y*factor+ruler.height*factor)
+    cr:line_to(sx+layer*dx2+2.5, ruler.y*factor+ruler.height*factor)
+    cr:stroke()
+
+    cr:save()
+    cr:move_to(sx+layer*dx2-2.5,ruler.y*factor)
+    cr:rotate(-math.pi/2)
+    if ruler and ruler.label then
+        show_ruler_label({x=-s.geometry.height*factor, y=sx}, pad, ruler, get_playout())
+    elseif ruler and ruler.align then
+        show_aligned_label(dx2, {x=s.geometry.width*factor, y=0}, pad, ruler)
+    end
+    cr:restore()
+end
+
+local function draw_hruler(s, dx2, sy, ruler, layer)
+    local pad = 10+(layer-1)*(dx2 or 0)
+    cr:set_source(color(ruler.color or (colors[ruler.label].."66")))
+    cr:move_to(ruler.x*factor, sy+pad)
+    cr:line_to(ruler.x*factor+ruler.width*factor, sy+pad)
+    cr:stroke()
+
+    cr:move_to(ruler.x*factor, sy+pad-2.5)
+    cr:line_to(ruler.x*factor, sy+pad+2.5)
+    cr:stroke()
+
+    cr:move_to(ruler.x*factor+ruler.width*factor, sy+pad-2.5)
+    cr:line_to(ruler.x*factor+ruler.width*factor, sy+pad+2.5)
+    cr:stroke()
+
+    if ruler and ruler.label then
+        show_ruler_label({x=s.geometry.width*factor, y=sy}, pad, ruler, get_playout())
+    elseif ruler and ruler.align then
+        show_aligned_label(dx2, {x=s.geometry.width*factor, y=sy}, pad, ruler)
+    end
+end
+
 local function draw_rulers(s)
     -- The table has a maximum of 4 entries, the sort algorithm is irrelevant.
     while not bubble_sort(hrulers, "x", "width" ) do end
@@ -205,67 +318,290 @@ local function draw_rulers(s)
     local sx = (s.geometry.x+s.geometry.width )*factor
     local sy = (s.geometry.y+s.geometry.height)*factor
 
-
-    local pctx    = PangoCairo.font_map_get_default():create_context()
-    local playout = Pango.Layout.new(pctx)
-    local pdesc   = Pango.FontDescription()
-    pdesc:set_absolute_size(11 * Pango.SCALE)
-    playout:set_font_description(pdesc)
-    local attr, parsed = Pango.parse_markup("<b>GeometryWorkareaPaddingMargins</b>", -1, 0)
-    playout.attributes, playout.text = attr, parsed
-    local _, logical = playout:get_pixel_extents()
-    dx = logical.height + 10
+    dx = get_text_height() + 10
 
     for k, ruler in ipairs(vrulers) do
-        local pad = 5+(k-1)*dx
-        cr:set_source(color(colors[ruler.label].."66"))
-        cr:move_to(sx+k*dx, ruler.y*factor)
-        cr:line_to(sx+k*dx, ruler.y*factor+ruler.height*factor)
-        cr:stroke()
-
-        cr:move_to(sx+k*dx-2.5,ruler.y*factor)
-        cr:line_to(sx+k*dx+2.5, ruler.y*factor)
-        cr:stroke()
-
-        cr:move_to(sx+k*dx-2.5,ruler.y*factor+ruler.height*factor)
-        cr:line_to(sx+k*dx+2.5, ruler.y*factor+ruler.height*factor)
-        cr:stroke()
-
-        cr:save()
-        cr:move_to(sx+k*dx-2.5,ruler.y*factor)
-        cr:rotate(-math.pi/2)
-        show_ruler_label({x=-s.geometry.height*factor, y=sx}, pad, ruler, playout)
-        cr:restore()
+        draw_vruler(s, dx, sx, ruler, k)
     end
 
-
     for k, ruler in ipairs(hrulers) do
-        local pad = 10+(k-1)*dx
-        cr:set_source(color(colors[ruler.label].."66"))
-        cr:move_to(ruler.x*factor, sy+pad)
-        cr:line_to(ruler.x*factor+ruler.width*factor, sy+pad)
-        cr:stroke()
-
-        cr:move_to(ruler.x*factor, sy+pad-2.5)
-        cr:line_to(ruler.x*factor, sy+pad+2.5)
-        cr:stroke()
-
-        cr:move_to(ruler.x*factor+ruler.width*factor, sy+pad-2.5)
-        cr:line_to(ruler.x*factor+ruler.width*factor, sy+pad+2.5)
-        cr:stroke()
-
-        show_ruler_label({x=s.geometry.width*factor, y=sy}, pad, ruler, playout)
+        draw_hruler(s, dx, sy, ruler, k)
     end
 end
 
+local tr_x, tr_y = 0, 0
+
+-- Not a very efficient way to do this, but at least it is simple.
+local function deduplicate_gaps(gaps)
+    for _, gap1 in ipairs(gaps) do
+        for k, gap2 in ipairs(gaps) do
+            if gap1[2] == gap2[1] then
+                gap1[2] = gap2[2]
+                table.remove(gaps, k)
+                return true
+            elseif gap2[1] >= gap1[1] and gap2[2] <= gap1[2] and gap1 ~= gap2 then
+                table.remove(gaps, k)
+                return true
+            elseif gap1[1] == gap2[1] and  gap2[2] == gap2[2] and gap1 ~= gap2 then
+                table.remove(gaps, k)
+                return true
+            end
+        end
+    end
+
+
+    return false
+end
+
+local function get_gaps(s)
+    local ret = {vertical={gaps={}, content={}}, horizontal={gaps={}, content={}}}
+
+    local gap = s.selected_tag.gap
+
+    if gap == 0 then return ret end
+
+    if s.selected_tag.gap_single_client == false and #s.tiled_clients == 1 then
+        return ret
+    end
+
+    -- First, get all gaps.
+    for _, c in ipairs(s.tiled_clients) do
+        local bw = c.border_width
+        table.insert(ret.horizontal.gaps, {c.x-gap     , c.x             })
+        table.insert(ret.vertical.gaps  , {c.y-gap     , c.y             })
+        table.insert(ret.horizontal.gaps, {c.x+c.width +2*bw, c.x+c.width+gap +2*bw})
+        table.insert(ret.vertical.gaps  , {c.y+c.height+2*bw, c.y+c.height+gap+2*bw})
+    end
+
+    -- Merge continuous gaps.
+    while deduplicate_gaps(ret.vertical.gaps  ) do end
+    while deduplicate_gaps(ret.horizontal.gaps) do end
+
+    return ret
+end
+
+local function evaluate_translation(draw_gaps, draw_struts, draw_mwfact, draw_client_snap)
+    for s in screen do
+        if (draw_gaps and s.selected_tag and s.selected_tag.gap > 0) then
+            local gaps = get_gaps(s)
+
+            -- Only add the space if there is something to display.
+            if #gaps.horizontal.gaps > 0 then
+                tr_y = math.max(tr_y, 3 * get_text_height())
+            end
+
+            if #gaps.vertical.gaps > 0 then
+                tr_x = math.max(tr_x, 2 * get_text_height())
+            end
+        end
+
+        if draw_client_snap or draw_struts then
+            tr_y = math.max(tr_y, 3 * get_text_height())
+            tr_x = math.max(tr_x, 2 * get_text_height())
+        end
+
+        if draw_mwfact then
+            tr_y = math.max(tr_y, 3 * get_text_height())
+        end
+    end
+end
+
+local function translate()
+    cr:translate(tr_x, tr_y * 0.66)
+end
+
+local function draw_gaps(s)
+    cr:translate(-tr_x, -tr_y)
+
+    local gaps = get_gaps(s)
+
+    local offset = s.tiling_area
+
+    for _, hgap in ipairs(gaps.horizontal.gaps) do
+        draw_hruler(
+            s,
+            offset.x,
+            get_text_height(),
+            {
+                x     = offset.x+hgap[1]+tr_x,
+                width = math.ceil(hgap[2]-hgap[1]),
+                label = nil,
+                color = colors.gaps.."66",
+                align = true
+            },
+            1
+         )
+    end
+
+    for _, vgap in ipairs(gaps.vertical.gaps) do
+        draw_vruler(
+            s,
+            get_text_height()*1.5,
+            0,
+            {
+                y      = offset.y+vgap[1]+tr_y,
+                height = math.ceil(vgap[2]-vgap[1]),
+                label  = nil,
+                color  = colors.gaps.."66",
+                align  = true
+            },
+            1
+        )
+    end
+
+    cr:translate(tr_x, tr_y)
+end
+
+local function has_struts(s)
+    for k, v in pairs(s.workarea) do
+        if s.geometry[k] ~= v then
+            return true
+        end
+    end
+
+    return false
+end
+
+local function draw_struts(s)
+    local left   = s.workarea.x - s.geometry.x
+    local right  = (s.geometry.x + s.geometry.width) - (s.workarea.x + s.workarea.width)
+    local top    = s.workarea.y - s.geometry.y
+    local bottom = (s.geometry.y + s.geometry.height) - (s.workarea.y + s.workarea.height)
+
+    cr:translate(-tr_x, -tr_y)
+
+    if left > 0 then
+        draw_hruler(
+            s,
+            0,
+            get_text_height(),
+            {x = s.geometry.x+tr_x*2, width = left, color = colors.gaps.."66", align = true},
+            1
+        )
+    end
+
+    if top > 0 then
+        draw_vruler(
+            s,
+            get_text_height()*1.5,
+            0,
+            {y=s.geometry.y+tr_y*(1/factor), height = top, color = colors.gaps.."66", align = true},
+            1
+        )
+    end
+
+    if right > 0 then
+        draw_hruler(
+            s,
+            0,
+            get_text_height(),
+            {x = s.geometry.x, width = left, color = colors.gaps.."66", align = true},
+            1
+        )
+    end
+
+    if bottom > 0 then
+        draw_vruler(
+            s,
+            get_text_height()*1.5,
+            0,
+            {
+                y      = s.geometry.y+tr_y*(1/factor)+s.geometry.height - bottom,
+                height = bottom,
+                color  = colors.gaps.."66",
+                align  = true
+            },
+            1
+        )
+    end
+
+    cr:translate(tr_x, tr_y)
+end
+
+local function draw_mwfact(s)
+    cr:translate(-tr_x, -tr_y)
+
+    local mwfact = s.selected_tag.master_width_factor
+
+    local offset = s.tiling_area.x
+    local width  = s.tiling_area.width
+
+    local w1, w2 = math.ceil(width*mwfact), math.ceil(width*(1-mwfact))
+
+    draw_hruler(s, offset, get_text_height(), {x=offset,width=w1,color = colors.gaps.."66", align=true}, 1)
+    draw_hruler(s, offset, get_text_height(), {x=offset+w1,width=w2,color = colors.gaps.."66", align=true}, 1)
+
+    cr:translate(tr_x, tr_y)
+end
+
+local function draw_client_snap(s)
+    cr:translate(-tr_x, -tr_y)
+
+    local snap_areas = {
+        vertical  ={},
+        horizontal={}
+    }
+
+    local d = require("awful.mouse.snap").default_distance
+
+    for _, c in ipairs(s.clients) do
+        if c.floating then
+            table.insert(snap_areas.horizontal, {c.x-d, c.x})
+            table.insert(snap_areas.horizontal, {c.x+c.width, c.x+c.width+d})
+            table.insert(snap_areas.vertical  , {c.y-d, c.y})
+            table.insert(snap_areas.vertical  , {c.y+c.height, c.y+c.height+d})
+        end
+    end
+
+    while deduplicate_gaps(snap_areas.horizontal) do end
+    while deduplicate_gaps(snap_areas.vertical  ) do end
+
+    --FIXME
+    --[[for _, hgap in ipairs(snap_areas.horizontal) do
+        draw_hruler(
+            s,
+            0,
+            get_text_height(),
+            {x=tr_x+s.workarea.x+hgap[1],width=hgap[2]-hgap[1],label="gaps"},
+            1
+        )
+    end
+
+    for _, vgap in ipairs(snap_areas.vertical) do
+        draw_vruler(
+            s,
+            get_text_height()*1.5,
+            0,
+            {y=tr_y+vgap[1],height=vgap[2]-vgap[1],label="gaps"},
+            1
+        )
+    end]]--
+
+    cr:translate(tr_x, tr_y)
+end
+
+-- local function draw_screen_snap(s)
+--     local d = require("awful.mouse.snap").aerosnap_distance
+--
+--
+--     local proxy = {
+--         x      = c.x - sd,
+--         y      = c.y - sd,
+--         width  = c.width + 2*sd,
+--         height = c.height + 2*sd,
+--     }
+--
+--     draw_client(s, proxy, 'gaps', (k-1)*10, nil, "11")
+-- end
+
 local function draw_info(s)
     cr:set_source_rgb(0, 0, 0)
 
-    local pctx    = PangoCairo.font_map_get_default():create_context()
-    local playout = Pango.Layout.new(pctx)
-    local pdesc   = Pango.FontDescription()
+    local pctx     = PangoCairo.font_map_get_default():create_context()
+    local playout2 = Pango.Layout.new(pctx)
+    local pdesc    = Pango.FontDescription()
     pdesc:set_absolute_size(11 * Pango.SCALE)
-    playout:set_font_description(pdesc)
+    playout2:set_font_description(pdesc)
 
     local rows = {
         "primary", "index", "geometry", "dpi", "dpi range", "outputs"
@@ -298,13 +634,13 @@ local function draw_info(s)
     -- Get the extents of the longest label.
     for k, label in ipairs(rows) do
         local attr, parsed = Pango.parse_markup(label..":", -1, 0)
-        playout.attributes, playout.text = attr, parsed
-        local _, logical = playout:get_pixel_extents()
+        playout2.attributes, playout2.text = attr, parsed
+        local _, logical = playout2:get_pixel_extents()
         col1_width = math.max(col1_width, logical.width+10)
 
         attr, parsed = Pango.parse_markup(values[k], -1, 0)
-        playout.attributes, playout.text = attr, parsed
-        _, logical = playout:get_pixel_extents()
+        playout2.attributes, playout2.text = attr, parsed
+        _, logical = playout2:get_pixel_extents()
         col2_width = math.max(col2_width, logical.width+10)
 
         height = math.max(height, logical.height)
@@ -316,15 +652,15 @@ local function draw_info(s)
     -- Draw everything.
     for k, label in ipairs(rows) do
         local attr, parsed = Pango.parse_markup(label..":", -1, 0)
-        playout.attributes, playout.text = attr, parsed
+        playout2.attributes, playout2.text = attr, parsed
         cr:move_to(dx2, dy)
-        cr:show_layout(playout)
+        cr:show_layout(playout2)
 
         attr, parsed = Pango.parse_markup(values[k], -1, 0)
-        playout.attributes, playout.text = attr, parsed
-        local _, logical = playout:get_pixel_extents()
+        playout2.attributes, playout2.text = attr, parsed
+        local _, logical = playout2:get_pixel_extents()
         cr:move_to( dx2+col1_width+5, dy)
-        cr:show_layout(playout)
+        cr:show_layout(playout2)
 
         dy = dy + 5 + logical.height
     end
@@ -344,11 +680,21 @@ for _=1, screen.count() do
     compute_ruler(s, s.geometry, "geometry")
 end
 
+-- If there is some rulers on the left/top, add a global translation.
+evaluate_translation(
+    args.draw_gaps,
+    args.draw_struts,
+    args.draw_mwfact,
+    args.draw_client_snap
+)
+
 -- Get the final size of the image.
 local sew, seh = screen._get_extents()
 sew, seh = sew/args.factor + (screen.count()-1)*10+2, seh/args.factor+2
 
-sew,seh=sew+100,seh+100
+sew, seh = sew + tr_x, seh + 0.66*tr_y
+
+sew, seh = sew + 5*get_text_height(), seh + 5*get_text_height()
 
 img = cairo.SvgSurface.create(image_path..".svg", sew, seh)
 cr  = cairo.Context(img)
@@ -356,10 +702,14 @@ cr  = cairo.Context(img)
 cr:set_line_width(1.5)
 cr:set_dash({10,4},1)
 
+-- Instead of adding origin offset everywhere, translate the viewport.
+translate()
+
 -- Draw the various areas.
 for k=1, screen.count() do
     local s = screen[1]
 
+
     -- The outer geometry.
     draw_area(s, s.geometry, "geometry", (k-1)*10, args.highlight_geometry)
 
@@ -381,17 +731,68 @@ for k=1, screen.count() do
         draw_struct(s, args.draw_wibar, 'wibar', (k-1)*10, 'Wibar')
     end
 
+    local skip_gaps = s.selected_tag
+        and s.selected_tag.gap_single_client == false
+        and #s.tiled_clients == 1
+
+    local sd = require("awful.mouse.snap").default_distance
+
     -- Draw clients.
     if args.draw_clients then
         for label,c in pairs(args.draw_clients) do
-            draw_struct(s, c, 'tiling_client', (k-1)*10, label)
+            local gap = c:tags()[1].gap
+            if args.draw_gaps and gap > 0 and (not c.floating) and not skip_gaps then
+                local proxy = {
+                    x      = c.x - gap,
+                    y      = c.y - gap,
+                    width  = c.width + 2*gap,
+                    height = c.height + 2*gap,
+                }
+
+                draw_client(s, proxy, 'gaps', (k-1)*10, nil, "11")
+            elseif args.draw_client_snap and c.floating then
+                local proxy = {
+                    x      = c.x - sd,
+                    y      = c.y - sd,
+                    width  = c.width + 2*sd,
+                    height = c.height + 2*sd,
+                }
+
+                draw_client(s, proxy, 'gaps', (k-1)*10, nil, "11")
+            end
+
+            draw_client(s, c, 'tiling_client', (k-1)*10, label)
         end
     end
 
+    if args.draw_struts and has_struts(s) then
+        draw_struts(s)
+    end
+
     -- Draw the informations.
     if args.display_screen_info ~= false then
         draw_info(s)
     end
+
+    -- Draw the useless gaps.
+    if args.draw_gaps and not skip_gaps then
+        draw_gaps(s)
+    end
+
+    -- Draw the useless gaps.
+    if args.draw_mwfact then
+        draw_mwfact(s)
+    end
+
+    -- Draw the snapping areas of floating clients.
+    if args.draw_client_snap then
+        draw_client_snap(s)
+    end
+
+    -- Draw the screen edge areas.
+    --if args.draw_screen_snap then
+    --    draw_screen_snap(s)
+    --end
 end
 
 img:finish()

tests/examples/sequences/client/screen.lua

@@ -0,0 +1,46 @@
+ --DOC_GEN_IMAGE --DOC_NO_USAGE --DOC_ASTERISK
+local module = ... --DOC_HIDE
+require("ruled.client") --DOC_HIDE
+local awful = {tag = require("awful.tag"), layout = require("awful.layout")} --DOC_HIDE
+awful.placement = require("awful.placement") --DOC_HIDE
+require("awful.ewmh") --DOC_HIDE
+screen[1]:fake_resize(0, 0, 800, 480) --DOC_HIDE
+screen.fake_add(830, 0, 800, 480).outputs = {["eVGA1"] = {mm_height=50, mm_width=80 }} --DOC_HIDE
+screen.fake_add(1660, 0, 800, 480).outputs = {["DVI1" ] = {mm_height=50, mm_width=80 }} --DOC_HIDE
+awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, screen[1], awful.layout.suit.corner.nw) --DOC_HIDE
+awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, screen[2], awful.layout.suit.corner.nw) --DOC_HIDE
+awful.tag({ "1", "2", "3", "4", "5", "6", "7", "8", "9" }, screen[3], awful.layout.suit.corner.nw) --DOC_HIDE
+
+function awful.spawn(name) --DOC_HIDE
+    client.gen_fake{class = name, name = name, x = 2094, y=10, width = 60, height =50, screen=screen[3]} --DOC_HIDE
+end --DOC_HIDE
+
+
+--DOC_NEWLINE
+
+module.add_event("Spawn a client on screen #3", function() --DOC_HIDE
+    -- Move the mouse to screen 3
+    mouse.coords {x = 1800, y = 100 }
+    assert(mouse.screen == screen[3]) --DOC_HIDE
+
+    --DOC_NEWLINE
+
+    -- Spawn a client on screen #3
+    awful.spawn("firefox")
+
+    assert(client.get()[1].screen == screen[3]) --DOC_HIDE
+end) --DOC_HIDE
+
+--DOC_NEWLINE
+module.display_tags() --DOC_HIDE
+
+module.add_event("Move to screen #2", function() --DOC_HIDE
+    client.get()[1].screen = screen[2]
+end) --DOC_HIDE
+
+module.display_tags() --DOC_HIDE
+
+module.execute { display_screen = true , display_clients     = true, --DOC_HIDE
+                 display_label  = false, display_client_name = true, --DOC_HIDE
+                 display_mouse  = true , --DOC_HIDE
+} --DOC_HIDE

tests/examples/sequences/client/sticky.lua

@@ -0,0 +1,31 @@
+--DOC_GEN_IMAGE --DOC --DOC_NO_USAGE --DOC_ASTERISK
+local module = ... --DOC_HIDE
+local awful = {tag = require("awful.tag"), layout = require("awful.layout") } --DOC_HIDE
+screen[1]._resize {x = 0, width = 128, height = 96} --DOC_HIDE
+
+
+function awful.spawn(_) --DOC_HIDE
+    local c = client.gen_fake{x = 10, y = 10, height=50, width=50} --DOC_HIDE
+    c:tags{screen[1].tags[1]} --DOC_HIDE
+end --DOC_HIDE
+
+awful.tag({ "one", "two", "three", "four", "five" }, screen[1]) --DOC_HIDE
+
+module.add_event("Add a client", function() --DOC_HIDE
+    -- Add a client.
+    awful.spawn("xterm")
+    assert(#screen[1].clients == 1) --DOC_HIDE
+end) --DOC_HIDE
+
+module.display_tags() --DOC_HIDE
+
+--DOC_NEWLINE
+
+module.add_event("Set sticky = true", function() --DOC_HIDE
+    -- Set sticky = true
+    screen[1].clients[1].sticky = true
+end) --DOC_HIDE
+
+module.display_tags() --DOC_HIDE
+
+module.execute {show_empty = true} --DOC_HIDE

tests/examples/sequences/tag/column_count.lua

@@ -0,0 +1,57 @@
+ --DOC_GEN_IMAGE --DOC --DOC_NO_USAGE
+local module = ... --DOC_HIDE
+local awful = {tag = require("awful.tag"), layout = require("awful.layout") } --DOC_HIDE
+screen[1]._resize {x = 0, width = 128, height = 96} --DOC_HIDE
+
+
+function awful.spawn(_, args) --DOC_HIDE
+    local c = client.gen_fake{} --DOC_HIDE
+    c:tags({args.tag}) --DOC_HIDE
+    assert(#c:tags() == 1) --DOC_HIDE
+    assert(c:tags()[1] == args.tag) --DOC_HIDE
+end --DOC_HIDE
+
+module.add_event("Create differing column count tags", function() --DOC_HIDE
+    -- Create a tag with column count of 1 and tag with count of 2
+    awful.tag.add("1 column", {
+        screen   = screen[1],
+        layout   = awful.layout.suit.tile,
+        column_count = 1,
+    })
+
+--DOC_NEWLINE
+
+    awful.tag.add("2 columns", {
+        screen   = screen[1],
+        layout   = awful.layout.suit.tile,
+        column_count = 2,
+    })
+
+--DOC_NEWLINE
+
+    awful.tag.add("3 columns", {
+        screen   = screen[1],
+        layout   = awful.layout.suit.tile,
+        column_count = 3,
+    })
+
+
+end) --DOC_HIDE
+
+module.display_tags() --DOC_HIDE
+
+--DOC_NEWLINE
+
+module.add_event("Add some clients", function() --DOC_HIDE
+    -- Add some clients.
+    for _, t in ipairs(screen[1].tags) do
+        for _ = 1, 6 do
+            awful.spawn("xterm", {tag = t})
+        end
+        assert(#t:clients() == 6) --DOC_HIDE
+    end
+end) --DOC_HIDE
+
+module.display_tags() --DOC_HIDE
+
+module.execute {show_empty = true} --DOC_HIDE

tests/examples/sequences/template.lua

@@ -242,11 +242,28 @@ local function gen_cls(c,results)
     return ret
 end
 
+local function get_all_tag_clients(t)
+    local s = t.screen
+
+    local clients = gtable.clone(t:clients(), false)
+
+    for _, c in ipairs(s.clients) do
+        if c.sticky then
+            if not gtable.hasitem(clients, c) then
+                table.insert(clients, c)
+            end
+        end
+    end
+
+    return clients
+end
+
 local function fake_arrange(tag)
     local cls,results,flt = {},setmetatable({},{__mode="k"}),{}
-    local _, l = tag.screen, tag.layout
+    local l = tag.layout
     local focus, focus_wrap = capi.client.focus, nil
-    for _ ,c in ipairs (tag:clients()) do
+
+    for _ ,c in ipairs (get_all_tag_clients(tag)) do
         -- Handle floating client separately
         if not c.minimized then
             local floating = c.floating
@@ -758,7 +775,7 @@ function module.display_tags()
                     master_width_factor = t.master_width_factor,
                     client_geo          = fake_arrange(t),
                 })
-                assert(#st[#st].client_geo == #t:clients())
+                assert(#st[#st].client_geo == #get_all_tag_clients(t))
             end
             table.insert(ret, {tags=st})
         end

tests/examples/shims/_default_look.lua

@@ -10,6 +10,7 @@ local mytextclock = wibox.widget.textclock()
 local mylayoutbox = awful.widget.layoutbox(screen[1])
 local mytaglist = awful.widget.taglist(screen[1], awful.widget.taglist.filter.all, {})
 local mytasklist = awful.widget.tasklist(screen[1], awful.widget.tasklist.filter.currenttags, {})
+local mypromptbox = wibox.widget.textbox("")
 
 local wb = awful.wibar { position = "top" }
 wb:setup {
@@ -21,11 +22,24 @@ wb:setup {
             widget = wibox.widget.imagebox,
         },
         mytaglist,
+        mypromptbox,
     },
     mytasklist,
     {
         layout = wibox.layout.fixed.horizontal,
         mykeyboardlayout,
+        {
+            image  = beautiful.awesome_icon,
+            widget = wibox.widget.imagebox,
+        },
+        {
+            image  = beautiful.awesome_icon,
+            widget = wibox.widget.imagebox,
+        },
+        {
+            image  = beautiful.awesome_icon,
+            widget = wibox.widget.imagebox,
+        },
         mytextclock,
         mylayoutbox,
     },
@@ -70,5 +84,6 @@ return {
     mylayoutbox      = mylayoutbox     ,
     mytaglist        = mytaglist       ,
     mytasklist       = mytasklist      ,
-    mywibox          = wb,
+    mywibox          = wb              ,
+    mypromptbox      = mypromptbox     ,
 }

tests/examples/shims/awesome.lua

@@ -82,6 +82,8 @@ function awesome.xrdb_get_value()
     return nil
 end
 
+function awesome.spawn() end
+
 -- Always show deprecated messages
 awesome.version   = "v9999"
 awesome.api_level = 9999

tests/examples/shims/client.lua

@@ -1,4 +1,5 @@
 local gears_obj = require("gears.object")
+local grect = require("gears.geometry").rectangle
 
 local clients = {}
 
@@ -71,6 +72,7 @@ function client.gen_fake(args)
     ret.valid = true
     ret.size_hints = {}
     ret._border_width = 1
+    ret._tags = args and args.tags or nil
     ret.icon_sizes = {{16,16}}
     ret.name = "Example Client"
     ret._private._struts = { top = 0, right = 0, left = 0, bottom = 0 }
@@ -98,7 +100,14 @@ function client.gen_fake(args)
 
     -- Emulate capi.client.geometry
     function ret:geometry(new)
-        if new then
+        local new_full = new and {
+            x      = new.x or ret.x,
+            y      = new.y or ret.y,
+            width  = new.width  or ret.width,
+            height = new.height or ret.height,
+        } or nil
+
+        if new and not grect.are_equal(ret, new_full) then
             for k,v in pairs(new) do
                 ret[k] = v
                 ret:emit_signal("property::"..k, v)
@@ -130,6 +139,12 @@ function client.gen_fake(args)
         ret._old_geo[#ret._old_geo]._hide = true
     end
 
+    function ret:_hide_all()
+        for _, geo in ipairs(ret._old_geo) do
+            geo._hide = true
+        end
+    end
+
     function ret:get_xproperty()
         return nil
     end

tests/examples/wibox/awidget/defaults/button.lua

@@ -0,0 +1,22 @@
+--DOC_GEN_IMAGE --DOC_HEADER --DOC_HIDE
+local parent = ... --DOC_NO_USAGE --DOC_HIDE
+local awful = {--DOC_HIDE
+    button = require("awful.button"), --DOC_HIDE
+    widget = {button = require("awful.widget.button")} --DOC_HIDE
+}--DOC_HIDE
+local beautiful = require("beautiful") --DOC_HIDE
+
+    local button = --DOC_HIDE
+    awful.widget.button {
+        image   = beautiful.awesome_icon,
+        buttons = {
+            awful.button({}, 1, nil, function ()
+                print("Mouse was clicked")
+            end)
+        }
+    }
+
+button.forced_height = 24 --DOC_HIDE
+button.forced_width = 24 --DOC_HIDE
+
+parent:add(button) --DOC_HIDE

tests/examples/wibox/awidget/defaults/clienticon.lua

@@ -0,0 +1,22 @@
+--DOC_GEN_IMAGE --DOC_HEADER --DOC_HIDE
+local parent = ... --DOC_NO_USAGE --DOC_HIDE
+local awful = {--DOC_HIDE
+    button = require("awful.button"), --DOC_HIDE
+    widget = {button = require("awful.widget.button")} --DOC_HIDE
+}--DOC_HIDE
+local beautiful = require("beautiful") --DOC_HIDE
+
+    local button = --DOC_HIDE
+    awful.widget.button {
+        image   = beautiful.awesome_icon,
+        buttons = {
+            awful.button({}, 1, nil, function ()
+                print("Mouse was clicked")
+            end)
+        }
+    }
+
+button.forced_height = 24 --DOC_HIDE
+button.forced_width = 24 --DOC_HIDE
+
+parent:add(button) --DOC_HIDE

tests/examples/wibox/awidget/defaults/keyboardlayout.lua

@@ -0,0 +1,13 @@
+--DOC_GEN_IMAGE --DOC_HIDE
+local parent = ... --DOC_HIDE
+local wibox  = require("wibox") --DOC_HIDE
+
+parent:add( --DOC_HIDE
+
+wibox.widget{
+    markup = "US",
+    widget = wibox.widget.textbox
+}
+
+) --DOC_HIDE
+--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

tests/examples/wibox/awidget/defaults/launcher.lua

@@ -0,0 +1,20 @@
+--DOC_GEN_IMAGE --DOC_HEADER --DOC_HIDE --DOC_HIDE_ALL
+local parent = ... --DOC_NO_USAGE --DOC_HIDE
+local awful = {--DOC_HIDE
+    widget = {launcher = require("awful.widget.launcher")} --DOC_HIDE
+}--DOC_HIDE
+local beautiful = require("beautiful") --DOC_HIDE
+
+    local mymainmenu = {}
+
+    local mylauncher = --DOC_HIDE
+    awful.widget.launcher {
+        image = beautiful.awesome_icon,
+        menu  = mymainmenu
+    }
+
+assert(mylauncher)
+mylauncher.forced_height = 24 --DOC_HIDE
+mylauncher.forced_width = 24 --DOC_HIDE
+
+parent:add(mylauncher) --DOC_HIDE

tests/examples/wibox/awidget/defaults/layoutbox.lua

@@ -0,0 +1,14 @@
+--DOC_GEN_IMAGE --DOC_HEADER --DOC_HIDE
+local parent = ... --DOC_NO_USAGE --DOC_HIDE
+local awful = {--DOC_HIDE
+    layout = require("awful.layout"), --DOC_HIDE
+    widget = {layoutbox = require("awful.widget.layoutbox")} --DOC_HIDE
+}--DOC_HIDE
+
+    local button = --DOC_HIDE
+    awful.widget.layoutbox {screen = 1}
+
+button.forced_height = 24 --DOC_HIDE
+button.forced_width = 24 --DOC_HIDE
+
+parent:add(button) --DOC_HIDE

tests/examples/wibox/awidget/defaults/layoutlist.lua

@@ -0,0 +1,31 @@
+--DOC_GEN_IMAGE --DOC_HEADER --DOC_HIDE
+local parent = ... --DOC_NO_USAGE --DOC_HIDE
+local awful = {--DOC_HIDE
+    widget = {layoutlist = require("awful.widget.layoutlist")}, --DOC_HIDE
+    layout = require("awful.layout") --DOC_HIDE
+}--DOC_HIDE
+local wibox = require("wibox") --DOC_HIDE
+
+local ll = --DOC_HIDE
+
+        awful.widget.layoutlist {
+            base_layout = wibox.layout.fixed.horizontal,
+            style = {
+                disable_name = true,
+                spacing      = 3,
+            },
+            source = function() return {
+                awful.layout.suit.floating,
+                awful.layout.suit.tile,
+                awful.layout.suit.tile.left,
+                awful.layout.suit.tile.bottom,
+                awful.layout.suit.tile.top,
+            } end,
+            screen      = 1,
+        }
+
+ll.forced_height = 24 --DOC_HIDE
+ll.forced_width = 100 --DOC_HIDE
+parent:add(ll) --DOC_HIDE
+
+--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

tests/examples/wibox/awidget/defaults/taglist.lua

@@ -0,0 +1,56 @@
+--DOC_GEN_IMAGE --DOC_HIDE_ALL
+local parent = ... --DOC_NO_USAGE
+local awful = {
+    tag = require("awful.tag"),
+    layout = require("awful.layout"),
+    placement = require("awful.placement"),
+    widget = {taglist = require("awful.widget.taglist")}
+}
+local wibox = require("wibox")
+local beautiful = require("beautiful")
+
+local s = screen[1]
+local taglist_buttons = nil -- To make luacheck shut up
+
+local tags = {}
+
+table.insert(tags,
+    awful.tag.add("one", {})
+)
+
+--DOC_NEWLINE
+
+table.insert(tags,
+    awful.tag.add("two", {
+        icon = beautiful.awesome_icon
+    })
+)
+
+--DOC_NEWLINE
+
+table.insert(tags,
+    awful.tag.add("three", {})
+)
+
+--DOC_NEWLINE
+
+for i=1, 3 do tags[i].selected = false end
+tags[2].selected = true
+
+--DOC_HIDE add some clients to some tags
+local c = client.gen_fake {x = 80, y = 55, width=75, height=50}
+local c2 = client.gen_fake {x = 80, y = 55, width=75, height=50}
+c:tags(tags[3])
+c2:tags(tags[1])
+
+s.mytaglist = awful.widget.taglist {
+    screen  = s,
+    filter  = awful.widget.taglist.filter.all,
+    buttons = taglist_buttons
+}
+
+s.mytaglist.forced_width = 100
+s.mytaglist.forced_height = 18
+s.mytaglist._do_taglist_update_now()
+
+parent:add(wibox.widget.background(s.mytaglist, beautiful.bg_normal))

tests/examples/wibox/awidget/defaults/tasklist.lua

@@ -0,0 +1,32 @@
+--DOC_GEN_IMAGE --DOC_HIDE_ALL
+local parent = ... --DOC_NO_USAGE
+local awful = {
+    tag = require("awful.tag"),
+    placement = require("awful.placement"),
+    widget = {tasklist = require("awful.widget.tasklist")}
+}
+local beautiful = require("beautiful")
+
+local s = screen[1]
+local tasklist_buttons = nil -- To make luacheck shut up
+
+local t_real = awful.tag.add("Test", {screen=screen[1]})
+
+for i=1, 3 do
+    local c = client.gen_fake {x = 80, y = 55, width=75, height=50}
+    c:tags{t_real}
+    c.icon = beautiful.awesome_icon
+    c.name = " Client "..i.."  "
+end
+
+    s.mytasklist = awful.widget.tasklist {
+        screen   = s,
+        filter   = awful.widget.tasklist.filter.currenttags,
+        buttons  = tasklist_buttons,
+    }
+
+s.mytasklist.forced_width = 200
+s.mytasklist.forced_height = 18
+s.mytasklist._do_tasklist_update_now()
+
+parent:add( s.mytasklist)

tests/examples/wibox/awidget/defaults/watch.lua

@@ -0,0 +1,18 @@
+--DOC_HIDE --DOC_GEN_IMAGE --DOC_HEADER
+local parent = ... --DOC_NO_USAGE --DOC_HIDE
+local awful = {--DOC_HIDE
+    button = require("awful.button"), --DOC_HIDE
+    widget = {watch = require("awful.widget.watch")} --DOC_HIDE
+}--DOC_HIDE
+local aspawn = require("awful.spawn") --DOC_HIDE
+aspawn.easy_async = function(_, cb)--DOC_HIDE
+    cb("Hello world!", "", nil, 0)--DOC_HIDE
+end--DOC_HIDE
+aspawn.with_line_callback = function() end --DOC_HIDE
+
+    local watch = --DOC_HIDE
+    awful.widget.watch('bash -c "echo Hello world! | grep Hello"', 15)
+
+watch.forced_height = 24 --DOC_HIDE
+
+parent:add(watch) --DOC_HIDE

tests/examples/wibox/awidget/taglist/icon.lua

@@ -0,0 +1,56 @@
+--DOC_GEN_IMAGE --DOC_HIDE
+local parent = ... --DOC_NO_USAGE --DOC_HIDE
+local awful = { --DOC_HIDE
+    tag = require("awful.tag"), --DOC_HIDE
+    layout = require("awful.layout"), --DOC_HIDE
+    placement = require("awful.placement"), --DOC_HIDE
+    widget = {taglist = require("awful.widget.taglist")} --DOC_HIDE
+} --DOC_HIDE
+local wibox = require("wibox") --DOC_HIDE
+local beautiful = require("beautiful") --DOC_HIDE
+
+local s = screen[1] --DOC_HIDE
+local taglist_buttons = nil -- To make luacheck shut up --DOC_HIDE
+
+local tags = {} --DOC_HIDE
+
+table.insert(tags, --DOC_HIDE
+    awful.tag.add("one", {})
+) --DOC_HIDE
+
+--DOC_NEWLINE
+
+table.insert(tags, --DOC_HIDE
+    awful.tag.add("two", {
+        icon = beautiful.awesome_icon
+    })
+) --DOC_HIDE
+
+--DOC_NEWLINE
+
+table.insert(tags, --DOC_HIDE
+    awful.tag.add("three", {})
+) --DOC_HIDE
+
+--DOC_NEWLINE
+
+for i=1, 3 do tags[i].selected = false end --DOC_HIDE
+tags[2].selected = true --DOC_HIDE
+
+--DOC_HIDE add some clients to some tags
+local c = client.gen_fake {x = 80, y = 55, width=75, height=50} --DOC_HIDE
+local c2 = client.gen_fake {x = 80, y = 55, width=75, height=50} --DOC_HIDE
+c:tags(tags[3]) --DOC_HIDE
+c2:tags(tags[1]) --DOC_HIDE
+
+s.mytaglist = awful.widget.taglist { --DOC_HIDE
+    screen  = s, --DOC_HIDE
+    filter  = awful.widget.taglist.filter.all, --DOC_HIDE
+    buttons = taglist_buttons --DOC_HIDE
+} --DOC_HIDE
+
+s.mytaglist.forced_width = 100 --DOC_HIDE
+s.mytaglist.forced_height = 18 --DOC_HIDE
+s.mytaglist._do_taglist_update_now() --DOC_HIDE
+
+parent:add(wibox.widget.background(s.mytaglist, beautiful.bg_normal)) --DOC_HIDE