Merge branch 'awesomeWM:master' into master

.github/workflows/main.yml

@@ -240,10 +240,6 @@ jobs:
         if: matrix.coverage
         run: sudo -H luarocks install cluacov
 
-      - name: Install codecov.io uploader
-        if: matrix.coverage == 'codecov'
-        run: wget -O /tmp/codecov-bash https://codecov.io/bash
-
       # Check out repository to ${{ github.workspace }}
       # Automatically picks the current branch/PR
       - uses: actions/checkout@v2
@@ -308,7 +304,7 @@ jobs:
         run: cd "${{ github.workspace }}/build" && make check-unit
 
       - name: Run examples tests
-        run: cd "${{ github.workspace }}/build" && make check-examples
+        run: cd "${{ github.workspace }}/build" && make check-examples -j24
 
       - name: Run requires tests
         if: matrix.coverage
@@ -317,13 +313,12 @@ jobs:
       - name: Run themes tests
         run: cd "${{ github.workspace }}/build" && make check-themes
 
-      - name: Upload Lua code coverage report
+      - name: Generate Lua coverage report
         if: matrix.coverage == 'codecov'
         run: |
           luacov
-          bash /tmp/codecov-bash -f build/luacov.report.out -X gcov -X coveragepy -F luacov
 
-      - name: Upload C code coverage report
+      - name: Generate C coverage report
         if: matrix.coverage == 'codecov'
         run: |
           # Report coverage for each .gcno file separately.
@@ -342,9 +337,22 @@ jobs:
             # with Code Climate.
             find "gcov.$i" -maxdepth 1 -type f -name '#usr#*.gcov' -delete
           done
-
-          # Upload to Codecov.
-          bash /tmp/codecov-bash -X gcov -X coveragepy -F gcov
+          
+      - name: Upload Lua code coverage report
+        if: matrix.coverage == 'codecov'
+        uses: codecov/codecov-action@v3
+        with:
+          files: "${{ github.workspace }}/build/luacov.report.out"
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
+
+      - name: Upload C code coverage report
+        if: matrix.coverage == 'codecov'
+        uses: codecov/codecov-action@v3
+        with:
+          files: "${{ github.workspace }}/build/*/*.gcov"
+        env:
+          CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
 
       # `check-qa` is the only test that doesn't get a coverage report, so it has to run after all of that.
       - name: Run qa tests

docs/common/cursor.ldoc

@@ -0,0 +1,80 @@
+ <div class='flex-list'>
+-- <div>num\_glyphs</div>
+-- <div>arrow</div>
+-- <div>based\_arrow\_down</div>
+-- <div>based\_arrow\_up</div>
+-- <div>boat</div>
+-- <div>bogosity</div>
+-- <div>bottom\_left\_corner</div>
+-- <div>bottom\_right\_corner</div>
+-- <div>bottom\_side</div>
+-- <div>bottom\_tee</div>
+-- <div>box\_spiral</div>
+-- <div>center\_ptr</div>
+-- <div>circle</div>
+-- <div>clock</div>
+-- <div>coffee\_mug</div>
+-- <div>cross</div>
+-- <div>crosshair</div>
+-- <div>cross\_reverse</div>
+-- <div>cursor</div>
+-- <div>diamond\_cross</div>
+-- <div>dotbox</div>
+-- <div>dot</div>
+-- <div>double\_arrow</div>
+-- <div>draft\_large</div>
+-- <div>draft\_small</div>
+-- <div>draped\_box</div>
+-- <div>exchange</div>
+-- <div>fleur</div>
+-- <div>gobbler</div>
+-- <div>gumby</div>
+-- <div>hand</div>
+-- <div>hand</div>
+-- <div>heart</div>
+-- <div>icon</div>
+-- <div>iron\_cross</div>
+-- <div>leftbutton</div>
+-- <div>left\_ptr</div>
+-- <div>left\_side</div>
+-- <div>left\_tee</div>
+-- <div>ll\_angle</div>
+-- <div>lr\_angle</div>
+-- <div>man</div>
+-- <div>middlebutton</div>
+-- <div>mouse</div>
+-- <div>pencil</div>
+-- <div>pirate</div>
+-- <div>plus</div>
+-- <div>question\_arrow</div>
+-- <div>rightbutton</div>
+-- <div>right\_ptr</div>
+-- <div>right\_side</div>
+-- <div>right\_tee</div>
+-- <div>rtl\_logo</div>
+-- <div>sailboat</div>
+-- <div>sb\_down\_arrow</div>
+-- <div>sb\_h\_double\_arrow</div>
+-- <div>sb\_left\_arrow</div>
+-- <div>sb\_right\_arrow</div>
+-- <div>sb\_up\_arrow</div>
+-- <div>sb\_v\_double\_arrow</div>
+-- <div>shuttle</div>
+-- <div>sizing</div>
+-- <div>spider</div>
+-- <div>spraycan</div>
+-- <div>star</div>
+-- <div>target</div>
+-- <div>tcross</div>
+-- <div>top\_left\_arrow</div>
+-- <div>top\_left\_corner</div>
+-- <div>top\_right\_corner</div>
+-- <div>top\_side</div>
+-- <div>top\_tee</div>
+-- <div>trek</div>
+-- <div>ul\_angle</div>
+-- <div>umbrella</div>
+-- <div>ur\_angle</div>
+-- <div>watch</div>
+-- <div>xterm</div>
+-- </div>

lib/awful/wallpaper.lua

@@ -30,6 +30,11 @@
 --
 --@DOC_awful_wallpaper_mazimized3_EXAMPLE@
 --
+-- To maintain the image's aspect ratio while filling the
+-- screen, the image can be cropped using `gears.surface`:
+--
+--@DOC_awful_wallpaper_mazimized4_EXAMPLE@
+--
 -- Finally, it is also possible to use simpler "branding" in a corner using
 -- `awful.placement`:
 --

lib/awful/widget/keyboardlayout.lua

@@ -265,8 +265,16 @@ end
 -- It shows current keyboard layout name in a textbox.
 --
 -- @constructorfct awful.widget.keyboardlayout
+-- @tparam[opt] table args The argument table containing any of the arguments below.
+-- @tparam[opt] table args.country_codes Array of names of custom keyboard layouts.
 -- @treturn awful.widget.keyboardlayout A keyboard layout widget.
-function keyboardlayout.new()
+function keyboardlayout.new(args)
+    if args and args.country_codes then
+        for _, country_code in ipairs(args.country_codes) do
+            keyboardlayout.xkeyboard_country_code[country_code] = true
+        end
+    end
+
     local widget = textbox()
     local self = widget_base.make_widget(widget, nil, {enable_properties=true})
 

lib/awful/widget/taglist.lua

@@ -1,7 +1,7 @@
 ---------------------------------------------------------------------------
 --- Taglist widget module for awful.
 --
--- Here is a more advanced example of how to extent the `taglist`. It provides:
+-- Here is a more advanced example of how to extend the `taglist`. It provides:
 --
 -- * mouse "hover" color
 -- * an extra index field
@@ -431,7 +431,7 @@ end
 
 --- The current number of tags.
 --
--- Note that the `tasklist` is usually lazy-loaded. Reading this property
+-- Note that the `taglist` is usually lazy-loaded. Reading this property
 -- may cause the widgets to be created. Depending on where the property is called
 -- from, it might, in theory, cause an infinite loop.
 --

lib/gears/table.lua

@@ -1,5 +1,5 @@
 ---------------------------------------------------------------------------
---- Various functions to worj with tables.
+--- Various functions to work with tables.
 --
 -- Examples
 -- ========

lib/gears/timer.lua

@@ -145,7 +145,7 @@ end
 -- @see start
 -- @see stop
 
---- The timer timeout value.
+--- The timer timeout value in seconds.
 --
 -- @property timeout
 -- @tparam[opt=0] number timeout
@@ -182,8 +182,8 @@ local timer_instance_mt = {
 --
 -- @tparam table args Arguments.
 -- @tparam number args.timeout Timeout in seconds (e.g. `1.5`).
--- @tparam[opt=false] boolean args.autostart Automatically start the timer.
--- @tparam[opt=false] boolean args.call_now Call the callback at timer creation.
+-- @tparam[opt=false] boolean args.autostart Immediately start the timer countdown.
+-- @tparam[opt=false] boolean args.call_now Immediately call the callback function.
 -- @tparam[opt] function args.callback Callback function to connect to the
 --  "timeout" signal.
 -- @tparam[opt=false] boolean args.single_shot Run only once then stop.
@@ -205,12 +205,11 @@ function timer.new(args)
     end
 
     if args.callback then
-        if args.call_now then
-            args.callback()
-        end
         ret:connect_signal("timeout", args.callback)
     end
-
+    if args.call_now then
+        ret:emit_signal("timeout")
+    end
     if args.single_shot then
         ret:connect_signal("timeout", function() ret:stop() end)
     end

lib/naughty/layout/box.lua

@@ -23,6 +23,7 @@ local abutton    = require("awful.button")
 local ascreen    = require("awful.screen")
 local gpcall     = require("gears.protected_call")
 local dpi        = require("beautiful").xresources.apply_dpi
+local cst        = require("naughty.constants")
 
 local default_widget = require("naughty.widget._default")
 
@@ -378,18 +379,20 @@ local function new(args)
     end
 
     --TODO remove
-    local function hide()
-        local n = ret._private.notification[1]
+    local function hide(reason)
+        return function ()
+            local n = ret._private.notification[1]
 
-        if n then
-            n:destroy()
+            if n then
+                n:destroy(reason)
+            end
         end
     end
 
-    --FIXME there's another pull request for this
+    -- On right click, close the notification without triggering the default action
     ret:buttons(gtable.join(
-        abutton({ }, 1, hide),
-        abutton({ }, 3, hide)
+        abutton({ }, 1, hide(cst.notification_closed_reason.dismissed_by_user)),
+        abutton({ }, 3, hide(cst.notification_closed_reason.silent))
     ))
 
     gtable.crush(ret, box, false)

lib/wibox/container/margin.lua

@@ -71,7 +71,7 @@ function margin:fit(context, width, height)
     return w + extra_w, h + extra_h
 end
 
---- The widget to be wrapped the the margins.
+--- The widget to be wrapped by the margins.
 --
 -- @property widget
 -- @tparam[opt=nil] widget|nil widget

lib/wibox/widget/graph.lua

@@ -1,9 +1,9 @@
 ---------------------------------------------------------------------------
 --- Display multiple values as a stream of bars.
 --
--- The graph goes from left to right. To change this to right to left, use
--- a `wibox.container.mirror` widget. This can also be used to have data
--- shown from top to bottom.
+-- The graph goes from left to right. To change the movement's direction,
+-- use a `wibox.container.mirror` widget. This can also be used to have
+-- data shown from top to bottom.
 --
 -- To add text on top of the graph, use a `wibox.layout.stack` and a
 -- `wibox.container.align` widgets.

lib/wibox/widget/separator.lua

@@ -1,7 +1,7 @@
 ---------------------------------------------------------------------------
 -- A flexible separator widget.
 --
--- By default, this widget display a simple line, but can be extended by themes
+-- By default, this widget displays a simple line, but can be extended by themes
 -- (or directly) to display much more complex visuals.
 --
 -- This widget is mainly intended to be used alongside the `spacing_widget`

lib/wibox/widget/slider.lua

@@ -89,7 +89,11 @@ local slider = {mt={}}
 -- @propemits true false
 -- @propbeautiful
 
---- The handle grab cursor.
+--- The cursor icon while grabbing the handle.
+-- The available cursor names are:
+--
+--@DOC_cursor_COMMON@
+--
 -- @property handle_cursor
 -- @tparam[opt="fleur"] string|nil handle_cursor
 -- @propbeautiful
@@ -228,7 +232,10 @@ local slider = {mt={}}
 -- @tparam[opt=gears.shape.rectangle] gears.shape shape
 -- @see gears.shape
 
---- The handle grab cursor.
+--- The cursor icon while grabbing the handle.
+-- The available cursor names are:
+--
+--@DOC_cursor_COMMON@
 --
 -- @beautiful beautiful.slider_handle_cursor
 -- @tparam[opt="fleur"] string cursor
@@ -565,7 +572,9 @@ end
 -- @tparam[opt] number args.handle_width The slider handle width.
 -- @tparam[opt] color args.handle_border_color The handle border_color.
 -- @tparam[opt] number args.handle_border_width The handle border width.
--- @tparam[opt] string args.handle_cursor The handle grab cursor.
+-- @tparam[opt] string args.handle_cursor
+--   The cursor icon while grabbing the handle.
+--   The available cursor names are listed under handle_cursor, in the "Object properties" section.
 -- @tparam[opt] gears.shape args.bar_shape The bar (background) shape.
 -- @tparam[opt] number args.bar_height The bar (background) height.
 -- @tparam[opt] color args.bar_color The bar (background) color.

objects/client.c

@@ -1375,7 +1375,7 @@ lua_class_t client_class;
 /**
  * The FreeDesktop StartId.
  *
- * When a client is spawned (like using a terminal or `awful.spawn`, a startup
+ * When a client is spawned (like using a terminal or `awful.spawn`), a startup
  * notification identifier is created. When the client is created, this
  * identifier remain the same. This allow to match a spawn event to an actual
  * client.