# Module: `ruled.client`

Apply properties to a new client based on pre-determined rules.

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

![Client rules](../images/client_rules.svg)

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
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 (Never mapped, invisible in taskbar)
minimized | Define if the client must be iconified (Only visible in taskbar)
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 (Available on all tags)
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
client\_shape\_input | The client's input 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. |
callback | function | A callback function to call *before* the properties have been applied. |
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

🔗 ruled.client.append_rule (rule)
  Add a new rule to the default set.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  rule |  | table | A valid rule.

🔗 ruled.client.append_rules (rules)
  Add a new rules to the default set.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  rules |  | table | A table with rules.

🔗 ruled.client.remove_rule (rule)
  Remove a new rule to the default set.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  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:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  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:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  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:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  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:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  c |  | client | 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.
🔗 ruled.client.matches_list (c, rules) -> bool
  Check if a client matches a given set of rules.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  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 |  | Type(s) | Description
  --- | --- | --- | ---
  name |  | string | The source name.

  ### Returns:

  boolean If the source was removed.
🔗 ruled.client.apply (c)
  Apply ruled.client.rules to a client.

  ### Parameters:

  Name |  | Type(s) | Description
  --- | --- | --- | ---
  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 |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  name |  | string | The provider name. It must be unique. | Not applicable
  callback |  | table | The callback that is called to produce properties. | Not applicable
  c |  | client | The client | Not applicable
  properties |  | table | The current properties. The callback should add to and overwrite properties in this table | Not applicable
  callbacks |  | table | A table of all callbacks scheduled to be executed after the main properties are applied. | Not applicable
  depends_on | Optional | table | A list of names of sources this source depends on (sources that must be executed *before* `name`. | `{}`
  precede | Optional | table | A list of names of sources this source have a priority over. | `{}`

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

  Name |  | Type(s) | Description | Default value
  --- | --- | --- | --- | ---
  c |  | client | The client. | Not applicable
  props |  | table | Properties to apply. | Not applicable
  callbacks | Optional | table | Callbacks to apply. | `{}`

  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.

  ### See also:

  callback | A callback function to call *before* the properties have been applied. | rule components

🔗 callback function
  A callback function to call *before* the properties have been applied.

  The callback is called with the current client as first argument.

🔗 rule table
  A table whose content will be compared to the target object current properties.

  ### See also:

  rule_any | Similar to rule, but each entry is a table with multiple values. | rule components
  except | The negative equivalent of rule. | rule components

🔗 rule_any table
  Similar to rule, but each entry is a table with multiple values.

  ### See also:

  rule | A table whose content will be compared to the target object current properties. | rule components
  except_any | The negative equivalent of rule_any. | rule components

🔗 except table
  The negative equivalent of rule.

  ### See also:

  rule | A table whose content will be compared to the target object current properties. | rule components
  except_any | The negative equivalent of rule_any. | rule components

🔗 except_any table
  The negative equivalent of rule_any.

  ### See also:

  rule | A table whose content will be compared to the target object current properties. | rule components
  except | The negative equivalent of rule. | rule components

🔗 rule_every table
  Matches when one of every \"category\" of components match.

  ### See also:

  rule | A table whose content will be compared to the target object current properties. | rule components
  except | The negative equivalent of rule. | rule components

🔗 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 | A table whose content will be compared to the target object current properties. | rule components
  except | The negative equivalent of rule. | rule components

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

  rule | A table whose content will be compared to the target object current properties. | rule components
  except | The negative equivalent of rule. | rule components

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

generated by LDoc 1.5.0