# Module `awful.rules`

Apply rules to clients at startup.

### Info:

- Copyright: 2009 Julien Danjou
- Author: Julien Danjou <julien@danjou.info>

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

## 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/or `except_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", "ruleany", "except" and "exceptany" 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` and `except_any` keys.

  ### Returns:

  bool True if at least one rule is matched, false otherwise.
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.
  - c client The client
  - value boolean, function or string The value.
  - props table The properties.

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

## 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` 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 }
      }

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

generated by LDoc 1.4.6 Last updated 2017-01-20 01:17:18