Docs: Port awful.rules into the new doc format.
This converts the old documentation style into the new one to use markdown instead of HTML in bigger doc blocks. Also, we can use block comments, which means that writting documentation (and indenting code blocks) easier. Signed-off-by: Ignas Anikevicius (gns_ank) <anikevicius@gmail.com>
This commit is contained in:
parent
400ba86ead
commit
12185a5aae
|
@ -1,4 +1,6 @@
|
||||||
---------------------------------------------------------------------------
|
---------------------------------------------------------------------------
|
||||||
|
-- Apply rules to clients at startup.
|
||||||
|
--
|
||||||
-- @author Julien Danjou <julien@danjou.info>
|
-- @author Julien Danjou <julien@danjou.info>
|
||||||
-- @copyright 2009 Julien Danjou
|
-- @copyright 2009 Julien Danjou
|
||||||
-- @release @AWESOME_VERSION@
|
-- @release @AWESOME_VERSION@
|
||||||
|
@ -13,102 +15,82 @@ local pairs = pairs
|
||||||
local aclient = require("awful.client")
|
local aclient = require("awful.client")
|
||||||
local atag = require("awful.tag")
|
local atag = require("awful.tag")
|
||||||
|
|
||||||
--- Apply rules to clients at startup.
|
|
||||||
-- awful.rules
|
|
||||||
local rules = {}
|
local rules = {}
|
||||||
|
|
||||||
--- This is the global rules table.
|
--[[--
|
||||||
-- <p>You should fill this table with your rule and properties to apply.
|
This is the global rules table.
|
||||||
-- For example, if you want to set xterm maximized at startup, you can add:
|
|
||||||
-- <br/>
|
You should fill this table with your rule and properties to apply.
|
||||||
-- <code>
|
For example, if you want to set xterm maximized at startup, you can add:
|
||||||
-- { rule = { class = "xterm" },
|
|
||||||
-- properties = { maximized_vertical = true, maximized_horizontal = true } }
|
{ rule = { class = "xterm" },
|
||||||
-- </code>
|
properties = { maximized_vertical = true, maximized_horizontal = true } }
|
||||||
-- </p>
|
|
||||||
-- <p>If you want to set mplayer floating at startup, you can add:
|
If you want to set mplayer floating at startup, you can add:
|
||||||
-- <br/>
|
|
||||||
-- <code>
|
{ rule = { name = "MPlayer" },
|
||||||
-- { rule = { name = "MPlayer" },
|
properties = { floating = true } }
|
||||||
-- properties = { floating = true } }
|
|
||||||
-- </code>
|
If you want to put Firefox on a specific tag at startup, you can add:
|
||||||
-- </p>
|
|
||||||
-- <p>If you want to put Firefox on a specific tag at startup, you
|
{ rule = { instance = "firefox" },
|
||||||
-- can add:
|
properties = { tag = mytagobject } }
|
||||||
-- <br/>
|
|
||||||
-- <code>
|
If you want to put Emacs on a specific tag at startup, and immediately switch
|
||||||
-- { rule = { instance = "firefox" },
|
to that tag you can add:
|
||||||
-- properties = { tag = mytagobject } }
|
|
||||||
-- </code>
|
{ rule = { class = "Emacs" },
|
||||||
-- </p>
|
properties = { tag = mytagobject, switchtotag = true } }
|
||||||
-- <p>If you want to put Emacs on a specific tag at startup, and
|
|
||||||
-- immediately switch to that tag you can add:
|
If you want to apply a custom callback to execute when a rule matched,
|
||||||
-- <br/>
|
for example to pause playing music from mpd when you start dosbox, you
|
||||||
-- <code>
|
can add:
|
||||||
-- { rule = { class = "Emacs" },
|
|
||||||
-- properties = { tag = mytagobject, switchtotag = true } }
|
{ rule = { class = "dosbox" },
|
||||||
-- </code>
|
callback = function(c)
|
||||||
-- </p>
|
awful.util.spawn('mpc pause')
|
||||||
-- <p>If you want to apply a custom callback to execute when a rule matched,
|
end }
|
||||||
-- for example to pause playing music from mpd when you start dosbox, you
|
|
||||||
-- can add:
|
Note that all "rule" entries need to match. If any of the entry does not
|
||||||
-- <br/>
|
match, the rule won't be applied.
|
||||||
-- <code>
|
|
||||||
-- { rule = { class = "dosbox" },
|
If a client matches multiple rules, their applied in the order they are
|
||||||
-- callback = function(c)
|
put in this global rules table. If the value of a rule is a string, then the
|
||||||
-- awful.util.spawn('mpc pause')
|
match function is used to determine if the client matches the rule.
|
||||||
-- end }
|
|
||||||
-- </code>
|
If the value of a property is a function, that function gets called and
|
||||||
-- </p>
|
function's return value is used for the property.
|
||||||
-- <p>Note that all "rule" entries need to match. If any of the entry does not
|
|
||||||
-- match, the rule won't be applied.</p>
|
To match multiple clients to a rule one need to use slightly different
|
||||||
-- <p>If a client matches multiple rules, their applied in the order they are
|
syntax:
|
||||||
-- put in this global rules table. If the value of a rule is a string, then the
|
|
||||||
-- match function is used to determine if the client matches the rule.</p>
|
{ rule_any = { class = { "MPlayer", "Nitrogen" }, instance = { "xterm" } },
|
||||||
-- <p>If the value of a property is a function, that function gets called and
|
properties = { floating = true } }
|
||||||
-- function's return value is used for the property.</p>
|
|
||||||
--
|
To match multiple clients with an exception one can couple `rules.except` or
|
||||||
-- <p> To match multiple clients to a rule one need to use slightly different
|
`rules.except_any` with the rules:
|
||||||
-- syntax:
|
|
||||||
-- <br/>
|
{ rule = { class = "Firefox" },
|
||||||
-- <code>
|
except = { instance = "Navigator" },
|
||||||
-- { rule_any = { class = { "MPlayer", "Nitrogen" }, instance = { "xterm" } },
|
properties = {floating = true},
|
||||||
-- properties = { floating = true } }
|
},
|
||||||
-- </code>
|
|
||||||
-- </p>
|
{ rule_any = { class = { "Pidgin", "Xchat" } },
|
||||||
--
|
except_any = { role = { "conversation" } },
|
||||||
-- <p> To match multiple clients with an exception one can couple 'except' or
|
properties = { tag = tags[1][1] }
|
||||||
-- 'except_any' with the rules:
|
}
|
||||||
-- <br/>
|
|
||||||
-- <code>
|
{ rule = {},
|
||||||
-- { rule = { class = "Firefox" },
|
except_any = { class = { "Firefox", "Vim" } },
|
||||||
-- except = { instance = "Navigator" },
|
properties = { floating = true }
|
||||||
-- properties = {floating = true},
|
}
|
||||||
-- },
|
]]--
|
||||||
-- </code>
|
|
||||||
-- <br/>
|
|
||||||
-- <code>
|
|
||||||
-- { rule_any = { class = { "Pidgin", "Xchat" } },
|
|
||||||
-- except_any = { role = { "conversation" } },
|
|
||||||
-- properties = { tag = tags[1][1] }
|
|
||||||
-- }
|
|
||||||
-- <br/>
|
|
||||||
-- <code>
|
|
||||||
-- { rule = {},
|
|
||||||
-- except_any = { class = { "Firefox", "Vim" } },
|
|
||||||
-- properties = { floating = true }
|
|
||||||
-- }
|
|
||||||
-- </code>
|
|
||||||
-- </p>
|
|
||||||
--
|
|
||||||
-- @class table
|
|
||||||
-- @name rules
|
|
||||||
rules.rules = {}
|
rules.rules = {}
|
||||||
|
|
||||||
--- Check if a client matches a rule.
|
--- Check if a client matches a rule.
|
||||||
-- @client c The client.
|
-- @client c The client.
|
||||||
-- @tab rule The rule to check.
|
-- @tab rule The rule to check.
|
||||||
-- @return True if it matches, false otherwise.
|
-- @treturn bool True if it matches, false otherwise.
|
||||||
function rules.match(c, rule)
|
function rules.match(c, rule)
|
||||||
if not rule then return false end
|
if not rule then return false end
|
||||||
for field, value in pairs(rule) do
|
for field, value in pairs(rule) do
|
||||||
|
@ -130,7 +112,7 @@ end
|
||||||
--- Check if a client matches any part of a rule.
|
--- Check if a client matches any part of a rule.
|
||||||
-- @client c The client.
|
-- @client c The client.
|
||||||
-- @tab rule The rule to check.
|
-- @tab rule The rule to check.
|
||||||
-- @return True if at least one rule is matched, false otherwise.
|
-- @treturn bool True if at least one rule is matched, false otherwise.
|
||||||
function rules.match_any(c, rule)
|
function rules.match_any(c, rule)
|
||||||
if not rule then return false end
|
if not rule then return false end
|
||||||
for field, values in pairs(rule) do
|
for field, values in pairs(rule) do
|
||||||
|
@ -166,8 +148,8 @@ end
|
||||||
--- Check if a client matches a given set of rules.
|
--- Check if a client matches a given set of rules.
|
||||||
-- @client c The client.
|
-- @client c The client.
|
||||||
-- @tab rules The rules to check. List with "rule", "rule_any", "except" and
|
-- @tab rules The rules to check. List with "rule", "rule_any", "except" and
|
||||||
-- "except_any" keys.
|
-- "except_any" keys.
|
||||||
-- @treturn boolean True if at least one rule is matched, false otherwise.
|
-- @treturn bool True if at least one rule is matched, false otherwise.
|
||||||
function rules.does_match(c, rules)
|
function rules.does_match(c, rules)
|
||||||
local result = rules.matching_rules(c, rules)
|
local result = rules.matching_rules(c, rules)
|
||||||
return #result == 0 and false or result
|
return #result == 0 and false or result
|
||||||
|
|
Loading…
Reference in New Issue