From 89f796b2689095b46cb43860c433610e00eeb129 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sat, 23 Jul 2016 18:26:27 -0400 Subject: [PATCH 01/17] doc: Fix copy paste mistake. --- lib/wibox/widget/progressbar.lua | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/lib/wibox/widget/progressbar.lua b/lib/wibox/widget/progressbar.lua index 1b8d7d216..ddf1b151b 100644 --- a/lib/wibox/widget/progressbar.lua +++ b/lib/wibox/widget/progressbar.lua @@ -69,13 +69,13 @@ local data = setmetatable({}, { __mode = "k" }) -- @param value The value. --- The progressbar background color. --- @beautiful beautiful.graph_bg +-- @beautiful beautiful.progressbar_bg --- The progressbar foreground color. --- @beautiful beautiful.graph_fg +-- @beautiful beautiful.progressbar_fg --- The progressbar border color. --- @beautiful beautiful.graph_border_color +-- @beautiful beautiful.progressbar_border_color local properties = { "width", "height", "border_color", "color", "background_color", From 2b6ff1b3ca92ba2069d2cb9199ced46accff56ae Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Fri, 5 Aug 2016 00:44:32 -0400 Subject: [PATCH 02/17] taglist: Add more documentation --- lib/awful/widget/taglist.lua | 20 ++++++++++++++++++-- 1 file changed, 18 insertions(+), 2 deletions(-) diff --git a/lib/awful/widget/taglist.lua b/lib/awful/widget/taglist.lua index df2b4eae2..38a39434e 100644 --- a/lib/awful/widget/taglist.lua +++ b/lib/awful/widget/taglist.lua @@ -141,9 +141,25 @@ end -- @param screen The screen to draw taglist for. -- @param filter Filter function to define what clients will be listed. -- @param buttons A table with buttons binding to set. --- @param style The style overrides default theme. +-- @tparam[opt={}] table style The style overrides default theme. +-- @tparam[opt=nil] string|pattern style.fg_focus +-- @tparam[opt=nil] string|pattern style.bg_focus +-- @tparam[opt=nil] string|pattern style.fg_urgent +-- @tparam[opt=nil] string|pattern style.bg_urgent +-- @tparam[opt=nil] string|pattern style.bg_occupied +-- @tparam[opt=nil] string|pattern style.fg_occupied +-- @tparam[opt=nil] string|pattern style.bg_empty +-- @tparam[opt=nil] string|pattern style.fg_empty +-- @tparam[opt=nil] string style.taglist_squares_sel +-- @tparam[opt=nil] string style.taglist_squares_unsel +-- @tparam[opt=nil] string style.taglist_squares_sel_empty +-- @tparam[opt=nil] string style.taglist_squares_unsel_empty +-- @tparam[opt=nil] string style.taglist_squares_resize +-- @tparam[opt=nil] string style.taglist_disable_icon +-- @tparam[opt=nil] string style.font +-- @tparam[opt=nil] number style.spacing The spacing between tags. -- @param[opt] update_function Function to create a tag widget on each --- update. @see awful.widget.common. +-- update. See `awful.widget.common`. -- @param[opt] base_widget Optional container widget for tag widgets. Default -- is wibox.layout.fixed.horizontal(). -- @param base_widget.bg_focus The background color for focused client. From bb96f948451fac6cc1bfdd69f42505f4c4a0c715 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Fri, 5 Aug 2016 01:32:53 -0400 Subject: [PATCH 03/17] tasklist: Add some documentation --- lib/awful/widget/tasklist.lua | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/lib/awful/widget/tasklist.lua b/lib/awful/widget/tasklist.lua index 74e2e986e..7d145c3df 100644 --- a/lib/awful/widget/tasklist.lua +++ b/lib/awful/widget/tasklist.lua @@ -149,7 +149,24 @@ end -- @param screen The screen to draw tasklist for. -- @param filter Filter function to define what clients will be listed. -- @param buttons A table with buttons binding to set. --- @param style The style overrides default theme. +-- @tparam[opt={}] table style The style overrides default theme. +-- @tparam[opt=nil] string|pattern style.fg_normal +-- @tparam[opt=nil] string|pattern style.bg_normal +-- @tparam[opt=nil] string|pattern style.fg_focus +-- @tparam[opt=nil] string|pattern style.bg_focus +-- @tparam[opt=nil] string|pattern style.fg_urgent +-- @tparam[opt=nil] string|pattern style.bg_urgent +-- @tparam[opt=nil] string|pattern style.fg_minimize +-- @tparam[opt=nil] string|pattern style.bg_minimize +-- @tparam[opt=nil] string style.bg_image_normal +-- @tparam[opt=nil] string style.bg_image_focus +-- @tparam[opt=nil] string style.bg_image_urgent +-- @tparam[opt=nil] string style.bg_image_minimize +-- @tparam[opt=nil] boolean style.tasklist_disable_icon +-- @tparam[opt=nil] string style.font +-- @tparam[opt=nil] string style.font_focus +-- @tparam[opt=nil] string style.font_minimized +-- @tparam[opt=nil] string style.font_urgent -- @param[opt] update_function Function to create a tag widget on each -- update. See `awful.widget.common.list_update`. -- @tparam[opt] table base_widget Container widget for tag widgets. Default From 50b6c82091a2877e8232a7381a8dafce873e4b31 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Thu, 11 Aug 2016 19:55:46 -0400 Subject: [PATCH 04/17] shim: Add basic button support --- tests/examples/shims/_common_template.lua | 3 ++- tests/examples/shims/button.lua | 3 +++ 2 files changed, 5 insertions(+), 1 deletion(-) create mode 100644 tests/examples/shims/button.lua diff --git a/tests/examples/shims/_common_template.lua b/tests/examples/shims/_common_template.lua index 021b09fc6..cfbb25ccb 100644 --- a/tests/examples/shims/_common_template.lua +++ b/tests/examples/shims/_common_template.lua @@ -1,7 +1,7 @@ return function(_, _, luacovpath) -- Set the global shims - -- luacheck: globals awesome root tag screen client mouse drawin + -- luacheck: globals awesome root tag screen client mouse drawin button awesome = require( "awesome" ) root = require( "root" ) tag = require( "tag" ) @@ -9,6 +9,7 @@ return function(_, _, luacovpath) client = require( "client" ) mouse = require( "mouse" ) drawin = require( "drawin" ) + button = require( "button" ) -- Force luacheck to be silent about setting those as unused globals assert(awesome and root and tag and screen and client and mouse) diff --git a/tests/examples/shims/button.lua b/tests/examples/shims/button.lua new file mode 100644 index 000000000..f3170d89e --- /dev/null +++ b/tests/examples/shims/button.lua @@ -0,0 +1,3 @@ +return function() return { + connect_signal = function() end +} end From 5f10e7a74ee4d79648a1349db6fbf2b0d82b6489 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Fri, 12 Aug 2016 02:01:45 -0400 Subject: [PATCH 05/17] doc: Begin to document the themes better. This add a meta-lua file that parses all existing lua files to generate a list of all beautiful variables. --- CMakeLists.txt | 4 +- awesomeConfig.cmake | 7 ++ docs/06-appearance.md.lua | 224 ++++++++++++++++++++++++++++++++++++++ docs/config.ld | 1 + 4 files changed, 235 insertions(+), 1 deletion(-) create mode 100644 docs/06-appearance.md.lua diff --git a/CMakeLists.txt b/CMakeLists.txt index cf8045e33..4e6a93c7a 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -276,7 +276,9 @@ if(GENERATE_DOC) add_custom_target(ldoc ALL COMMAND ${LDOC_EXECUTABLE} . 3>&1 1>&2 2>&3 | awk "{ fail=1 \; print } END { exit fail }" WORKING_DIRECTORY ${AWE_DOC_DIR} - DEPENDS ${AWE_LUA_FILES} ${AWE_MD_FILES}) + DEPENDS ${AWE_LUA_FILES} ${AWE_MD_FILES} ${BUILD_DIR}/docs/06-appearance.md + ) + endif() # }}} diff --git a/awesomeConfig.cmake b/awesomeConfig.cmake index 1771daa5e..c17362e40 100644 --- a/awesomeConfig.cmake +++ b/awesomeConfig.cmake @@ -340,6 +340,13 @@ foreach(file ${AWESOME_CONFIGURE_FILES}) endforeach() #}}} +# {{{ Generate some aggregated documentation from lua script +add_custom_command( + OUTPUT ${BUILD_DIR}/docs/06-appearance.md + COMMAND lua ${SOURCE_DIR}/docs/06-appearance.md.lua + ${BUILD_DIR}/docs/06-appearance.md +) + # {{{ Copy additional files file(GLOB awesome_md_docs RELATIVE ${SOURCE_DIR} ${SOURCE_DIR}/docs/*.md) diff --git a/docs/06-appearance.md.lua b/docs/06-appearance.md.lua new file mode 100644 index 000000000..5675ee494 --- /dev/null +++ b/docs/06-appearance.md.lua @@ -0,0 +1,224 @@ +#! /usr/bin/lua +local args = {...} + +local gio = require("lgi").Gio +local gobject = require("lgi").GObject +local glib = require("lgi").GLib + +local name_attr = gio.FILE_ATTRIBUTE_STANDARD_NAME +local type_attr = gio.FILE_ATTRIBUTE_STANDARD_TYPE + +-- Recursive file scanner +local function get_all_files(path, ext, ret) + ret = ret or {} + local enumerator = gio.File.new_for_path(path):enumerate_children( + table.concat({name_attr, type_attr}, ",") , 0, nil, nil + ) + + for file in function() return enumerator:next_file() end do + local file_name = file:get_attribute_as_string(name_attr) + local file_type = file:get_file_type() + if file_type == "REGULAR" and file_name:match(ext or "") then + table.insert(ret, enumerator:get_child(file):get_path()) + elseif file_type == "DIRECTORY" then + get_all_files(enumerator:get_child(file):get_path(), ext, ret) + end + end + + return ret +end + +local function path_to_module(path) + for _, module in ipairs { + "awful", "wibox", "gears", "naughty", "menubar", "beautiful" + } do + local match = path:match("/"..module.."/([^.]+).lua") + if match then + return module.."."..match:gsub("/",".") + end + end + + error("Cannot figure out module for " .. tostring(path)) +end + +local function module_to_html(mod) + mod = mod:gsub(".init", "") + + local f = io.open("doc/classes/".. mod ..".html","r") + + if f~=nil then + f:close() + return "../classes/".. mod ..".html" + end + + f = io.open("doc/libraries/".. mod ..".html","r") + + if f~=nil then + f:close() + return "../libraries/".. mod ..".html" + end + + -- This can happen + return "" +end + +local function get_link(file, element) + return table.concat { + "", + element:match("[. ](.+)"), + "" + } +end + +local all_files = get_all_files("./lib/", "lua") + +local beautiful_vars = {} + +-- Find all @beautiful doc entries +for _,file in ipairs(all_files) do + local f = io.open(file) + + local buffer = "" + + for line in f:lines() do + + local var = line:gmatch("--[ ]*@beautiful ([^ \n]*)")() + + -- There is no backward/forward pattern in lua + if #line <= 1 then + buffer = "" + elseif #buffer and not var then + buffer = buffer.."\n"..line + elseif line:sub(1,3) == "---" then + buffer = line + end + + + if var then + -- Get the @param, @see and @usage + local params = "" + for line in f:lines() do + if line:sub(1,2) ~= "--" then + break + else + params = params.."\n"..line + end + end + + local name = var:gmatch("[ ]*beautiful.(.+)")() + if not name then + print("WARNING:", var, + "seems to be misformatted. Use `beautiful.namespace_name`" + ) + else + table.insert(beautiful_vars, { + file = file, + name = name, + link = get_link(file, var), + desc = buffer:gmatch("[- ]+([^\n.]*)")() or "", + mod = path_to_module(file), + }) + end + + buffer = "" + end + end +end + +local function create_table(entries, columns) + local lines = {} + + for _, entry in ipairs(entries) do + local line = " " + + for _, column in ipairs(columns) do + line = line..""..entry[column].."" + end + + table.insert(lines, line.."\n") + end + + return [[

+ + + + ]] .. table.concat(lines) .. "
NameDescription
\n" +end + +local override_cats = { + ["border" ] = true, + ["bg" ] = true, + ["fg" ] = true, + ["useless" ] = true, + ["" ] = true, +} + +local function categorize(entries) + local ret = {} + + local cats = { + ["Default variables"] = {} + } + + for _, v in ipairs(entries) do + local ns = v.name:match("([^_]+)_") or "" + ns = override_cats[ns] and "Default variables" or ns + cats[ns] = cats[ns] or {} + table.insert(cats[ns], v) + end + + return cats +end + +local function create_sample(entries) + local ret = { + " local theme = {}" + } + + for name, cat in pairs(categorize(entries)) do + table.insert(ret, "\n -- "..name) + for _, v in ipairs(cat) do + table.insert(ret, " -- theme."..v.name.." = nil") + end + end + + table.insert(ret, [[ + + return theme + + -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80]] + ) + + return table.concat(ret, '\n') +end + +-- Create the file +local filename = args[1] + +local f = io.open(filename, "w") + +f:write[[ +# Change Awesome appearance + +## The beautiful themes + +Beautiful is where Awesome theme variables are stored. + +]] +f:write(create_table(beautiful_vars, {"link", "desc"})) + +f:write("\n\n## Sample theme file\n\n") + +f:write(create_sample(beautiful_vars, {"link", "desc"})) + +f:close() + +--TODO add some linting to direct undeclared beautiful variables +--TODO re-generate all official themes +--TODO generate a complete sample theme +--TODO also parse C files. + diff --git a/docs/config.ld b/docs/config.ld index 9a20dded9..939b74de9 100644 --- a/docs/config.ld +++ b/docs/config.ld @@ -21,6 +21,7 @@ topics={ '02-contributing.md', '03-declarative-layout.md', '04-new-widgets.md', + '06-appearance.md', '16-using-cairo.md', '90-FAQ.md', } From abd2a271afae89caadfb04e9dde19cc279392ec8 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Fri, 12 Aug 2016 02:23:19 -0400 Subject: [PATCH 06/17] doc: Document menu variables. --- lib/awful/menu.lua | 43 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/lib/awful/menu.lua b/lib/awful/menu.lua index 92c89ce0a..63b969f0f 100644 --- a/lib/awful/menu.lua +++ b/lib/awful/menu.lua @@ -48,6 +48,49 @@ local table_update = function (t, set) return t end +--- The icon used for sub-menus. +-- @beautiful beautiful.menu_submenu_icon + +--- The item height. +-- @beautiful beautiful.menu_height +-- @tparam[opt=16] number menu_height + +--- The default menu width. +-- @beautiful beautiful.menu_width +-- @tparam[opt=100] number menu_width + +--- The menu item border color. +-- @beautiful beautiful.menu_border_color +-- @tparam[opt=0] number menu_border_color + +--- The menu item border width. +-- @beautiful beautiful.menu_border_width +-- @tparam[opt=0] number menu_border_width + +--- The default focused item foreground (text) color. +-- @beautiful beautiful.menu_fg_focus +-- @param color +-- @see gears.color + +--- The default focused item background color. +-- @beautiful beautiful.menu_bg_focus +-- @param color +-- @see gears.color + +--- The default foreground (text) color. +-- @beautiful beautiful.menu_fg_normal +-- @param color +-- @see gears.color + +--- The default background color. +-- @beautiful beautiful.menu_bg_normal +-- @param color +-- @see gears.color + +--- The default sub-menu indicator if no menu_submenu_icon is provided. +-- @beautiful beautiful.menu_submenu +-- @tparam[opt="▶"] string menu_submenu The sub-menu text. +-- @see beautiful.menu_submenu_icon --- Key bindings for menu navigation. -- Keys are: up, down, exec, enter, back, close. Value are table with a list of valid From be8f0c376be39392319fef51e44b7ebff069d0db Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Fri, 12 Aug 2016 02:34:03 -0400 Subject: [PATCH 07/17] doc: Document the basic variables. --- lib/beautiful/init.lua | 60 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) diff --git a/lib/beautiful/init.lua b/lib/beautiful/init.lua index 5fb140480..cca92293a 100644 --- a/lib/beautiful/init.lua +++ b/lib/beautiful/init.lua @@ -30,6 +30,66 @@ local descs = setmetatable({}, { __mode = 'k' }) local fonts = setmetatable({}, { __mode = 'v' }) local active_font +--- The default font. +-- @beautiful beautiful.font + +-- The default background color. +-- @beautiful beautiful.bg_normal + +-- The default focused element background color. +-- @beautiful beautiful.bg_focus + +-- The default urgent element background color. +-- @beautiful beautiful.bg_urgent + +-- The default minimized element background color. +-- @beautiful beautiful.bg_minimize + +-- The system tray background color. +-- Please note that only solid colors are currently supported. +-- @beautiful beautiful.bg_systray + +-- The default focused element foreground (text) color. +-- @beautiful beautiful.fg_normal + +-- The default focused element foreground (text) color. +-- @beautiful beautiful.fg_focus + +-- The default urgent element foreground (text) color. +-- @beautiful beautiful.fg_urgent + +-- The default minimized element foreground (text) color. +-- @beautiful beautiful.fg_minimize + +--- The gap between clients. +-- @beautiful beautiful.useless_gap +-- @param[opt=0] number + +--- The client border width. +-- @beautiful beautiful.border_width + +--- The default clients border width. +-- Note that only solid colors are supported. +-- @beautiful beautiful.border_normal + +--- The focused client border width. +-- Note that only solid colors are supported. +-- @beautiful beautiful.border_focus + +--- The marked clients border width. +-- Note that only solid colors are supported. +-- @beautiful beautiful.border_marked + +--- The wallpaper path. +-- @beautiful beautiful.wallpaper + +-- The icon theme name. +-- It has to be a directory in `/usr/share/icons` or an XDG icon folder. +-- @beautiful beautiful.icon_theme + +--- The Awesome icon path. +-- @beautiful beautiful.awesome_icon + --- Load a font from a string or a font description. -- -- @see https://developer.gnome.org/pango/stable/pango-Fonts.html#pango-font-description-from-string From 63b712e24704f3998ab9f96664e6e56a5d5b8518 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Fri, 12 Aug 2016 15:18:27 -0400 Subject: [PATCH 08/17] doc: Document rc.lua This meta-lua script takes the "raw" awesomerc.lua and turn it into the final file and generate a documentation page from its parsed content. It support * Turn {{{ into markdown categories * Turn top level comments into documentation * Add custom documentation sections * Parse the code to add links for each API calls This helps generate a good entry point for new users wanting to understand the content of rc.lua without searching the API by hand. Over time, this will also become the basis of the documentation. If `rc.lua` is separated into several files, this will be easy to fix this script. It could even do the separation itself from a monolitic file using the already implemented {{{ parser. --- CMakeLists.txt | 1 + awesomeConfig.cmake | 10 +- awesomerc.lua | 27 ++++- docs/05-awesomerc.md.lua | 241 +++++++++++++++++++++++++++++++++++++++ docs/config.ld | 1 + 5 files changed, 278 insertions(+), 2 deletions(-) create mode 100644 docs/05-awesomerc.md.lua diff --git a/CMakeLists.txt b/CMakeLists.txt index 4e6a93c7a..275e8e03a 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -277,6 +277,7 @@ if(GENERATE_DOC) COMMAND ${LDOC_EXECUTABLE} . 3>&1 1>&2 2>&3 | awk "{ fail=1 \; print } END { exit fail }" WORKING_DIRECTORY ${AWE_DOC_DIR} DEPENDS ${AWE_LUA_FILES} ${AWE_MD_FILES} ${BUILD_DIR}/docs/06-appearance.md + ${BUILD_DIR}/docs/05-awesomerc.md ) endif() diff --git a/awesomeConfig.cmake b/awesomeConfig.cmake index c17362e40..192865069 100644 --- a/awesomeConfig.cmake +++ b/awesomeConfig.cmake @@ -329,7 +329,6 @@ set(AWESOME_CONFIGURE_FILES ${awesome_lua_configure_files} config.h docs/config.ld - awesomerc.lua awesome-version-internal.h) foreach(file ${AWESOME_CONFIGURE_FILES}) @@ -347,6 +346,15 @@ add_custom_command( ${BUILD_DIR}/docs/06-appearance.md ) +add_custom_command( + OUTPUT ${BUILD_DIR}/awesomerc.lua ${BUILD_DIR}/docs/05-awesomerc.md + COMMAND lua ${SOURCE_DIR}/docs/05-awesomerc.md.lua + ${BUILD_DIR}/docs/05-awesomerc.md ${SOURCE_DIR}/awesomerc.lua + ${BUILD_DIR}/awesomerc.lua +) + +#}}} + # {{{ Copy additional files file(GLOB awesome_md_docs RELATIVE ${SOURCE_DIR} ${SOURCE_DIR}/docs/*.md) diff --git a/awesomerc.lua b/awesomerc.lua index 7edb28278..287a916dd 100755 --- a/awesomerc.lua +++ b/awesomerc.lua @@ -1,3 +1,4 @@ +-- @DOC_REQUIRE_SECTION@ -- Standard awesome library local gears = require("gears") local awful = require("awful") @@ -12,6 +13,7 @@ local menubar = require("menubar") local hotkeys_popup = require("awful.hotkeys_popup").widget -- {{{ Error handling +-- @DOC_ERROR_HANDLING@ -- Check if awesome encountered an error during startup and fell back to -- another config (This code will only ever execute for the fallback config) if awesome.startup_errors then @@ -37,9 +39,11 @@ end -- }}} -- {{{ Variable definitions +-- @DOC_LOAD_THEME@ -- Themes define colours, icons, font and wallpapers. beautiful.init(awful.util.get_themes_dir() .. "default/theme.lua") +-- @DOC_DEFAULT_APPLICATIONS@ -- This is used later as the default terminal and editor to run. terminal = "xterm" editor = os.getenv("EDITOR") or "nano" @@ -52,6 +56,7 @@ editor_cmd = terminal .. " -e " .. editor -- However, you can use another modifier like Mod1, but it may interact with others. modkey = "Mod4" +-- @DOC_LAYOUT@ -- Table of layouts to cover with awful.layout.inc, order matters. awful.layout.layouts = { awful.layout.suit.floating, @@ -89,6 +94,7 @@ end -- }}} -- {{{ Menu +-- @DOC_MENU@ -- Create a launcher widget and a main menu myawesomemenu = { { "hotkeys", function() return false, hotkeys_popup.show_help end}, @@ -113,7 +119,7 @@ menubar.utils.terminal = terminal -- Set the terminal for applications that requ -- Keyboard map indicator and switcher mykeyboardlayout = awful.widget.keyboardlayout() --- {{{ Wibox +-- {{{ Wibar -- Create a textclock widget mytextclock = wibox.widget.textclock() @@ -122,6 +128,7 @@ mywibox = {} mypromptbox = {} mylayoutbox = {} mytaglist = {} +-- @TAGLIST_BUTTON@ mytaglist.buttons = awful.util.table.join( awful.button({ }, 1, function(t) t:view_only() end), awful.button({ modkey }, 1, function(t) @@ -140,6 +147,7 @@ mytaglist.buttons = awful.util.table.join( ) mytasklist = {} +-- @TASKLIST_BUTTON@ mytasklist.buttons = awful.util.table.join( awful.button({ }, 1, function (c) if c == client.focus then @@ -165,7 +173,9 @@ mytasklist.buttons = awful.util.table.join( awful.client.focus.byidx(-1) end)) +-- @DOC_WALLPAPER@ local function set_wallpaper(s) + -- Wallpaper if beautiful.wallpaper then local wallpaper = beautiful.wallpaper -- If wallpaper is a function, call it with the screen @@ -179,6 +189,7 @@ end -- Re-set wallpaper when a screen's geometry changes (e.g. different resolution) screen.connect_signal("property::geometry", set_wallpaper) +-- @DOC_FOR_EACH_SCREEN@ awful.screen.connect_for_each_screen(function(s) -- Wallpaper set_wallpaper(s) @@ -202,9 +213,11 @@ awful.screen.connect_for_each_screen(function(s) -- Create a tasklist widget mytasklist[s] = awful.widget.tasklist(s, awful.widget.tasklist.filter.currenttags, mytasklist.buttons) + -- @DOC_WIBAR@ -- Create the wibox mywibox[s] = awful.wibar({ position = "top", screen = s }) + -- @DOC_SETUP_WIDGETS@ -- Add widgets to the wibox mywibox[s]:setup { layout = wibox.layout.align.horizontal, @@ -227,6 +240,7 @@ end) -- }}} -- {{{ Mouse bindings +-- @DOC_ROOT_BUTTONS@ root.buttons(awful.util.table.join( awful.button({ }, 3, function () mymainmenu:toggle() end), awful.button({ }, 4, awful.tag.viewnext), @@ -235,6 +249,7 @@ root.buttons(awful.util.table.join( -- }}} -- {{{ Key bindings +-- @DOC_GLOBAL_KEYBINDINGS@ globalkeys = awful.util.table.join( awful.key({ modkey, }, "s", hotkeys_popup.show_help, {description="show help", group="awesome"}), @@ -333,6 +348,7 @@ globalkeys = awful.util.table.join( {description = "show the menubar", group = "launcher"}) ) +-- @DOC_CLIENT_KEYBINDINGS@ clientkeys = awful.util.table.join( awful.key({ modkey, }, "f", function (c) @@ -365,6 +381,7 @@ clientkeys = awful.util.table.join( {description = "maximize", group = "client"}) ) +-- @DOC_NUMBER_KEYBINDINGS@ -- Bind all key numbers to tags. -- Be careful: we use keycodes to make it works on any keyboard layout. -- This should map on the top row of your keyboard, usually 1 to 9. @@ -415,6 +432,7 @@ for i = 1, 9 do ) end +-- @DOC_CLIENT_BUTTONS@ clientbuttons = awful.util.table.join( awful.button({ }, 1, function (c) client.focus = c; c:raise() end), awful.button({ modkey }, 1, awful.mouse.client.move), @@ -426,7 +444,9 @@ root.keys(globalkeys) -- {{{ Rules -- Rules to apply to new clients (through the "manage" signal). +-- @DOC_RULES@ awful.rules.rules = { + -- @DOC_GLOBAL_RULE@ -- All clients will match this rule. { rule = { }, properties = { border_width = beautiful.border_width, @@ -440,6 +460,7 @@ awful.rules.rules = { } }, + -- @DOC_FLOATING_RULE@ -- Floating clients. { rule_any = { instance = { @@ -466,6 +487,7 @@ awful.rules.rules = { } }, properties = { floating = true }}, + -- @DOC_DIALOG_RULE@ -- Add titlebars to normal clients and dialogs { rule_any = {type = { "normal", "dialog" } }, properties = { titlebars_enabled = true } @@ -479,6 +501,7 @@ awful.rules.rules = { -- {{{ Signals -- Signal function to execute when a new client appears. +-- @DOC_MANAGE_HOOK@ client.connect_signal("manage", function (c) -- Set the windows at the slave, -- i.e. put it at the end of others instead of setting it master. @@ -492,6 +515,7 @@ client.connect_signal("manage", function (c) end end) +-- @DOC_TITLEBARS@ -- Add a titlebar if titlebars_enabled is set to true in the rules. client.connect_signal("request::titlebars", function(c) -- buttons for the titlebar @@ -542,6 +566,7 @@ client.connect_signal("mouse::enter", function(c) end end) +-- @DOC_BORDER@ client.connect_signal("focus", function(c) c.border_color = beautiful.border_focus end) client.connect_signal("unfocus", function(c) c.border_color = beautiful.border_normal end) -- }}} diff --git a/docs/05-awesomerc.md.lua b/docs/05-awesomerc.md.lua new file mode 100644 index 000000000..9e41f88b6 --- /dev/null +++ b/docs/05-awesomerc.md.lua @@ -0,0 +1,241 @@ +local filename, rcfile, new_rcfile = ... + +local f = io.open(filename, "w") + +f:write[[# Default configuration file documentation + +This document explain the default `rc.lua` file provided by Awesome. + +]] + +-- Document sections of the file to guide new users to the right doc pages + +local sections = {} + +sections.DOC_REQUIRE_SECTION = [[ +Awesome API is distributed across many libraries (also called modules). + +Here is the modules being imported: + + + + + + + + +
`gears`Utilities such as color parsing and objects
`wibox`Awesome own generic widget framework
`awful`Everything related to window managment
`naughty`Notifications
`menubar`XDG (application) menu implementation
`beautiful`Awesome theme module
+ +]] + +sections.DOC_ERROR_HANDLING = [[ +Awesome is a window managing framework. It allows its users great (ultimate?) +flexibility. However, it also allows the user to write invalid code. There is +multiple "levels" of problems: + + * Syntax: There is an `awesome -k` option available in the command line to + check this. Awesome cannot start with an invalid `rc.lua` + * Invalid APIs and type errors: Lua is a dynamic language. It doesn't have much + support for static/compile time checks. There is the `luacheck` utility to + help find some categories of errors. Those errors will cause Awesome to + "drop" the current call stack and start over. Note that if the config cannot + reach the end of the `rc.lua` without errors, it will fallback to the + original file. + * Invalid logic: It is possible to write fully valid code that will leave + Awesome unusable (like an infinite loop or blocking commands). In that case, + the best way to debug this is either using `print()` or using `gdb`. For + this, see the [Debugging tips Readme section](../documentation/01-readme.md.html) + * Deprecated APIs: Awesome API is not frozen for eternity. While after a + decade and recent changes to enforce consistency, it doesn't change as much, + it will likely be changed in the future. When possible, changes wont cause + errors but will instead print a deprecation message in Awesome logs. Those + logs are placed in various places depending on the distribution. By default, + Awesome will print this on stderr and stdout. + + +]] + + +sections.DOC_LOAD_THEME = [[ +To create custom themes, the easiest way is to copy the `default` theme folder +from `/usr/share/awesome/themes/` into `~/.config/awesome` and modify it. + +Awesome currently doesn't behave well without a theme containing all the "basic" +variables such as `bg_normal`. To get a list of all official variables, see +the [appearance guide](../documentation/06-appearance.md.html). +]] + + +sections.DOC_DEFAULT_APPLICATIONS = [[ +   +]] + + +sections.DOC_LAYOUT = [[ +   +]] + + +sections.DOC_MENU = [[ +   +]] + + +sections.TAGLIST_BUTTON = [[ +   +]] + + +sections.TASKLIST_BUTTON = [[ +   +]] + + +sections.DOC_FOR_EACH_SCREEN = [[ +   +]] + + +sections.DOC_WIBAR = [[ +   +]] + + +sections.DOC_SETUP_WIDGETS = [[ +   +]] + + +sections.DOC_ROOT_BUTTONS = [[ +   +]] + + +sections.DOC_GLOBAL_KEYBINDINGS = [[ +   +]] + + +sections.DOC_CLIENT_KEYBINDINGS = [[ +   +]] + + +sections.DOC_NUMBER_KEYBINDINGS = [[ +   +]] + + +sections.DOC_CLIENT_BUTTONS = [[ +   +]] + + +sections.DOC_RULES = [[ +   +]] + + +sections.DOC_GLOBAL_RULE = [[ +   +]] + + +sections.DOC_FLOATING_RULE = [[ +   +]] + + +sections.DOC_DIALOG_RULE = [[ +   +]] + + +sections.DOC_MANAGE_HOOK = [[ +   +]] + + +sections.DOC_TITLEBARS = [[ +   +]] + + +sections.DOC_BORDER = [[ +   +]] + +-- Ask ldoc to generate links + +local function add_links(line) + for _, module in ipairs { + "awful", "wibox", "gears", "naughty", "menubar", "beautiful" + } do + if line:match(module.."%.") then + line = line:gsub("("..module.."[.a-zA-Z]+)", "`%1`") + end + end + + return " "..line.."\n" +end + +-- Parse the default awesomerc.lua + +local rc = io.open(rcfile) + +local doc_block = false + +local output = {} + +for line in rc:lines() do + local tag = line:match("@([^@]+)@") + + if not tag then + local section = line:match("--[ ]*{{{[ ]*(.*)") + if line == "-- }}}" or line == "-- {{{" then + -- Hide some noise + elseif section then + -- Turn Vim sections into markdown sections + if doc_block then + f:write("\n") + doc_block = false + end + f:write("## "..section.."\n") + elseif line:sub(1,2) == "--" then + -- Display "top level" comments are normal text. + if doc_block then + f:write("\n") + doc_block = false + end + f:write(line:sub(3).."\n") + else + -- Write the code in sections + if not doc_block then + f:write("\n") + doc_block = true + end + f:write(add_links(line)) + end + table.insert(output, line) + else + -- Take the documentation found in this file and append it + if doc_block then + f:write("\n") + doc_block = false + end + + if sections[tag] then + f:write(sections[tag]) + else + f:write(" \n\n") + end + end +end + +f:write("\n") + +f:close() + +local rc_lua = io.open(new_rcfile, "w") +rc_lua:write(table.concat(output, "\n")) +rc_lua:close() diff --git a/docs/config.ld b/docs/config.ld index 939b74de9..72505c8bc 100644 --- a/docs/config.ld +++ b/docs/config.ld @@ -21,6 +21,7 @@ topics={ '02-contributing.md', '03-declarative-layout.md', '04-new-widgets.md', + '05-awesomerc.md', '06-appearance.md', '16-using-cairo.md', '90-FAQ.md', From 4a8a1423e86b13fc366f1c115d03fd87239ff427 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sat, 13 Aug 2016 03:05:31 -0400 Subject: [PATCH 09/17] doc: Fix improper punctuation (causing an ldoc issue) --- lib/gears/object/properties.lua | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/gears/object/properties.lua b/lib/gears/object/properties.lua index f528482a7..d0c80e01b 100644 --- a/lib/gears/object/properties.lua +++ b/lib/gears/object/properties.lua @@ -27,7 +27,7 @@ local function cobj_register(cobj) return fallback end ---- Add the missing properties handler to a CAPI object such as client/tag/screen +--- Add the missing properties handler to a CAPI object such as client/tag/screen. -- Valid args: -- -- * **getter**: A smart getter (handle property getter itself) From d5aca4ccd7494f49a2f360eee328c885640dd4c9 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sat, 13 Aug 2016 03:13:25 -0400 Subject: [PATCH 10/17] doc: Fix gears.timer documentation --- lib/gears/timer.lua | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) diff --git a/lib/gears/timer.lua b/lib/gears/timer.lua index fbd69bcf5..2c39b8b49 100644 --- a/lib/gears/timer.lua +++ b/lib/gears/timer.lua @@ -4,7 +4,7 @@ -- @author Uli Schlachter -- @copyright 2014 Uli Schlachter -- @release @AWESOME_VERSION@ --- @module gears.timer +-- @classmod gears.timer --------------------------------------------------------------------------- local capi = { awesome = awesome } @@ -30,10 +30,13 @@ local protected_call = require("gears.protected_call") -- @table timer --- When the timer is started. --- @signal start +-- @signal .start --- When the timer is stopped. --- @signal stop +-- @signal .stop + +--- When the timer had a timeout event. +-- @signal .timeout local timer = { mt = {} } @@ -71,6 +74,15 @@ function timer:again() self:start() end +--- The timer is started. +-- @property started +-- @param boolean + +--- The timer timeout value. +-- **Signal:** property::timeout +-- @property timeout +-- @param number + local timer_instance_mt = { __index = function(self, property) if property == "timeout" then @@ -94,6 +106,7 @@ local timer_instance_mt = { -- @tparam table args Arguments. -- @tparam number args.timeout Timeout in seconds (e.g. 1.5). -- @treturn timer +-- @function gears.timer timer.new = function(args) local ret = object() @@ -115,6 +128,7 @@ end -- @tparam function callback Function to run. -- @treturn timer The timer object that was set up. -- @see timer.weak_start_new +-- @function gears.timer.start_new function timer.start_new(timeout, callback) local t = timer.new({ timeout = timeout }) t:connect_signal("timeout", function() @@ -136,6 +150,7 @@ end -- @tparam function callback Function to start. -- @treturn timer The timer object that was set up. -- @see timer.start_new +-- @function gears.timer.weak_start_new function timer.weak_start_new(timeout, callback) local indirection = setmetatable({}, { __mode = "v" }) indirection.callback = callback @@ -158,6 +173,7 @@ end) --- Call the given function at the end of the current main loop iteration -- @tparam function callback The function that should be called -- @param ... Arguments to the callback function +-- @function gears.timer.delayed_call function timer.delayed_call(callback, ...) assert(type(callback) == "function", "callback must be a function, got: " .. type(callback)) table.insert(delayed_calls, { callback, ... }) From 1b9f44c62d3df8bc951a28614cb1de0f006c456a Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 14 Aug 2016 00:25:31 -0400 Subject: [PATCH 11/17] doc: Document the titlebar theme variables. --- lib/awful/titlebar.lua | 185 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 185 insertions(+) diff --git a/lib/awful/titlebar.lua b/lib/awful/titlebar.lua index fa4df5de0..101b49b78 100644 --- a/lib/awful/titlebar.lua +++ b/lib/awful/titlebar.lua @@ -25,6 +25,191 @@ local titlebar = { widget = {} } +--- The titlebar foreground (text) color. +-- @beautiful beautiful.titlebar_fg_normal +-- @param color +-- @see gears.color + +--- The titlebar background color. +-- @beautiful beautiful.titlebar_bg_normal +-- @param color +-- @see gears.color + +--- The titlebar background image image. +-- @beautiful beautiful.titlebar_bgimage_normal +-- @param surface +-- @see gears.surface + +--- The titlebar foreground (text) color. +-- @beautiful beautiful.titlebar_fg +-- @param color +-- @see gears.color + +--- The titlebar background color. +-- @beautiful beautiful.titlebar_bg +-- @param color +-- @see gears.color + +--- The titlebar background image image. +-- @beautiful beautiful.titlebar_bgimage +-- @param surface +-- @see gears.surface + +--- The focused titlebar foreground (text) color. +-- @beautiful beautiful.titlebar_fg_focus +-- @param color +-- @see gears.color + +--- The focused titlebar background color. +-- @beautiful beautiful.titlebar_bg_focus +-- @param color +-- @see gears.color + +--- The focused titlebar background image image. +-- @beautiful beautiful.titlebar_bgimage_focus +-- @param surface +-- @see gears.surface + +--- floating_button_normal. +-- @beautiful beautiful.titlebar_floating_button_normal +-- @param surface +-- @see gears.surface + +--- maximized_button_normal. +-- @beautiful beautiful.titlebar_maximized_button_normal +-- @param surface +-- @see gears.surface + +--- minimize_button_normal +-- @beautiful beautiful.titlebar_minimize_button_normal +-- @param surface +-- @see gears.surface + +--- close_button_normal. +-- @beautiful beautiful.titlebar_close_button_normal +-- @param surface +-- @see gears.surface + +--- ontop_button_normal. +-- @beautiful beautiful.titlebar_ontop_button_normal +-- @param surface +-- @see gears.surface + +--- sticky_button_normal. +-- @beautiful beautiful.titlebar_sticky_button_normal +-- @param surface +-- @see gears.surface + +--- floating_button_focus. +-- @beautiful beautiful.titlebar_floating_button_focus +-- @param surface +-- @see gears.surface + +--- maximized_button_focus. +-- @beautiful beautiful.titlebar_maximized_button_focus +-- @param surface +-- @see gears.surface + +--- minimize_button_focus. +-- @beautiful beautiful.titlebar_minimize_button_focus +-- @param surface +-- @see gears.surface + +--- close_button_focus. +-- @beautiful beautiful.titlebar_close_button_focus +-- @param surface +-- @see gears.surface + +--- ontop_button_focus. +-- @beautiful beautiful.titlebar_ontop_button_focus +-- @param surface +-- @see gears.surface + +--- sticky_button_focus. +-- @beautiful beautiful.titlebar_sticky_button_focus +-- @param surface +-- @see gears.surface + +--- floating_button_normal_active. +-- @beautiful beautiful.titlebar_floating_button_normal_active +-- @param surface +-- @see gears.surface + +--- maximized_button_normal_active. +-- @beautiful beautiful.titlebar_maximized_button_normal_active +-- @param surface +-- @see gears.surface + +--- ontop_button_normal_active. +-- @beautiful beautiful.titlebar_ontop_button_normal_active +-- @param surface +-- @see gears.surface + +--- sticky_button_normal_active. +-- @beautiful beautiful.titlebar_sticky_button_normal_active +-- @param surface +-- @see gears.surface + +--- floating_button_focus_active. +-- @beautiful beautiful.titlebar_floating_button_focus_active +-- @param surface +-- @see gears.surface + +--- maximized_button_focus_active. +-- @beautiful beautiful.titlebar_maximized_button_focus_active +-- @param surface +-- @see gears.surface + +--- ontop_button_focus_active. +-- @beautiful beautiful.titlebar_ontop_button_focus_active +-- @param surface +-- @see gears.surface + +--- sticky_button_focus_active. +-- @beautiful beautiful.titlebar_sticky_button_focus_active +-- @param surface +-- @see gears.surface + +--- floating_button_normal_inactive. +-- @beautiful beautiful.titlebar_floating_button_normal_inactive +-- @param surface +-- @see gears.surface + +--- maximized_button_normal_inactive. +-- @beautiful beautiful.titlebar_maximized_button_normal_inactive +-- @param surface +-- @see gears.surface + +--- ontop_button_normal_inactive. +-- @beautiful beautiful.titlebar_ontop_button_normal_inactive +-- @param surface +-- @see gears.surface + +--- sticky_button_normal_inactive. +-- @beautiful beautiful.titlebar_sticky_button_normal_inactive +-- @param surface +-- @see gears.surface + +--- floating_button_focus_inactive. +-- @beautiful beautiful.titlebar_floating_button_focus_inactive +-- @param surface +-- @see gears.surface + +--- maximized_button_focus_inactive. +-- @beautiful beautiful.titlebar_maximized_button_focus_inactive +-- @param surface +-- @see gears.surface + +--- ontop_button_focus_inactive. +-- @beautiful beautiful.titlebar_ontop_button_focus_inactive +-- @param surface +-- @see gears.surface + +--- sticky_button_focus_inactive. +-- @beautiful beautiful.titlebar_sticky_button_focus_inactive +-- @param surface +-- @see gears.surface + --- Set a declarative widget hierarchy description. -- See [The declarative layout system](../documentation/03-declarative-layout.md.html) -- @param args An array containing the widgets disposition From 85334faffd7011d910ba7c2277f5ad7a01d40f10 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 4 Sep 2016 02:24:29 -0400 Subject: [PATCH 12/17] doc: Remove invalid tasklist documentation --- lib/awful/widget/tasklist.lua | 19 +------------------ 1 file changed, 1 insertion(+), 18 deletions(-) diff --git a/lib/awful/widget/tasklist.lua b/lib/awful/widget/tasklist.lua index 7d145c3df..ae749273b 100644 --- a/lib/awful/widget/tasklist.lua +++ b/lib/awful/widget/tasklist.lua @@ -171,24 +171,7 @@ end -- update. See `awful.widget.common.list_update`. -- @tparam[opt] table base_widget Container widget for tag widgets. Default -- is `wibox.layout.flex.horizontal`. --- @param base_widget.align The alignment ("left", "center" or "right"). --- @param base_widget.bg_normal The background color for unfocused client. --- @param base_widget.bg_normal The background color for unfocused client. --- @param base_widget.fg_normal The foreground color for unfocused client. --- @param base_widget.bg_focus The background color for focused client. --- @param base_widget.fg_focus The foreground color for focused client. --- @param base_widget.bg_urgent The background color for urgent clients. --- @param base_widget.fg_urgent The foreground color for urgent clients. --- @param base_widget.bg_minimize The background color for minimized clients. --- @param base_widget.fg_minimize The foreground color for minimized clients. --- @param base_widget.floating Symbol to use for floating clients. --- @param base_widget.ontop Symbol to use for ontop clients. --- @param base_widget.above Symbol to use for clients kept above others. --- @param base_widget.below Symbol to use for clients kept below others. --- @param base_widget.maximized Symbol to use for clients that have been maximized (vertically and horizontally). --- @param base_widget.maximized_horizontal Symbol to use for clients that have been horizontally maximized. --- @param base_widget.maximized_vertical Symbol to use for clients that have been vertically maximized. --- @param base_widget.font The font. +-- @function awful.tasklist function tasklist.new(screen, filter, buttons, style, update_function, base_widget) screen = get_screen(screen) local uf = update_function or common.list_update From 280973c9cb78cdeee66c760480dd48ed9bfdd36c Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 14 Aug 2016 01:34:43 -0400 Subject: [PATCH 13/17] doc: Document all client layout theme properties. --- lib/awful/layout/suit/corner.lua | 20 ++++++++++++++++++++ lib/awful/layout/suit/fair.lua | 10 ++++++++++ lib/awful/layout/suit/floating.lua | 5 +++++ lib/awful/layout/suit/magnifier.lua | 5 +++++ lib/awful/layout/suit/max.lua | 10 ++++++++++ lib/awful/layout/suit/spiral.lua | 10 ++++++++++ lib/awful/layout/suit/tile.lua | 20 ++++++++++++++++++++ 7 files changed, 80 insertions(+) diff --git a/lib/awful/layout/suit/corner.lua b/lib/awful/layout/suit/corner.lua index 2327186ae..ea1a86036 100644 --- a/lib/awful/layout/suit/corner.lua +++ b/lib/awful/layout/suit/corner.lua @@ -14,6 +14,26 @@ local math = math local capi = {screen = screen} local tag = require("awful.tag") +--- The cornernw layout layoutbox icon. +-- @beautiful beautiful.layout_cornernw +-- @param surface +-- @see gears.surface + +--- The cornerne layout layoutbox icon. +-- @beautiful beautiful.layout_cornerne +-- @param surface +-- @see gears.surface + +--- The cornersw layout layoutbox icon. +-- @beautiful beautiful.layout_cornersw +-- @param surface +-- @see gears.surface + +--- The cornerse layout layoutbox icon. +-- @beautiful beautiful.layout_cornerse +-- @param surface +-- @see gears.surface + --- Actually arrange clients of p.clients for corner layout -- @param p Mandatory table containing required informations for layouts -- (clients to arrange, workarea geometry, etc.) diff --git a/lib/awful/layout/suit/fair.lua b/lib/awful/layout/suit/fair.lua index 3291530c3..e3f9b0e42 100644 --- a/lib/awful/layout/suit/fair.lua +++ b/lib/awful/layout/suit/fair.lua @@ -11,6 +11,16 @@ local ipairs = ipairs local math = math +--- The fairh layout layoutbox icon. +-- @beautiful beautiful.layout_fairh +-- @param surface +-- @see gears.surface + +--- The fairv layout layoutbox icon. +-- @beautiful beautiful.layout_fairv +-- @param surface +-- @see gears.surface + local fair = {} local function do_fair(p, orientation) diff --git a/lib/awful/layout/suit/floating.lua b/lib/awful/layout/suit/floating.lua index 7f18f5280..3ba649ae6 100644 --- a/lib/awful/layout/suit/floating.lua +++ b/lib/awful/layout/suit/floating.lua @@ -15,6 +15,11 @@ local capi = mousegrabber = mousegrabber } +--- The floating layout layoutbox icon. +-- @beautiful beautiful.layout_floating +-- @param surface +-- @see gears.surface + local floating = {} --- Jump mouse cursor to the client's corner when resizing it. diff --git a/lib/awful/layout/suit/magnifier.lua b/lib/awful/layout/suit/magnifier.lua index 02226658b..a7edf35d2 100644 --- a/lib/awful/layout/suit/magnifier.lua +++ b/lib/awful/layout/suit/magnifier.lua @@ -18,6 +18,11 @@ local capi = mousegrabber = mousegrabber } +--- The magnifier layout layoutbox icon. +-- @beautiful beautiful.layout_magnifier +-- @param surface +-- @see gears.surface + local magnifier = {} function magnifier.mouse_resize_handler(c, corner, x, y) diff --git a/lib/awful/layout/suit/max.lua b/lib/awful/layout/suit/max.lua index 73603ab5d..6b662351e 100644 --- a/lib/awful/layout/suit/max.lua +++ b/lib/awful/layout/suit/max.lua @@ -12,6 +12,16 @@ local pairs = pairs local max = {} +--- The max layout layoutbox icon. +-- @beautiful beautiful.layout_max +-- @param surface +-- @see gears.surface + +--- The fullscreen layout layoutbox icon. +-- @beautiful beautiful.layout_fullscreen +-- @param surface +-- @see gears.surface + local function fmax(p, fs) -- Fullscreen? local area diff --git a/lib/awful/layout/suit/spiral.lua b/lib/awful/layout/suit/spiral.lua index c04a145ac..3e142952a 100644 --- a/lib/awful/layout/suit/spiral.lua +++ b/lib/awful/layout/suit/spiral.lua @@ -13,6 +13,16 @@ local ipairs = ipairs local math = math +--- The spiral layout layoutbox icon. +-- @beautiful beautiful.layout_spiral +-- @param surface +-- @see gears.surface + +--- The dwindle layout layoutbox icon. +-- @beautiful beautiful.layout_dwindle +-- @param surface +-- @see gears.surface + local spiral = {} local function do_spiral(p, _spiral) diff --git a/lib/awful/layout/suit/tile.lua b/lib/awful/layout/suit/tile.lua index 3215b033f..fb62f6d1b 100644 --- a/lib/awful/layout/suit/tile.lua +++ b/lib/awful/layout/suit/tile.lua @@ -23,6 +23,26 @@ local capi = local tile = {} +--- The tile layout layoutbox icon. +-- @beautiful beautiful.layout_tile +-- @param surface +-- @see gears.surface + +--- The tile top layout layoutbox icon. +-- @beautiful beautiful.layout_tiletop +-- @param surface +-- @see gears.surface + +--- The tile bottom layout layoutbox icon. +-- @beautiful beautiful.layout_tilebottom +-- @param surface +-- @see gears.surface + +--- The tile left layout layoutbox icon. +-- @beautiful beautiful.layout_tileleft +-- @param surface +-- @see gears.surface + --- Jump mouse cursor to the client's corner when resizing it. tile.resize_jump_to_corner = true From 6990cc15dcc56b838c59e69323eb6fc7369a84b0 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2016 02:57:32 -0400 Subject: [PATCH 14/17] tests: Add an helper "before and after" method for the layouts This will avoid a lot of copy paste as the remove/set/swap/insert/add/remove_widgets/swap_widgets code is identical beside the method name. --- tests/examples/wibox/layout/template.lua | 62 ++++++++++++++++++++++-- 1 file changed, 59 insertions(+), 3 deletions(-) diff --git a/tests/examples/wibox/layout/template.lua b/tests/examples/wibox/layout/template.lua index 88462ad55..bc162e77d 100644 --- a/tests/examples/wibox/layout/template.lua +++ b/tests/examples/wibox/layout/template.lua @@ -5,14 +5,15 @@ local wibox = require( "wibox" ) local surface = require( "gears.surface" ) local color = require( "gears.color" ) local beautiful = require( "beautiful" ) +local unpack = unpack or table.unpack -- luacheck: globals unpack (compatibility with Lua 5.1) -- Create a generic rectangle widget to show layout disposition -local function generic_widget(text) +local function generic_widget(text, col) return { { { draw = function(_, _, cr, width, height) - cr:set_source(color(beautiful.bg_normal)) + cr:set_source(color(col or beautiful.bg_normal)) cr:set_line_width(3) cr:rectangle(0, 0, width, height) cr:fill_preserve() @@ -34,8 +35,63 @@ local function generic_widget(text) } end +local names = { + "first" , + "second" , + "third" , + "fourth" , + "fifth" , + "sixth" , + "seventh", + "eighth" , + "ninth" , +} + +-- Generic template to create "before and after" for layout mutators +local function generic_before_after(layout, layout_args, count, method, method_args) + local ls = {} + + -- Create the layouts + for i=1, 2 do + local args = {layout = layout} + + -- In case the layout change the array (it is technically not forbidden) + for k,v in pairs(layout_args) do + args[k] = v + end + + local l = wibox.layout(args) + for j=1, count or 3 do + l:add(wibox.widget(generic_widget(names[j] or "N/A"))) + end + + ls[i] = l + end + + -- Mutate + if type(method) == "function" then + method(ls[2], unpack(method_args or {})) + else + ls[2][method](ls[2], unpack(method_args or {})) + end + + return wibox.layout { + { + markup = "Before:", + widget = wibox.widget.textbox, + }, + ls[1], + { + markup = "After:", + widget = wibox.widget.textbox, + }, + ls[2], + layout = wibox.layout.fixed.vertical + } +end + -- Let the test request a size and file format -local widget, w, h = loadfile(file_path)(generic_widget) +local widget, w, h = loadfile(file_path)(generic_widget, generic_before_after) -- Emulate the event loop for 10 iterations for _ = 1, 10 do From 979d2289fc616766ab5ac12c57b4e72ab8e937d9 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 21 Aug 2016 04:18:54 -0400 Subject: [PATCH 15/17] doc: Port the Awesome (global API) to the ldoc --- luaa.c | 52 +++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 41 insertions(+), 11 deletions(-) diff --git a/luaa.c b/luaa.c index ac0d3bb15..de39f52b0 100644 --- a/luaa.c +++ b/luaa.c @@ -296,18 +296,48 @@ luaA_fixups(lua_State *L) lua_setglobal(L, "selection"); } -/** awesome global table. - * @field version The version of awesome. - * @field release The release name of awesome. - * @field conffile The configuration file which has been loaded. - * @field startup True if we are still in startup, false otherwise. - * @field startup_errors Error message for errors that occured during - * startup. - * @field composite_manager_running True if a composite manager is running. - * @field unix_signal Table mapping between signal numbers and signal identifiers. - * @field hostname The hostname of the computer on which we are running. - * @table awesome + +/** + * The version of awesome. + * @tfield string version */ + +/** + * The release name of awesome. + * @tfield string release + */ + +/** + * The configuration file which has been loaded. + * @tfield string conffile + */ + +/** + * True if we are still in startup, false otherwise. + * @tfield boolean startup + */ + +/** + * Error message for errors that occured during + * startup. + * @tfield string startup_errors + */ + +/** + * True if a composite manager is running. + * @tfield boolean composite_manager_running + */ + +/** + * Table mapping between signal numbers and signal identifiers. + * @tfield table unix_signal + */ + +/** + * The hostname of the computer on which we are running. + * @tfield string hostname + */ + static int luaA_awesome_index(lua_State *L) { From 3d1edf317c114798d516ab59b2e93fcb9293f8fc Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Fri, 9 Sep 2016 02:03:07 -0400 Subject: [PATCH 16/17] doc: Document cursors --- docs/common/cursor_c.ldoc | 80 +++++++++++++++++++++++++++++++++++++++ mousegrabber.c | 5 +++ root.c | 6 ++- 3 files changed, 90 insertions(+), 1 deletion(-) create mode 100644 docs/common/cursor_c.ldoc diff --git a/docs/common/cursor_c.ldoc b/docs/common/cursor_c.ldoc new file mode 100644 index 000000000..6b595973d --- /dev/null +++ b/docs/common/cursor_c.ldoc @@ -0,0 +1,80 @@ + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
num_glyphs
cursor
arrow
based_arrow_down
based_arrow_up
boat
bogosity
bottom_left_corner
bottom_right_corner
bottom_side
bottom_tee
box_spiral
center_ptr
circle
clock
coffee_mug
cross
cross_reverse
crosshair
diamond_cross
dot
dotbox
double_arrow
draft_large
draft_small
draped_box
exchange
fleur
gobbler
gumby
hand
hand
heart
icon
iron_cross
left_ptr
left_side
left_tee
leftbutton
ll_angle
lr_angle
man
middlebutton
mouse
pencil
pirate
plus
question_arrow
right_ptr
right_side
right_tee
rightbutton
rtl_logo
sailboat
sb_down_arrow
sb_h_double_arrow
sb_left_arrow
sb_right_arrow
sb_up_arrow
sb_v_double_arrow
shuttle
sizing
spider
spraycan
star
target
tcross
top_left_arrow
top_left_corner
top_right_corner
top_side
top_tee
trek
ul_angle
umbrella
ur_angle
watch
xterm
diff --git a/mousegrabber.c b/mousegrabber.c index 2ad65a1cc..b35d17546 100644 --- a/mousegrabber.c +++ b/mousegrabber.c @@ -83,6 +83,11 @@ mousegrabber_handleevent(lua_State *L, int x, int y, uint16_t mask) * The function is called with one argument: * a table containing modifiers pointer coordinates. * + * The list of valid cusrors are: + * + *@DOC_cursor_c_COMMON@ + * + * * @param func A callback function as described above. * @param cursor The name of a X cursor to use while grabbing. * @function run diff --git a/root.c b/root.c index 99ebdb1ca..3564570d0 100644 --- a/root.c +++ b/root.c @@ -361,7 +361,11 @@ luaA_root_buttons(lua_State *L) return 1; } -/** Set the root cursor. +/** Set the root cursor + * + * The possible values are: + * + *@DOC_cursor_c_COMMON@ * * @param cursor_name A X cursor name. * @function cursor From 260aeba78bcdfae15fa51deb449d1392cc5ee1de Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 11 Sep 2016 01:48:45 -0400 Subject: [PATCH 17/17] doc: Fix the menubar fields documentation --- lib/menubar/init.lua | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/lib/menubar/init.lua b/lib/menubar/init.lua index c85b982e4..36f7918f3 100644 --- a/lib/menubar/init.lua +++ b/lib/menubar/init.lua @@ -46,34 +46,47 @@ local compute_text_width = menubar.utils.compute_text_width --- When true the .desktop files will be reparsed only when the -- extension is initialized. Use this if menubar takes much time to -- open. +-- @tfield[opt=true] boolean cache_entries menubar.cache_entries = true --- When true the categories will be shown alongside application -- entries. +-- @tfield[opt=true] boolean show_categories menubar.show_categories = true --- Specifies the geometry of the menubar. This is a table with the keys -- x, y, width and height. Missing values are replaced via the screen's -- geometry. However, missing height is replaced by the font size. +-- @table geometry +-- @tfield number geometry.x A forced horizontal position +-- @tfield number geometry.y A forced vertical position +-- @tfield number geometry.width A forced width +-- @tfield number geometry.height A forced height menubar.geometry = { width = nil, height = nil, x = nil, y = nil } + --- Width of blank space left in the right side. +-- @tfield number right_margin menubar.right_margin = theme.xresources.apply_dpi(8) --- Label used for "Next page", default "▶▶". +-- @tfield[opt="▶▶"] string right_label menubar.right_label = "▶▶" --- Label used for "Previous page", default "◀◀". +-- @tfield[opt="◀◀"] string left_label menubar.left_label = "◀◀" -- awful.widget.common.list_update adds three times a margin of dpi(4) -- for each item: +-- @tfield number list_interspace local list_interspace = theme.xresources.apply_dpi(4) * 3 --- Allows user to specify custom parameters for prompt.run function -- (like colors). +-- @see awful.prompt menubar.prompt_args = {} -- Private section