From ac0aeb65c04a816d752c53eb4b51d0d65db831c5 Mon Sep 17 00:00:00 2001 From: Emmanuel Lepage Vallee Date: Sun, 23 Aug 2020 01:46:05 -0700 Subject: [PATCH] doc: Modernize the landing page. The previous index.html was scary and the most useful links were at the bottom. This commit fixes that. It also adds an image of the default config with some labels to name all visible components. --- docs/03-declarative-layout.md | 8 +- docs/05-awesomerc.md.lua | 5 + docs/config.ld | 45 +++++- docs/ldoc.css | 21 +++ tests/examples/awful/popup/defaultconfig.lua | 137 +++++++++++++++++++ tests/examples/shims/_default_look.lua | 17 ++- 6 files changed, 230 insertions(+), 3 deletions(-) create mode 100644 tests/examples/awful/popup/defaultconfig.lua diff --git a/docs/03-declarative-layout.md b/docs/03-declarative-layout.md index b989340dd..b6b57d0d3 100644 --- a/docs/03-declarative-layout.md +++ b/docs/03-declarative-layout.md @@ -1,7 +1,13 @@ -# The AwesomeWM widget system +# The Widget system This document explains how to define, place and manage widgets. +## The default configuration + +This is what the widgets present in the default configuration are named: + +@DOC_awful_popup_defaultconfig_EXAMPLE@ + ## The default widgets ### Widgets diff --git a/docs/05-awesomerc.md.lua b/docs/05-awesomerc.md.lua index dee0ab161..0fc005d0d 100644 --- a/docs/05-awesomerc.md.lua +++ b/docs/05-awesomerc.md.lua @@ -18,10 +18,15 @@ The Awesome API is distributed across many libraries (also called modules). Here are the modules that we import: + + + + +
LibraryDescription
`gears`Utilities such as color parsing and objects
`wibox`Awesome own generic widget framework
`awful`Everything related to window managment
`naughty`Notifications
`ruled`Define declarative rules on various events
`menubar`XDG (application) menu implementation
`beautiful`Awesome theme module
diff --git a/docs/config.ld b/docs/config.ld index 2225cd3af..f03346100 100644 --- a/docs/config.ld +++ b/docs/config.ld @@ -20,7 +20,7 @@ merge=true use_markdown_titles=true wrap=true full_description = [[ -Welcome to the documentation for the awesome window manager. Below you find an +Welcome to the documentation for the Awesome window manager. Below you find an overview of the individual parts which links to the full documentation. If you are a new user, you may want to read @{07-my-first-awesome.md} to get @@ -28,6 +28,49 @@ started. In @{05-awesomerc.md}, the default configuration is explained. If you already used awesome in the past, @{89-NEWS.md} and @{17-porting-tips.md} should be useful for you. + +### Default configuration components name: + +
+ +### Guides + +
+
+ Getting started + FAQ + Read me + NEWS +
+
+ The widget system + Startup options + The default rc.lua + Window management +
+
+ +## Major libraries + +AwesomeWM ship multiple libraries. Here is an overview of the purpose and scope +of those libraries. + + + + + + + + + + + + + + + +
LibraryDescription
`gears`Utilities such as color parsing and objects
`wibox`Awesome own generic widget framework
`awful`Everything related to window managment
`awful.widget`Window management related widgets
`awful.layout`The default stateless client tiling module.
`ruled`Define declarative rules on various events
`naughty`Notifications
`menubar`XDG (application) menu implementation
`beautiful`Awesome theme module
+ ]] topics={ '00-authors.md', diff --git a/docs/ldoc.css b/docs/ldoc.css index f87d1fc0c..1cb5b83bd 100644 --- a/docs/ldoc.css +++ b/docs/ldoc.css @@ -482,3 +482,24 @@ pre .url { color: #272fc2; text-decoration: underline; } color: rgb(128, 128, 128); border-radius: 7px; } + +.index_guides div { + margin: 0 auto; + display: table; + margin-bottom: 10px; +} + +.index_guides div a { + display: inline-block; + border: solid 1px #cccccc; + width: 200px; + margin-left: 10px; + margin-right: 10px; + text-align: center; + padding-top: 20px; + padding-bottom: 20px; +} + +.index_guides div a:hover { + background-color: #99b3ec; +} diff --git a/tests/examples/awful/popup/defaultconfig.lua b/tests/examples/awful/popup/defaultconfig.lua new file mode 100644 index 000000000..be28439ad --- /dev/null +++ b/tests/examples/awful/popup/defaultconfig.lua @@ -0,0 +1,137 @@ +--DOC_GEN_IMAGE +--DOC_HIDE_ALL +--DOC_NO_USAGE +--DOC_NO_DASH +require("_date") +local awful = require("awful") +local gears = require("gears") +local naughty = require("naughty") +local wibox = require("wibox") +local beautiful = require("beautiful") --DOC_HIDE +local look = require("_default_look") + +screen[1]._resize {width = 640, height = 340} + +-- This example is used to show the various type of wibox awesome provides +-- and mimic the default config look + +look.mypromptbox.text = "Run:" + +local c = client.gen_fake {hide_first=true} + +c:geometry { + x = 205, + y = 260, + height = 60, + width = 230, +} +c._old_geo = {c:geometry()} +c:set_label("A client (window)") + +require("gears.timer").run_delayed_calls_now() +-- The titlebar + +c:emit_signal("request::titlebars", "rules", {})--DOC_HIDE + +local overlay_w = wibox { + bg = "#00000000", + visible = true, + ontop = true, +} + +awful.placement.maximize(overlay_w) + +local canvas = wibox.layout.manual() +canvas.forced_height = 480 +canvas.forced_width = 640 +overlay_w:set_widget(canvas) + +local function create_info(text, x, y, width, height) + canvas:add_at(wibox.widget { + { + { + text = text, + align = "center", + ellipsize = "none", + wrap = "word", + widget = wibox.widget.textbox + }, + margins = 10, + widget = wibox.container.margin + }, + forced_width = width, + forced_height = height, + shape = gears.shape.rectangle, + border_width = 1, + border_color = beautiful.border_color, + bg = "#ffff0055", + widget = wibox.container.background + }, {x = x, y = y}) +end + +local function create_line(x1, y1, x2, y2) + return canvas:add_at(wibox.widget { + fit = function() + return x2-x1+6, y2-y1+6 + end, + draw = function(_, _, cr) + cr:set_source_rgb(0,0,0) + cr:set_line_width(1) + cr:arc(1.5, 1.5, 1.5, 0, math.pi*2) + cr:arc(x2-x1+1.5, y2-y1+1.5, 1.5, 0, math.pi*2) + cr:fill() + cr:move_to(1.5,1.5) + cr:line_to(x2-x1+1.5, y2-y1+1.5) + cr:stroke() + end, + layout = wibox.widget.base.make_widget, + }, {x=x1, y=y1}) +end + +naughty.connect_signal("request::display", function(n) + naughty.layout.box {notification = n} +end) + +naughty.notification { + title = "A notification", + message = "With a message! ....", + position = "top_right", +} + +create_info("awful.widget.launcher", 0, 70, 135, 30) +create_info("awful.widget.prompt", 145, 80, 127, 30) +create_info("awful.widget.taglist", 20, 30, 120, 30) +create_info("awful.widget.tasklist", 240, 50, 130, 30) +create_info("wibox.widget.systray", 380, 50, 130, 30) +create_info("awful.widget.keyboardlayout", 315, 15, 170, 30) +create_info("wibox.widget.textclock", 480, 130, 140, 30) +create_info("awful.widget.layoutbox", 490, 170, 150, 30) +create_info("naughty.layout.box", 450, 90, 130, 30) + +create_info("awful.titlebar.widget.iconwidget", 10, 260, 190, 30) +create_info("awful.titlebar.widget.titlewidget", 90, 225, 190, 30) +create_info("awful.titlebar.widget.floatingbutton", 150, 190, 205, 30) +create_info("awful.titlebar.widget.maximizedbutton", 150, 155, 220, 30) +create_info("awful.titlebar.widget.stickybutton", 200, 125, 195, 30) +create_info("awful.titlebar.widget.ontopbutton", 390, 210, 200, 30) +create_info("awful.titlebar.widget.closebutton", 445, 260, 190, 30) + +create_line(5, 10, 5, 70) --launcher +create_line(75, 10, 75, 30) --taglist +create_line(150, 10, 150, 80) -- prompt +create_line(550, 65, 550, 90) -- notification +create_line(305, 10, 305, 50) -- tasklist +create_line(480, 10, 480, 15) -- keyboard +create_line(600, 5, 600, 130) --textclock +create_line(630, 5, 630, 170) -- layoutbox +create_line(500, 5, 500, 50) -- systray + +create_line(385, 150, 385, 259) -- sticky +create_line(365, 180, 365, 259) -- maximize +create_line(345, 215, 345, 259) -- floating +create_line(405, 235, 405, 259) -- ontop +create_line(195, 270, 203, 270) -- icon +create_line(437, 270, 445, 270) -- close +create_line(245, 250, 245, 259) -- title + +--DOC_HIDE vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80 diff --git a/tests/examples/shims/_default_look.lua b/tests/examples/shims/_default_look.lua index 87e7a5085..c67927f74 100644 --- a/tests/examples/shims/_default_look.lua +++ b/tests/examples/shims/_default_look.lua @@ -10,6 +10,7 @@ local mytextclock = wibox.widget.textclock() local mylayoutbox = awful.widget.layoutbox(screen[1]) local mytaglist = awful.widget.taglist(screen[1], awful.widget.taglist.filter.all, {}) local mytasklist = awful.widget.tasklist(screen[1], awful.widget.tasklist.filter.currenttags, {}) +local mypromptbox = wibox.widget.textbox("") local wb = awful.wibar { position = "top" } wb:setup { @@ -21,11 +22,24 @@ wb:setup { widget = wibox.widget.imagebox, }, mytaglist, + mypromptbox, }, mytasklist, { layout = wibox.layout.fixed.horizontal, mykeyboardlayout, + { + image = beautiful.awesome_icon, + widget = wibox.widget.imagebox, + }, + { + image = beautiful.awesome_icon, + widget = wibox.widget.imagebox, + }, + { + image = beautiful.awesome_icon, + widget = wibox.widget.imagebox, + }, mytextclock, mylayoutbox, }, @@ -70,5 +84,6 @@ return { mylayoutbox = mylayoutbox , mytaglist = mytaglist , mytasklist = mytasklist , - mywibox = wb, + mywibox = wb , + mypromptbox = mypromptbox , }