Module awful.rules
Rules for clients.
This module applies rules to clients during startup (via client.manage, but its functions can be used for client matching in general.
All existing client properties can be used in rules. It is also possible
to add random properties that will be later accessible as c.property_name
(where c
is a valid client object)
In addition to the existing properties, the following are supported:
- placement
- honor_padding
- honor_workarea
- tag
- new_tag
- switchtotag
- focus
- titlebars_enabled
- callback
Info:
- Copyright: 2009 Julien Danjou
- Author: Julien Danjou <[email protected]>
Functions
match (c, rule) | Check if a client matches a rule. |
match_any (c, rule) | Check if a client matches any part of a rule. |
matches (c, entry) | Does a given rule entry match a client? |
matching_rules (c, _rules) | Get list of matching rules for a client. |
matches_list (c, _rules) | Check if a client matches a given set of rules. |
add_rule_source (name, callback, depends_on, precede) | Add a new rule source. |
remove_rule_source (name) | Remove a source. |
apply (c) | Apply awful.rules.rules to a client. |
rules.high_priority_properties.new_tag (c, value, props) | Create a new tag based on a rule. |
execute (c, props[, callbacks]) | Apply properties and callbacks to a client. |
Rule sources
awful.rules | The default awful.rules source. |
awful.spawn | The rule source for clients spawned by awful.spawn. |
Tables
rules | This is the global rules table. |
extra_properties | Extra rules properties. |
high_priority_properties | Extra high priority properties. |
delayed_properties | Delayed properties. |
Functions
Methods- match (c, rule)
-
Check if a client matches a rule.
- c client.object The client.
- rule table The rule to check.
Returns:
-
bool
True if it matches, false otherwise.
- match_any (c, rule)
-
Check if a client matches any part of a rule.
- c client.object The client.
- rule table The rule to check.
Returns:
-
bool
True if at least one rule is matched, false otherwise.
- matches (c, entry)
-
Does a given rule entry match a client?
- c client.object The client.
- entry
table
Rule entry (with keys
rule
,rule_any
,except
and/orexcept_any
).
Returns:
-
bool
- matching_rules (c, _rules)
-
Get list of matching rules for a client.
- c client.object The client.
- _rules table The rules to check. List with “rule”, “rule_any”, “except” and “except_any” keys.
Returns:
-
table
The list of matched rules.
- matches_list (c, _rules)
-
Check if a client matches a given set of rules.
- c client.object The client.
- _rules
table
The rules to check. List of tables with
rule
,rule_any
,except
andexcept_any
keys.
Returns:
-
bool
True if at least one rule is matched, false otherwise.
- add_rule_source (name, callback, depends_on, precede)
-
Add a new rule source.
A rule source is a provider called when a client is managed (started). It allows to configure the client by providing properties that should be applied. By default, Awesome provides 2 sources:
- awful.rules: A declarative matcher
- awful.spawn: Launch clients with pre-defined properties
It is possible to register new callbacks to modify the properties table before it is applied. Each provider is executed sequentially and modifies the same table. If the first provider set a property, then the second can override it, then the third, etc. Once the providers are exhausted, the properties are applied on the client.
It is important to note that properties themselves have their own dependencies. For example, a tag property implies a screen. Therefor, if a screen is already specified, then it will be ignored when the rule is executed. Properties also have their own priorities. For example, the titlebar and
border_width
need to be applied before thex
andy
positions are set. Otherwise, it will be off or the client will shift upward everytime Awesome is restarted. A rule source cannot change this. It is up to the callback to be aware of the dependencies and avoid to introduce issues. For example, if the source wants to set a screen, it has to check if the tag,tags
or new_tag are on that screen or remove those properties. Otherwise, they will be ignored once the rule is applied.- name string The provider name. It must be unique.
- callback The callback that is called to produce properties.
- depends_on table A list of names of sources this source depends on (sources that must be executed before
name
. (default {})- precede table A list of names of sources this source have a priority over. (default {})
Returns:
-
boolean
Returns false if a dependency conflict was found.
- remove_rule_source (name)
-
Remove a source.
- name string The source name.
Returns:
-
boolean
If the source was removed
- apply (c)
-
Apply awful.rules.rules to a client.
- c client.object The client.
- rules.high_priority_properties.new_tag (c, value, props)
-
Create a new tag based on a rule.
Returns:
-
tag
The new tag
- execute (c, props[, callbacks])
-
Apply properties and callbacks to a client.
- c client.object The client.
- props table Properties to apply.
- callbacks table Callbacks to apply. (optional)
Rule sources
- awful.rules
-
The default awful.rules source.
Has priority over:
nothing
- awful.spawn
-
The rule source for clients spawned by awful.spawn.
Has priority over:
Tables
- rules
-
This is the global rules table.
You should fill this table with your rule and properties to apply. For example, if you want to set xterm maximized at startup, you can add:
{ rule = { class = "xterm" }, properties = { maximized_vertical = true, maximized_horizontal = true } }
If you want to set mplayer floating at startup, you can add:
{ rule = { name = "MPlayer" }, properties = { floating = true } }
If you want to put Firefox on a specific tag at startup, you can add:
{ rule = { instance = "firefox" }, properties = { tag = mytagobject } }
Alternatively, you can specify the tag by name:
{ rule = { instance = "firefox" }, properties = { tag = "3" } }
If you want to put Thunderbird on a specific screen at startup, use:
{ rule = { instance = "Thunderbird" }, properties = { screen = 1 } }
Assuming that your X11 server supports the RandR extension, you can also specify the screen by name:
{ rule = { instance = "Thunderbird" }, properties = { screen = "VGA1" } }
If you want to put Emacs on a specific tag at startup, and immediately switch to that tag you can add:
{ rule = { class = "Emacs" }, properties = { tag = mytagobject, switchtotag = true } }
If you want to apply a custom callback to execute when a rule matched, for example to pause playing music from mpd when you start dosbox, you can add:
{ rule = { class = "dosbox" }, callback = function(c) awful.spawn('mpc pause') end }
Note that all “rule” entries need to match. If any of the entry does not match, the rule won’t be applied.
If a client matches multiple rules, they are applied in the order they are 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.
If the value of a property is a function, that function gets called and function’s return value is used for the property.
To match multiple clients to a rule one need to use slightly different syntax:
{ rule_any = { class = { "MPlayer", "Nitrogen" }, instance = { "xterm" } }, properties = { floating = true } }
To match multiple clients with an exception one can couple
rules.except
orrules.except_any
with the rules:{ rule = { class = "Firefox" }, except = { instance = "Navigator" }, properties = {floating = true}, }, { rule_any = { class = { "Pidgin", "Xchat" } }, except_any = { role = { "conversation" } }, properties = { tag = "1" } } { rule = {}, except_any = { class = { "Firefox", "Vim" } }, properties = { floating = true } }
- extra_properties
-
Extra rules properties.
These properties are used in the rules only and are not sent to the client afterward.
To add a new properties, just do:
function awful.rules.extra_properties.my_new_property(c, value, props) -- do something end
By default, the table has the following functions:
- geometry
- placement
- high_priority_properties
-
Extra high priority properties.
Some properties, such as anything related to tags, geometry or focus, will cause a race condition if set in the main property section. This is why they have a section for them.
To add a new properties, just do:
function awful.rules.high_priority_properties.my_new_property(c, value, props) -- do something end
By default, the table has the following functions:
- tag
- new_tag
- delayed_properties
- Delayed properties. Properties applied after all other categories.