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:

Usage example

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:

Usage example

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:

Usage example

-- 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:

Usage example

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:

Usage example

-- 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

Client rules

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

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

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

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

ruled.client.remove_rule_source (name) -> boolean

Remove a source.

Parameters:

name string The source name.

Returns:

boolean

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 and border_width need to be applied before the x and y 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.

Parameters:

name string The provider name. It must be unique.
callback The callback that is called to produce properties.
- c client The client
- properties table The current properties. The callback should add to and overwrite properties in this table
- callbacks table A table of all callbacks scheduled to be executed after the main properties are applied.
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

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.rules

awful.spawn_once

The rule source for clients spawned by awful.spawn.once and single_instance.

Has priority over:

awful.rules

Depends on:

awful.spawn

Rule components

properties table

A table whose content will be used to set the target object properties.

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.

awesome

Contents

Declarative rules

Core components

Input handling

Widgets

Widget containers

Widget layouts

Popups and bars

Utility libraries

Theme related libraries

Client tiling

Libraries

Sample files

Classes

Documentation

Module: ruled.client

Syntax

Flowchart

Applicable client properties

Info:

Functions

Static module functions

Rule sources

Rule components

Tables

Functions

Parameters:

Parameters:

Parameters:

Static module functions

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Parameters:

Returns:

Parameters:

Requested actions or permissions:

Rule sources

Rule components

See also:

See also:

See also:

See also:

See also:

See also:

See also:

See also:

See also:

Tables

Module: `ruled.client`