Aire-One
/
awesome
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

doc: Mutualize the wibar and wibox constructor documentation. 

Do it now since the future awful.popup and notification widget
also uses it.

The `load_ldoc.cmake` changes allow to include `.ldoc` blocks in
existing ldoc comments. Previously, it added some extra newlines
and an autogenerated comments saying the content below was imported.
The problem is that this prevented the system to be used for shared
function arguments.

This commit also renames the `wibar` argument table from `arg` to
`args` as the name has to be the same in the `wibox` and `wibar`
constructor for this to work.
This commit is contained in:
Emmanuel Lepage Vallee 2017-11-23 23:19:41 -05:00
parent 9e81045d42
commit d99504775b
4 changed files with 54 additions and 65 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
docs/common/wibox_constructor.ldoc Normal file
View File

@ -0,0 +1,22 @@
@tparam integer args.border_width Border width.
-- @tparam string args.border_color Border color.
-- @tparam[opt=false] boolean args.ontop On top of other windows.
-- @tparam string args.cursor The mouse cursor.
-- @tparam boolean args.visible Visibility.
-- @tparam[opt=1] number args.opacity The opacity, between 0 and 1.
-- @tparam string args.type The window type (desktop, normal, dock, …).
-- @tparam integer args.x The x coordinates.
-- @tparam integer args.y The y coordinates.
-- @tparam integer args.width The width.
-- @tparam integer args.height The height.
-- @tparam screen args.screen The wibox screen.
-- @tparam wibox.widget args.widget The widget that the wibox displays.
-- @param args.shape_bounding The wibox’s bounding shape as a (native) cairo surface.
-- @param args.shape_clip The wibox’s clip shape as a (native) cairo surface.
-- @param args.shape_input The wibox’s input shape as a (native) cairo surface.
-- @tparam color args.bg The background.
-- @tparam surface args.bgimage The background image of the drawable.
-- @tparam color args.fg The foreground (text) color.
-- @tparam gears.shape args.shape The shape.
-- @tparam[opt=false] boolean args.input_passthrough If the inputs are
-- forward to the element below.

5
docs/load_ldoc.cmake
View File

@ -13,8 +13,11 @@ foreach(doc_file_name ${doc_files})
# Remove the file extension
string(REGEX REPLACE "\\.ldoc" "" DOC_FILE_NAME ${doc_file_name})
# There is a trailing \n, remove it or it cannot be included in existing blocks
string(REGEX REPLACE "\n$" "" doc_file_content "${doc_file_content}")
# Create a new variable usable from lua files
set(DOC_${DOC_FILE_NAME}_COMMON "Imported documentation\n\n${doc_file_content}")
set(DOC_${DOC_FILE_NAME}_COMMON "${doc_file_content}")
endforeach()
# vim: filetype=cmake:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80:foldmethod=marker

72
lib/awful/wibar.lua
View File

@ -339,37 +339,19 @@ end
-- You can also set the screen key with a screen number to attach the wibox.
-- If not specified, the primary screen is assumed.
-- @see wibox
-- @tparam[opt=nil] table arg
-- @tparam string arg.position The position.
-- @tparam string arg.stretch If the wibar need to be stretched to fill the screen.
-- @tparam integer arg.border_width Border width.
-- @tparam string arg.border_color Border color.
-- @tparam boolean arg.ontop On top of other windows.
-- @tparam string arg.cursor The mouse cursor.
-- @tparam boolean arg.visible Visibility.
-- @tparam number arg.opacity The wibar's opacity, between 0 and 1.
-- @tparam string arg.type The window type (desktop, normal, dock, …).
-- @tparam integer arg.x The x coordinates.
-- @tparam integer arg.y The y coordinates.
-- @tparam integer arg.width The wibar's width.
-- @tparam integer arg.height The wibar's height.
-- @tparam screen arg.screen The wibox screen.
-- @tparam wibox.widget arg.widget The widget that the wibox displays.
-- @param arg.shape_bounding The wibox’s bounding shape as a (native) cairo surface.
-- @param arg.shape_clip The wibox’s clip shape as a (native) cairo surface.
-- @param arg.shape_input The wibox’s input shape as a (native) cairo surface.
-- @tparam color arg.bg The wibar's background.
-- @tparam surface arg.bgimage The background image of the drawable.
-- @tparam color arg.fg The wibar's foreground (text) color.
-- @tparam[opt=nil] table args
-- @tparam string args.position The position.
-- @tparam string args.stretch If the wibar need to be stretched to fill the screen.
--@DOC_wibox_constructor_COMMON@
-- @return The new wibar
-- @function awful.wibar
function awfulwibar.new(arg)
arg = arg or {}
local position = arg.position or "top"
function awfulwibar.new(args)
args = args or {}
local position = args.position or "top"
local has_to_stretch = true
local screen = get_screen(arg.screen or 1)
local screen = get_screen(args.screen or 1)
arg.type = arg.type or "dock"
args.type = args.type or "dock"
if position ~= "top" and position ~="bottom"
and position ~= "left" and position ~= "right" then
@ -379,48 +361,48 @@ function awfulwibar.new(arg)
-- Set default size
if position == "left" or position == "right" then
arg.width = arg.width or beautiful["wibar_width"]
or math.ceil(beautiful.get_font_height(arg.font) * 1.5)
if arg.height then
args.width = args.width or beautiful["wibar_width"]
or math.ceil(beautiful.get_font_height(args.font) * 1.5)
if args.height then
has_to_stretch = false
if arg.screen then
local hp = tostring(arg.height):match("(%d+)%%")
if args.screen then
local hp = tostring(args.height):match("(%d+)%%")
if hp then
arg.height = math.ceil(screen.geometry.height * hp / 100)
args.height = math.ceil(screen.geometry.height * hp / 100)
end
end
end
else
arg.height = arg.height or beautiful["wibar_height"]
or math.ceil(beautiful.get_font_height(arg.font) * 1.5)
if arg.width then
args.height = args.height or beautiful["wibar_height"]
or math.ceil(beautiful.get_font_height(args.font) * 1.5)
if args.width then
has_to_stretch = false
if arg.screen then
local wp = tostring(arg.width):match("(%d+)%%")
if args.screen then
local wp = tostring(args.width):match("(%d+)%%")
if wp then
arg.width = math.ceil(screen.geometry.width * wp / 100)
args.width = math.ceil(screen.geometry.width * wp / 100)
end
end
end
end
arg.screen = nil
args.screen = nil
-- The C code scans the table directly, so metatable magic cannot be used.
for _, prop in ipairs {
"border_width", "border_color", "font", "opacity", "ontop", "cursor",
"bgimage", "bg", "fg", "type", "stretch", "shape"
} do
if (arg[prop] == nil) and beautiful["wibar_"..prop] ~= nil then
arg[prop] = beautiful["wibar_"..prop]
if (args[prop] == nil) and beautiful["wibar_"..prop] ~= nil then
args[prop] = beautiful["wibar_"..prop]
end
end
local w = wibox(arg)
local w = wibox(args)
w.screen = screen
w._screen = screen --HACK When a screen is removed, then getbycoords wont work
w._stretch = arg.stretch == nil and has_to_stretch or arg.stretch
w._stretch = args.stretch == nil and has_to_stretch or args.stretch
w.get_position = get_position
w.set_position = set_position
@ -429,7 +411,7 @@ function awfulwibar.new(arg)
w.set_stretch = set_stretch
w.remove = remove
if arg.visible == nil then w.visible = true end
if args.visible == nil then w.visible = true end
-- `w` needs to be inserted in `wiboxes` before reattach or its own offset
-- will not be taken into account by the "older" wibars when `reattach` is

20
lib/wibox/init.lua
View File

@ -236,25 +236,7 @@ end
--- Create a wibox.
-- @tparam[opt=nil] table args
-- @tparam integer args.border_width Border width.
-- @tparam string args.border_color Border color.
-- @tparam boolean args.ontop On top of other windows.
-- @tparam string args.cursor The mouse cursor.
-- @tparam boolean args.visible Visibility.
-- @tparam number args.opacity The opacity of the wibox, between 0 and 1.
-- @tparam string args.type The window type (desktop, normal, dock, …).
-- @tparam integer args.x The x coordinates.
-- @tparam integer args.y The y coordinates.
-- @tparam integer args.width The width of the wibox.
-- @tparam integer args.height The height of the wibox.
-- @tparam screen args.screen The wibox screen.
-- @tparam wibox.widget args.widget The widget that the wibox displays.
-- @param args.shape_bounding The wibox’s bounding shape as a (native) cairo surface.
-- @param args.shape_clip The wibox’s clip shape as a (native) cairo surface.
-- @param args.shape_input The wibox’s input shape as a (native) cairo surface.
-- @tparam color args.bg The background of the wibox.
-- @tparam surface args.bgimage The background image of the drawable.
-- @tparam color args.fg The foreground (text) of the wibox.
--@DOC_wibox_constructor_COMMON@
-- @treturn wibox The new wibox
-- @function .wibox