Module: ruled.client
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)
Syntax
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:
ruled.client.append_rule { rule = { class = "xterm" }, properties = { maximized_vertical = true, maximized_horizontal = true }, } -- Spawn xterm awful.spawn("xterm")
If you want to set mplayer floating at startup, you can add:
ruled.client.append_rule { rule = { class = "mplayer" }, properties = { floating = true, placement = awful.placement.centered, width = 640, height = 480, }, } -- Spawn xterm for _=1, 5 do awful.spawn("xterm") end -- Spawn mplayer awful.spawn("mplayer")
If you want to put Firefox on a specific tag at startup. It is possible to specify the tag with it's object or by name:
-- Select tag by object reference: ruled.client.append_rule { rule_any = { class = {"firefox"} }, properties = { tag = screen[1].tags[3], }, } -- Select tag by name: ruled.client.append_rule { rule_any = { class = {"thunderbird"} }, properties = { tag = "five", }, } -- Spawn firefox and thunderbird awful.spawn("firefox") awful.spawn("thunderbird")
If you want to put Thunderbird on a specific screen at startup, use:
mouse.coords {x = 2500, y = 100 } -- Screen by IDs: ruled.client.append_rule { rule_any = { class = {"firefox"} }, properties = { screen = 2, }, } -- Screen by object: ruled.client.append_rule { rule_any = { class = {"thunderbird"} }, properties = { screen = mouse.screen, }, } -- Screen by output name: ruled.client.append_rule { rule_any = { class = {"xterm"} }, properties = { screen = "LVDS1", }, } -- Spawn firefox, thunderbird and xterm awful.spawn("firefox") awful.spawn("thunderbird") awful.spawn("xterm")
If you want to put Emacs on a specific tag at startup, and immediately switch to that tag you can add:
-- Select tag by object reference: ruled.client.append_rule { rule = { class = "firefox" }, properties = { tag = screen[1].tags[4], switch_to_tags = true } } -- Spawn firefox awful.spawn("firefox")
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
or
rules.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 } }
Note that all rules can have an id field. This can then be used to find the rule. For example, it can be used in remove_rule instead of the table.
Flowchart
Applicable client properties
The table below holds the list of default client properties along with some extra properties that are specific to the rules. Note that any property can be set in the rules and interpreted by user provided code. This table only represent those offered by default.
Name | Description |
---|---|
placement | The client default placement on the screen |
honor\_padding | When applying the placement, honor the screen padding |
honor\_workarea | When applying the placement, honor the screen work area |
tag | The client default tag |
tags | The client default tags |
new\_tag | Create a new tag for this client |
switch\_to\_tags | Unselect the current tags and select this client tags |
focus | Define if the client should grab focus by default |
titlebars\_enabled | Should this client have a titlebar by default |
callback | A function to call when this client is ready |
placement | The client default placement on the screen |
honor\_padding | When applying the placement, honor the screen padding |
honor\_workarea | When applying the placement, honor the screen work area |
tag | The client default tag |
tags | The client default tags |
new\_tag | Create a new tag for this client |
switch\_to\_tags | Unselect the current tags and select this client tags |
focus | Define if the client should grab focus by default |
titlebars\_enabled | Should this client have a titlebar by default |
callback | A function to call when this client is ready |
marked | If a client is marked or not |
is\_fixed | Return if a client has a fixed size or not |
immobilized\_horizontal | Is the client immobilized horizontally? |
immobilized\_vertical | Is the client immobilized vertically? |
floating | The client floating state |
x | The x coordinates |
y | The y coordinates |
width | The width of the client |
height | The height of the client |
dockable | If the client is dockable |
requests\_no\_titlebar | If the client requests not to be decorated with a titlebar |
shape | Set the client shape |
active | Return true if the client is active (has focus) |
window | The X window id |
name | The client title |
skip\_taskbar | True if the client does not want to be in taskbar |
type | The window type |
class | The client class |
instance | The client instance |
pid | The client PID, if available |
role | The window role, if available |
machine | The machine the client is running on |
icon\_name | The client name when iconified |
icon | The client icon as a surface |
icon\_sizes | The available sizes of client icons |
screen | Client screen |
hidden | Define if the client must be hidden, i |
minimized | Define it the client must be iconify, i |
size\_hints\_honor | Honor size hints, e |
border\_width | The client border width |
border\_color | The client border color |
urgent | Set to true when the client ask for attention |
content | A cairo surface for the client window content |
opacity | The client opacity |
ontop | The client is on top of every other windows |
above | The client is above normal windows |
below | The client is below normal windows |
fullscreen | The client is fullscreen or not |
maximized | The client is maximized (horizontally and vertically) or not |
maximized\_horizontal | The client is maximized horizontally or not |
maximized\_vertical | The client is maximized vertically or not |
transient\_for | The client the window is transient for |
group\_window | Window identification unique to a group of windows |
leader\_window | Identification unique to windows spawned by the same command |
size\_hints | A table with size hints of the client |
motif\_wm\_hints | The motif WM hints of the client |
sticky | Set the client sticky, i |
modal | Indicate if the client is modal |
focusable | True if the client can receive the input focus |
shape\_bounding | The client's bounding shape as set by awesome as a (native) cairo surface |
shape\_clip | The client's clip shape as set by awesome as a (native) cairo surface |
shape\_input | The client's input shape as set by awesome as a (native) cairo surface |
client\_shape\_bounding | The client's bounding shape as set by the program as a (native) cairo surface |
client\_shape\_clip | The client's clip shape as set by the program as a (native) cairo surface |
startup\_id | The FreeDesktop StartId |
valid | If the client that this object refers to is still managed by awesome |
first\_tag | The first tag of the client |
buttons | Get or set mouse buttons bindings for a client |
keys | Get or set keys bindings for a client |
marked | If a client is marked or not |
is\_fixed | Return if a client has a fixed size or not |
immobilized\_horizontal | Is the client immobilized horizontally? |
immobilized\_vertical | Is the client immobilized vertically? |
floating | The client floating state |
x | The x coordinates |
y | The y coordinates |
width | The width of the client |
height | The height of the client |
dockable | If the client is dockable |
requests\_no\_titlebar | If the client requests not to be decorated with a titlebar |
shape | Set the client shape |
active | Return true if the client is active (has focus) |
window | The X window id |
name | The client title |
skip\_taskbar | True if the client does not want to be in taskbar |
type | The window type |
class | The client class |
instance | The client instance |
pid | The client PID, if available |
role | The window role, if available |
machine | The machine the client is running on |
icon\_name | The client name when iconified |
icon | The client icon as a surface |
icon\_sizes | The available sizes of client icons |
screen | Client screen |
hidden | Define if the client must be hidden, i |
minimized | Define it the client must be iconify, i |
size\_hints\_honor | Honor size hints, e |
border\_width | The client border width |
border\_color | The client border color |
urgent | Set to true when the client ask for attention |
content | A cairo surface for the client window content |
opacity | The client opacity |
ontop | The client is on top of every other windows |
above | The client is above normal windows |
below | The client is below normal windows |
fullscreen | The client is fullscreen or not |
maximized | The client is maximized (horizontally and vertically) or not |
maximized\_horizontal | The client is maximized horizontally or not |
maximized\_vertical | The client is maximized vertically or not |
transient\_for | The client the window is transient for |
group\_window | Window identification unique to a group of windows |
leader\_window | Identification unique to windows spawned by the same command |
size\_hints | A table with size hints of the client |
motif\_wm\_hints | The motif WM hints of the client |
sticky | Set the client sticky, i |
modal | Indicate if the client is modal |
focusable | True if the client can receive the input focus |
shape\_bounding | The client's bounding shape as set by awesome as a (native) cairo surface |
shape\_clip | The client's clip shape as set by awesome as a (native) cairo surface |
shape\_input | The client's input shape as set by awesome as a (native) cairo surface |
client\_shape\_bounding | The client's bounding shape as set by the program as a (native) cairo surface |
client\_shape\_clip | The client's clip shape as set by the program as a (native) cairo surface |
startup\_id | The FreeDesktop StartId |
valid | If the client that this object refers to is still managed by awesome |
first\_tag | The first tag of the client |
buttons | Get or set mouse buttons bindings for a client |
keys | Get or set keys bindings for a client |
Info:
- Copyright: 2009 Julien Danjou
-
Originally authored by: Julien Danjou <julien@danjou.info>
(Full contributors list available on our github project)
Functions
ruled.client.append_rule (rule) | Add a new rule to the default set. | |
ruled.client.append_rules (rules) | Add a new rules to the default set. | |
ruled.client.remove_rule (rule) | Remove a new rule to the default set. |
Static module functions
ruled.client.match (c, rule) -> bool | Check if a client matches a rule. | |
ruled.client.match_any (c, rule) -> bool | Check if a client matches any part of a rule. | |
ruled.client.matches (c, entry) -> bool | Does a given rule entry match a client? | |
ruled.client.matching_rules (c, _rules) -> table | Get list of matching rules for a client. | |
ruled.client.matches_list (c, _rules) -> bool | Check if a client matches a given set of rules. | |
ruled.client.remove_rule_source (name) -> boolean | Remove a source. | |
ruled.client.apply (c) | Apply ruled.client.rules to a client. | |
ruled.client.add_rule_source (name, callback, depends_on, precede) -> boolean | Add a new rule source. | |
ruled.client.execute (c, props[, callbacks]) | Apply properties and callbacks to a client. |
Rule sources
awful.rules | The default ruled.client source. | |
awful.spawn | The rule source for clients spawned by awful.spawn. | |
awful.spawn_once |
The rule source for clients spawned by awful.spawn.once and single_instance .
|
Rule components
properties | table | A table whose content will be used to set the target object properties. | |
callbacks | table | A list of callback function to call after the properties have been apploed. | |
rule | table | A table whose content will be compared to the target object current properties. | |
rule_any | table | Similar to rule, but each entry is a table with multiple values. | |
except | table | The negative equivalent of rule. | |
except_any | table | The negative equivalent of rule_any. | |
rule_every | table | Matches when one of every \"category\" of components match. | |
rule_lesser | table | A table whose content will be compared to the target object current properties. | |
rule_greater | table | A table whose content will be compared to the target object current properties. | |
id | table or string or number or function | An identifier for this rule. |
Tables
ruled.client.extra_properties | Extra rules properties. | |
ruled.client.high_priority_properties | Extra high priority properties. | |
ruled.client.delayed_properties | Delayed properties. |
Functions
Methods- ruled.client.append_rule (rule)
-
Add a new rule to the default set.
Parameters:
- rule table A valid rule.
- ruled.client.append_rules (rules)
-
Add a new rules to the default set.
Parameters:
- rules table A table with rules.
- ruled.client.remove_rule (rule)
-
Remove a new rule to the default set.
Parameters:
- rule table or string A valid rule or a name passed in the id value when calling append_rule.
Static module functions
- ruled.client.match (c, rule) -> bool
-
Check if a client matches a rule.
Parameters:
- c client The client.
- rule table The rule to check.
Returns:
-
bool
True if it matches, false otherwise.
- ruled.client.match_any (c, rule) -> bool
-
Check if a client matches any part of a rule.
Parameters:
- c client The client.
- rule table The rule to check.
Returns:
-
bool
True if at least one rule is matched, false otherwise.
- ruled.client.matches (c, entry) -> bool
-
Does a given rule entry match a client?
Parameters:
- c client The client.
- entry table Rule entry (with keys rule, rule_any, except and/or except_any).
Returns:
-
bool
- ruled.client.matching_rules (c, _rules) -> table
-
Get list of matching rules for a client.
Parameters:
- c client The client.
- _rules table The rules to check. List with "rule", "ruleany", "except" and "exceptany" keys.
Returns:
-
table
The list of matched rules.
- ruled.client.matches_list (c, _rules) -> bool
-
Check if a client matches a given set of rules.
Parameters:
- c client The client.
- _rules table The rules to check. List of tables with rule, rule_any, except and except_any keys.
Returns:
-
bool
True if at least one rule is matched, false otherwise.
- ruled.client.remove_rule_source (name) -> boolean
-
Remove a source.
Parameters:
- name string The source name.
Returns:
-
boolean
If the source was removed.
- ruled.client.apply (c)
-
Apply ruled.client.rules to a client.
Parameters:
- c client The client.
- ruled.client.add_rule_source (name, callback, depends_on, precede) -> boolean
-
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
andborder_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
ornew_tag
are on that screen or remove those properties. Otherwise, they will be ignored once the rule is applied.Parameters:
- 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.
- ruled.client.execute (c, props[, callbacks]) · 1 permission
-
Apply properties and callbacks to a client.
Parameters:
- c client The client.
- props table Properties to apply.
- callbacks table Callbacks to apply. (optional)
Click to display more Requested actions or permissions:
Class Permission Context Default Description client titlebars rules granted The titlebars_enabled
is set in the rules.
Rule sources
- awful.rules
-
The default ruled.client source.
It is called awful.rules for historical reasons.
Has priority over:
nothing
- awful.spawn
-
The rule source for clients spawned by awful.spawn.
Has priority over:
- awful.spawn_once
-
The rule source for clients spawned by awful.spawn.once and
single_instance
.Has priority over:
Depends on:
Rule components
- properties table
-
A table whose content will be used to set the target object properties.
See also:
- callbacks table
-
A list of callback function to call after the properties have been apploed.
See also:
- rule table
-
A table whose content will be compared to the target object current properties.
See also:
- rule_any table
-
Similar to rule, but each entry is a table with multiple values.
See also:
- except table
-
The negative equivalent of rule.
See also:
- except_any table
-
The negative equivalent of rule_any.
See also:
- rule_every table
-
Matches when one of every \"category\" of components match.
See also:
- rule_lesser table
-
A table whose content will be compared to the target object current properties.
The comparison will be made using the lesser (
<
) operator.See also:
- rule_greater table
-
A table whose content will be compared to the target object current properties.
The comparison will be made using the greater (
>
) operator.See also:
- id table or string or number or function
-
An identifier for this rule.
It can be anything. It will be compared with the
==
operator. Strings are highly recommended.Setting an id is useful to be able to remove the rule by using its id instead of a table reference. Modules can also listen to
rule::appended
and modify or disable a rule.
Tables
- ruled.client.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 ruled.client.extra_properties.my_new_property(c, value, props) -- do something end
By default, the table has the following functions:
- geometry
- placement
- ruled.client.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 ruled.client.high_priority_properties.my_new_property(c, value, props) -- do something end
By default, the table has the following functions:
- tag
- new_tag
- ruled.client.delayed_properties
- Delayed properties. Properties applied after all other categories.