awful.wibox: Rename to awful.wibar

Why:

 * Two different (but related) concepts had the same name
 * Users were confused for years on IRC
 * The wibar name was already in use in some doc to avoid confusion

awesomerc.lua

@@ -196,7 +196,7 @@ awful.screen.connect_for_each_screen(function(s)
     mytasklist[s] = awful.widget.tasklist(s, awful.widget.tasklist.filter.currenttags, mytasklist.buttons)
 
     -- Create the wibox
-    mywibox[s] = awful.wibox({ position = "top", screen = s })
+    mywibox[s] = awful.wibar({ position = "top", screen = s })
 
     -- Add widgets to the wibox
     mywibox[s]:setup {

lib/awful/init.lua

@@ -51,6 +51,7 @@ return
     remote = require("awful.remote");
     key = require("awful.key");
     button = require("awful.button");
+    wibar = require("awful.wibar");
     wibox = require("awful.wibox");
     startup_notification = require("awful.startup_notification");
     tooltip = require("awful.tooltip");

lib/awful/mouse/init.lua

@@ -10,7 +10,7 @@
 -- Grab environment we need
 local layout = require("awful.layout")
 local aplace = require("awful.placement")
-local awibox = require("awful.wibox")
+local awibar = require("awful.wibar")
 local util = require("awful.util")
 local type = type
 local ipairs = ipairs
@@ -135,20 +135,20 @@ function mouse.wibox.move(w)
 
     capi.mousegrabber.run(function (_mouse)
         local button_down = false
-        if awibox.get_position(w) == "floating" then
+        if awibar.get_position(w) == "floating" then
             w.x = capi.mouse.coords().x + offset.x
             w.y = capi.mouse.coords().y + offset.y
         else
             local wa = capi.screen[capi.mouse.screen].workarea
 
             if capi.mouse.coords()["y"] > wa.y + wa.height - 10 then
-                awibox.set_position(w, "bottom", w.screen)
+                awibar.set_position(w, "bottom", w.screen)
             elseif capi.mouse.coords()["y"] < wa.y + 10 then
-                awibox.set_position(w, "top", w.screen)
+                awibar.set_position(w, "top", w.screen)
             elseif capi.mouse.coords()["x"] > wa.x + wa.width - 10 then
-                awibox.set_position(w, "right", w.screen)
+                awibar.set_position(w, "right", w.screen)
             elseif capi.mouse.coords()["x"] < wa.x + 10 then
-                awibox.set_position(w, "left", w.screen)
+                awibar.set_position(w, "left", w.screen)
             end
             w.screen = capi.mouse.screen
         end

lib/awful/wibar.lua

@@ -0,0 +1,335 @@
+---------------------------------------------------------------------------
+--- Wibox module for awful.
+-- This module allows you to easily create wibox and attach them to the edge of
+-- a screen.
+--
+-- @author Emmanuel Lepage Vallee <elv1313@gmail.com>
+-- @copyright 2016 Emmanuel Lepage Vallee
+-- @release @AWESOME_VERSION@
+-- @module awful.wibar
+---------------------------------------------------------------------------
+
+-- Grab environment we need
+local capi =
+{
+    screen = screen,
+    client = client
+}
+local setmetatable = setmetatable
+local tostring = tostring
+local ipairs = ipairs
+local error = error
+local wibox = require("wibox")
+local beautiful = require("beautiful")
+local util = require("awful.util")
+local placement = require("awful.placement")
+
+local function get_screen(s)
+    return s and capi.screen[s]
+end
+
+local awfulwibar = { mt = {} }
+
+--- Array of table with wiboxes inside.
+-- It's an array so it is ordered.
+local wiboxes = setmetatable({}, {__mode = "v"})
+
+-- Compute the margin on one side
+local function get_margin(w, position, auto_stop)
+    local h_or_w = (position == "top" or position == "bottom") and "height" or "width"
+    local ret = 0
+
+    for _, v in ipairs(wiboxes) do
+        -- Ignore the wibars placed after this one
+        if auto_stop and v == w then break end
+
+        if v.position == position and v.screen == w.screen and v.visible then
+            ret = ret + v[h_or_w]
+        end
+    end
+
+    return ret
+end
+
+-- `honor_workarea` cannot be used as it does modify the workarea itself.
+-- a manual padding has to be generated.
+local function get_margins(w)
+    local position = w.position
+    assert(position)
+
+    local margins = {left=0, right=0, top=0, bottom=0}
+
+    margins[position] = get_margin(w, position, true)
+
+    -- Avoid overlapping wibars
+    if position == "left" or position == "right" then
+        margins.top    = get_margin(w, "top"   )
+        margins.bottom = get_margin(w, "bottom")
+    end
+
+    return margins
+end
+
+-- Create the placement function
+local function gen_placement(position, stretch)
+    local maximize = (position == "right" or position == "left") and
+        "maximize_vertically" or "maximize_horizontally"
+
+    return placement[position] + (stretch and placement[maximize] or nil)
+end
+
+-- Attach the placement function.
+local function attach(wb, align)
+    gen_placement(align, wb._stretch)(wb, {
+        attach          = true,
+        update_workarea = true,
+        margins         = get_margins(wb)
+    })
+end
+
+-- Re-attach all wibars on a given wibar screen
+local function reattach(wb)
+    local s = wb.screen
+    for _, w in ipairs(wiboxes) do
+        if w ~= wb and w.screen == s then
+            if w.detach_callback then
+                w.detach_callback()
+                w.detach_callback = nil
+            end
+            attach(w, w.position)
+        end
+    end
+end
+
+--- The wibox position.
+-- @property position
+-- @param string Either "left", right", "top" or "bottom"
+
+local function get_position(wb)
+    return wb._position or "top"
+end
+
+local function set_position(wb, position)
+    -- Detach first to avoid any uneeded callbacks
+    if wb.detach_callback then
+        wb.detach_callback()
+
+        -- Avoid disconnecting twice, this produces a lot of warnings
+        wb.detach_callback = nil
+    end
+
+    -- Move the wibar to the end of the list to avoid messing up the others in
+    -- case there is stacked wibars on one side.
+    if wb._position then
+        for k, w in ipairs(wiboxes) do
+            if w == wb then
+                table.remove(wiboxes, k)
+            end
+        end
+        table.insert(wiboxes, wb)
+    end
+
+    -- In case the position changed, it may be necessary to reset the size
+    if (wb._position == "left" or wb._position == "right")
+      and (position == "top" or position == "bottom") then
+        wb.height = math.ceil(beautiful.get_font_height(wb.font) * 1.5)
+    elseif (wb._position == "top" or wb._position == "bottom")
+      and (position == "left" or position == "right") then
+        wb.width = math.ceil(beautiful.get_font_height(wb.font) * 1.5)
+    end
+
+    -- Changing the position will also cause the other margins to be invalidated.
+    -- For example, adding a wibar to the top will change the margins of any left
+    -- or right wibars. To solve, this, they need to be re-attached.
+    reattach(wb)
+
+    -- Set the new position
+    wb._position = position
+
+    -- Attach to the new position
+    attach(wb, position)
+end
+
+--- Stretch the wibar.
+--
+-- @property stretch
+-- @param[opt=true] boolean
+
+local function get_stretch(w)
+    return w._stretch
+end
+
+local function set_stretch(w, value)
+    w._stretch = value
+
+    attach(w, w.position)
+end
+
+--- Get a wibox position if it has been set, or return top.
+-- @param wb The wibox
+-- @deprecated awful.wibar.get_position
+-- @return The wibox position.
+function awfulwibar.get_position(wb)
+    util.deprecate("Use wb:get_position() instead of awful.wibar.get_position")
+    return get_position(wb)
+end
+
+--- Put a wibox on a screen at this position.
+-- @param wb The wibox to attach.
+-- @param position The position: top, bottom left or right.
+-- @param screen This argument is deprecated, use wb.screen directly.
+-- @deprecated awful.wibar.set_position
+function awfulwibar.set_position(wb, position, screen) --luacheck: no unused args
+    util.deprecate("Use wb:set_position(position) instead of awful.wibar.set_position")
+
+    set_position(wb, position)
+end
+
+--- Attach a wibox to a screen.
+-- If a wibox is attached, it will be automatically be moved when other wiboxes
+-- will be attached.
+-- @param wb The wibox to attach.
+-- @param position The position of the wibox: top, bottom, left or right.
+-- @param screen The screen to attach to
+-- @deprecated awful.wibar.attach
+function awfulwibar.attach(wb, position, screen) --luacheck: no unused args
+    util.deprecate("awful.wibar.attach is deprecated, use the 'attach' property"..
+        " of awful.placement. This method doesn't do anything anymore"
+    )
+end
+
+--- Align a wibox.
+--
+-- Supported alignment are:
+--
+-- * top_left
+-- * top_right
+-- * bottom_left
+-- * bottom_right
+-- * left
+-- * right
+-- * top
+-- * bottom
+-- * centered
+-- * center_vertical
+-- * center_horizontal
+--
+-- @param wb The wibox.
+-- @param align The alignment
+-- @param screen This argument is deprecated. It is not used. Use wb.screen
+--  directly.
+-- @deprecated awful.wibar.align
+-- @see awful.placement.align
+function awfulwibar.align(wb, align, screen) --luacheck: no unused args
+    if align == "center" then
+        util.deprecate("awful.wibar.align(wb, 'center' is deprecated, use 'centered'")
+        align = "centered"
+    end
+
+    if screen then
+        util.deprecate("awful.wibar.align 'screen' argument is deprecated")
+    end
+
+    attach(wb, align)
+end
+
+--- Stretch a wibox so it takes all screen width or height.
+--
+-- **This function has been removed.**
+--
+-- @deprecated awful.wibox.stretch
+-- @see awful.placement
+-- @see stretch
+
+--- Create a new wibox and attach it to a screen edge.
+-- @see wibox
+-- @param arg A table with standard arguments to wibox() creator.
+-- You can add also position key with value top, bottom, left or right.
+-- You can also use width or height in % and set align to center, right or left.
+-- You can also set the screen key with a screen number to attach the wibox.
+-- If not specified, 1 is assumed.
+-- @return The wibox created.
+function awfulwibar.new(arg)
+    arg = arg or {}
+    local position = arg.position or "top"
+    local has_to_stretch = true
+    local screen = get_screen(arg.screen or 1)
+
+    arg.type = arg.type or "dock"
+
+    if position ~= "top" and position ~="bottom"
+            and position ~= "left" and position ~= "right" then
+        error("Invalid position in awful.wibar(), you may only use"
+            .. " 'top', 'bottom', 'left' and 'right'")
+    end
+
+    -- Set default size
+    if position == "left" or position == "right" then
+        arg.width = arg.width or math.ceil(beautiful.get_font_height(arg.font) * 1.5)
+        if arg.height then
+            has_to_stretch = false
+            if arg.screen then
+                local hp = tostring(arg.height):match("(%d+)%%")
+                if hp then
+                    arg.height = math.ceil(screen.geometry.height * hp / 100)
+                end
+            end
+        end
+    else
+        arg.height = arg.height or math.ceil(beautiful.get_font_height(arg.font) * 1.5)
+        if arg.width then
+            has_to_stretch = false
+            if arg.screen then
+                local wp = tostring(arg.width):match("(%d+)%%")
+                if wp then
+                    arg.width = math.ceil(screen.geometry.width * wp / 100)
+                end
+            end
+        end
+    end
+
+    local w = wibox(arg)
+
+    w.screen   = screen
+    w._stretch = arg.stretch == nil and has_to_stretch or arg.stretch
+
+    w:add_signal("property::position")
+    w.get_position = get_position
+    w.set_position = set_position
+
+    w:add_signal("property::stretch")
+    w.get_stretch = get_stretch
+    w.set_stretch = set_stretch
+
+    w.visible = true
+
+    w:set_position(position)
+
+    table.insert(wiboxes, w)
+
+    w:connect_signal("property::visible", function() reattach(w) end)
+
+    return w
+end
+
+capi.screen.connect_signal("removed", function(s)
+    for _, wibar in ipairs(wiboxes) do
+        if wibar.screen == s then
+            if wibar.detach_callback then
+                wibar.detach_callback()
+            end
+
+            wibar.visible = false
+        end
+    end
+end)
+
+function awfulwibar.mt:__call(...)
+    return awfulwibar.new(...)
+end
+
+--@DOC_wibox_COMMON@
+
+return setmetatable(awfulwibar, awfulwibar.mt)
+
+-- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

lib/awful/wibox.lua

@@ -1,337 +1,32 @@
 ---------------------------------------------------------------------------
---- Wibox module for awful.
+--- This module is deprecated and has been renamed `awful.wibar`
--- This module allows you to easily create wibox and attach them to the edge of
--- a screen.
 --
 -- @author Emmanuel Lepage Vallee <elv1313@gmail.com>
 -- @copyright 2016 Emmanuel Lepage Vallee
 -- @release @AWESOME_VERSION@
 -- @module awful.wibox
 ---------------------------------------------------------------------------
-
--- Grab environment we need
-local capi =
-{
-    screen = screen,
-    client = client
-}
-local setmetatable = setmetatable
-local tostring = tostring
-local ipairs = ipairs
-local error = error
-local wibox = require("wibox")
-local beautiful = require("beautiful")
 local util = require("awful.util")
-local placement = require("awful.placement")
+local wibar = require("awful.wibar")
 
---@DOC_wibox_COMMON@
+local function call(_,...)
+    util.deprecate("awful.wibox has been renamed to awful.wibar")
 
-local function get_screen(s)
+    return wibar(...)
-    return s and capi.screen[s]
 end
 
-local awfulwibox = { mt = {} }
+local function index(_, k)
+    util.deprecate("awful.wibox has been renamed to awful.wibar")
 
---- Array of table with wiboxes inside.
+    return wibar[k]
--- It's an array so it is ordered.
-local wiboxes = setmetatable({}, {__mode = "v"})
-
--- Compute the margin on one side
-local function get_margin(w, position, auto_stop)
-    local h_or_w = (position == "top" or position == "bottom") and "height" or "width"
-    local ret = 0
-
-    for _, v in ipairs(wiboxes) do
-        -- Ignore the wiboxes placed after this one
-        if auto_stop and v == w then break end
-
-        if v.position == position and v.screen == w.screen and v.visible then
-            ret = ret + v[h_or_w]
-        end
-    end
-
-    return ret
 end
 
--- `honor_workarea` cannot be used as it does modify the workarea itself.
+local function newindex(_, k, v)
--- a manual padding has to be generated.
+    util.deprecate("awful.wibox has been renamed to awful.wibar")
-local function get_margins(w)
-    local position = w.position
-    assert(position)
 
-    local margins = {left=0, right=0, top=0, bottom=0}
+    wibar[k] = v
-
-    margins[position] = get_margin(w, position, true)
-
-    -- Avoid overlapping wiboxes
-    if position == "left" or position == "right" then
-        margins.top    = get_margin(w, "top"   )
-        margins.bottom = get_margin(w, "bottom")
-    end
-
-    return margins
 end
 
--- Create the placement function
+return setmetatable({}, {__call = call, __index = index, __newindex  = newindex})
-local function gen_placement(position, stretch)
-    local maximize = (position == "right" or position == "left") and
-        "maximize_vertically" or "maximize_horizontally"
-
-    return placement[position] + (stretch and placement[maximize] or nil)
-end
-
--- Attach the placement function.
-local function attach(wb, align)
-    gen_placement(align, wb._stretch)(wb, {
-        attach          = true,
-        update_workarea = true,
-        margins         = get_margins(wb)
-    })
-end
-
--- Re-attach all wiboxes on a given wibox screen
-local function reattach(wb)
-    local s = wb.screen
-    for k, w in ipairs(wiboxes) do
-        if w ~= wb and w.screen == s then
-            if w.detach_callback then
-                w.detach_callback()
-                w.detach_callback = nil
-            end
-            attach(w, w.position)
-        end
-    end
-end
-
---- The wibox position.
--- @property position
--- @param string Either "left", right", "top" or "bottom"
-
-local function get_position(wb)
-    return wb._position or "top"
-end
-
-local function set_position(wb, position)
-    -- Detach first to avoid any uneeded callbacks
-    if wb.detach_callback then
-        wb.detach_callback()
-
-        -- Avoid disconnecting twice, this produces a lot of warnings
-        wb.detach_callback = nil
-    end
-
-    -- Move the wibox to the end of the list to avoid messing up the others in
-    -- case there is stacked wiboxes on one side.
-    if wb._position then
-        for k, w in ipairs(wiboxes) do
-            if w == wb then
-                table.remove(wiboxes, k)
-            end
-        end
-        table.insert(wiboxes, wb)
-    end
-
-    -- In case the position changed, it may be necessary to reset the size
-    if (wb._position == "left" or wb._position == "right")
-      and (position == "top" or position == "bottom") then
-        wb.height = math.ceil(beautiful.get_font_height(wb.font) * 1.5)
-    elseif (wb._position == "top" or wb._position == "bottom")
-      and (position == "left" or position == "right") then
-        wb.width = math.ceil(beautiful.get_font_height(wb.font) * 1.5)
-    end
-
-    -- Changing the position will also cause the other margins to be invalidated.
-    -- For example, adding a wibox to the top will change the margins of any left
-    -- or right wiboxes. To solve, this, they need to be re-attached.
-    reattach(wb)
-
-    -- Set the new position
-    wb._position = position
-
-    -- Attach to the new position
-    attach(wb, position)
-end
-
---- Stretch the wibox.
---
--- @property stretch
--- @param[opt=true] boolean
-
-local function get_stretch(w)
-    return w._stretch
-end
-
-local function set_stretch(w, value)
-    w._stretch = value
-
-    attach(w, w.position)
-end
-
---- Get a wibox position if it has been set, or return top.
--- @param wb The wibox
--- @deprecated awful.wibox.get_position
--- @return The wibox position.
-function awfulwibox.get_position(wb)
-    util.deprecate("Use wb:get_position() instead of awful.wibox.get_position")
-    return get_position(wb)
-end
-
---- Put a wibox on a screen at this position.
--- @param wb The wibox to attach.
--- @param position The position: top, bottom left or right.
--- @param screen This argument is deprecated, use wb.screen directly.
--- @deprecated awful.wibox.set_position
-function awfulwibox.set_position(wb, position, screen) --luacheck: no unused args
-    util.deprecate("Use wb:set_position(position) instead of awful.wibox.set_position")
-
-    set_position(wb, position)
-end
-
---- Attach a wibox to a screen.
--- If a wibox is attached, it will be automatically be moved when other wiboxes
--- will be attached.
--- @param wb The wibox to attach.
--- @param position The position of the wibox: top, bottom, left or right.
--- @param screen The screen to attach to
--- @deprecated awful.wibox.attach
-function awfulwibox.attach(wb, position, screen) --luacheck: no unused args
-    util.deprecate("awful.wibox.attach is deprecated, use the 'attach' property"..
-        " of awful.placement. This method doesn't do anything anymore"
-    )
-end
-
---- Align a wibox.
---
--- Supported alignment are:
---
--- * top_left
--- * top_right
--- * bottom_left
--- * bottom_right
--- * left
--- * right
--- * top
--- * bottom
--- * centered
--- * center_vertical
--- * center_horizontal
---
--- @param wb The wibox.
--- @param align The alignment
--- @param screen This argument is deprecated. It is not used. Use wb.screen
---  directly.
--- @deprecated awful.wibox.align
--- @see awful.placement.align
-function awfulwibox.align(wb, align, screen) --luacheck: no unused args
-    if align == "center" then
-        util.deprecate("awful.wibox.align(wb, 'center' is deprecated, use 'centered'")
-        align = "centered"
-    end
-
-    if screen then
-        util.deprecate("awful.wibox.align 'screen' argument is deprecated")
-    end
-
-    attach(wb, align)
-end
-
---- Stretch a wibox so it takes all screen width or height.
---
--- **This function has been removed.**
---
--- @deprecated awful.wibox.stretch
--- @see awful.placement
--- @see stretch
-
---- Create a new wibox and attach it to a screen edge.
--- @see wibox
--- @param arg A table with standard arguments to wibox() creator.
--- You can add also position key with value top, bottom, left or right.
--- You can also use width or height in % and set align to center, right or left.
--- You can also set the screen key with a screen number to attach the wibox.
--- If not specified, 1 is assumed.
--- @return The wibox created.
-function awfulwibox.new(arg)
-    arg = arg or {}
-    local position = arg.position or "top"
-    local has_to_stretch = true
-    local screen = get_screen(arg.screen or 1)
-
-    arg.type = arg.type or "dock"
-
-    if position ~= "top" and position ~="bottom"
-            and position ~= "left" and position ~= "right" then
-        error("Invalid position in awful.wibox(), you may only use"
-            .. " 'top', 'bottom', 'left' and 'right'")
-    end
-
-    -- Set default size
-    if position == "left" or position == "right" then
-        arg.width = arg.width or math.ceil(beautiful.get_font_height(arg.font) * 1.5)
-        if arg.height then
-            has_to_stretch = false
-            if arg.screen then
-                local hp = tostring(arg.height):match("(%d+)%%")
-                if hp then
-                    arg.height = math.ceil(screen.geometry.height * hp / 100)
-                end
-            end
-        end
-    else
-        arg.height = arg.height or math.ceil(beautiful.get_font_height(arg.font) * 1.5)
-        if arg.width then
-            has_to_stretch = false
-            if arg.screen then
-                local wp = tostring(arg.width):match("(%d+)%%")
-                if wp then
-                    arg.width = math.ceil(screen.geometry.width * wp / 100)
-                end
-            end
-        end
-    end
-
-    local w = wibox(arg)
-
-    w.screen   = screen
-    w._stretch = arg.stretch == nil and has_to_stretch or arg.stretch
-
-    w:add_signal("property::position")
-    w.get_position = get_position
-    w.set_position = set_position
-
-    w:add_signal("property::stretch")
-    w.get_stretch = get_stretch
-    w.set_stretch = set_stretch
-
-    w.visible = true
-
-    w:set_position(position)
-
-    table.insert(wiboxes, w)
-
-    w:connect_signal("property::visible", function() reattach(w) end)
-
-    return w
-end
-
-capi.screen.connect_signal("removed", function(s)
-    for _, wibox in ipairs(wiboxes) do
-        if wibox.screen == s then
-            if wibox.detach_callback then
-                wibox.detach_callback()
-            end
-
-            wibox.visible = false
-        end
-    end
-end)
-
-function awfulwibox.mt:__call(...)
-    return awfulwibox.new(...)
-end
-
---@DOC_wibox_COMMON@
-
-return setmetatable(awfulwibox, awfulwibox.mt)
 
 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80

objects/screen.c

@@ -117,7 +117,7 @@
  * The screen workarea.
  *
  * The workarea is a subsection of the screen where clients can be placed. It
- * usually excludes the toolbars (see `awful.wibox`) and dockable clients
+ * usually excludes the toolbars (see `awful.wibar`) and dockable clients
  * (see `client.dockable`) like WindowMaker DockAPP.
  *
  * It can be modified be altering the `wibox` or `client` struts.