unexist.dev

h1. Tagging\015\012\015\012{{>toc}}\015\012\015\012\015\012[[Tags]] are generally used in [[subtle]] for placement of [[Clients|clients]]. This placement is *mandatory*, that means that - aside from other tiling window managers - [[Clients|clients]] _must have_ a matching [[Tags|tag]] to be on a certain [[Views|view]]. This also includes that [[Clients|clients]], that are started on a certain [[Views|view]], *aren't* automatically placed there.\015\012\015\012There are two ways to define a [[Tags|tag]] in the [[config]]:\015\012\015\012h2. Simple\015\012\015\012The simple way just needs a name and a "regular expression":http://en.wikipedia.org/wiki/Regular_expression to just handle the placement:\015\012\015\012<pre><code class="ruby">tag "tagname", "xterm"</code></pre>\015\012\015\012h2. Extended\015\012\015\012Additionally [[Tagging|tags]] can do a lot more then just control the placement - they also have properties to define and control some aspects of a [[Clients|client]] like the [[gravity]] or [[Clients#Modes|modes]].\015\012\015\012<pre>{{hide}}<code class="ruby">\015\012tag "tag" do\015\012 match "xterm|[u]?rxvt"\015\012 gravity :center\015\012end\015\012</code></pre>\015\012\015\012h2. Default\015\012\015\012Whenever a [[Clients|client]] has no [[Tagging|tags]] it gets the +default+ [[Tagging|tag]] and is placed on the [[Views#Default|default view]].\015\012\015\012Example:\015\012\015\012<pre>{{hide}}<code class="ruby">\015\012view "terms", "terms",\015\012view "www", "default|browser",\015\012view "dev", "editor"\015\012</code></pre>\015\012\015\012h2. Modes\015\012\015\012Following modes exist:\015\012\015\012h3. Properties\015\012\015\012Following properties exist:\015\012\015\012{{needs(r2900)}}\015\012\015\012h3. Borderless \015\012\015\012Enables \015\012\015\012This property enables the [[Clients#Borderless|borderless mode]] for [[Tagging|tagged]] [[clients]]. When set, any borders around the [[clients|client]] are absent.\015\012\015\012<pre>{{hide}}<code [[clients]].\015\012\015\012<pre>{{hide}}<code class="ruby">\015\012tag "borderless" do\015\012 match "xterm"\015\012 set :borderless\015\012end</code></pre>\015\012\015\012h3. Fixed\015\012\015\012Enables the [[Clients#Fixed|fixed mode]] for [[Tagging|tagged]] [[clients]]. When set, the [[clients|client]] cannot be resized anymore.\015\012\015\012<pre>{{hide}}<code class="ruby">\015\012tag "fixed" do\015\012 borderless match "xterm"\015\012 set :fixed\015\012end</code></pre>\015\012\015\012h3. Floating\015\012\015\012This true\015\012end</code></pre>\015\012\015\012{{needs(r2909)}}\015\012\015\012h3. Center\015\012\015\012This property enables the [[Clients#Floating|floating [[Clients#Center|center mode]] for [[Tagging|tagged]] [[clients]].\015\012\015\012<pre>{{hide}}<code class="ruby">\015\012tag "floating" "center" do\015\012 match "xterm"\015\012 set :floating\015\012end\015\012</code></pre>\015\012\015\012h3. Full\015\012\015\012Enable the [[Clients#Fullscreen|fullscreen mode]] for [[Tagging|tagged]] [[Clients|clients]]. When set, the [[clients|client] covers the whole screen size.\015\012\015\012<pre>{{hide}}<code class="ruby">\015\012tag "full" do\015\012 center match "xterm"\015\012 set :full\015\012end\015\012</code></pre>\015\012\015\012h3. Resize\015\012\015\012Enable true\015\012end</code></pre>\015\012\015\012{{needs(r2890)}}\015\012\015\012h3. Fixed\015\012\015\012This property enables the [[Clients#Resize|resize [[Clients#Fixed|fixed mode]] for [[Tagging|tagged]] [[clients]]. When set, [[subtle]] honors "size hints":http://tronche.com/gui/x/icccm/sec-4.html#s-4.1.2.3 of the [[clients]], that define various size constraints like sizes for columns or rows of a terminal.\015\012\015\012<pre>{{hide}}<code [[clients]].\015\012\015\012<pre>{{hide}}<code class="ruby">\015\012tag "resize" "fixed" do\015\012 match "xterm"\015\012 set :resize\015\012end\015\012</code></pre>\015\012\015\012h3. Sticky\015\012\015\012Enable the [[Clients#Sticky|sticky mode]] for [[Tagging|tagged]] [[clients]]. When set, [[subtle]] keeps the [[clients|client] on the current [[multihead|screen]], regardless of the [[tagging|tags]].\015\012\015\012Supported values are either true or a number to specify a screen.\015\012\015\012<pre>{{hide}}<code class="ruby">\015\012tag "sticky" do\015\012 fixed match "xterm"\015\012 set :sticky\015\012end\015\012</code></pre>\015\012\015\012h3. Urgent\015\012\015\012Enable true\015\012end</code></pre>\015\012\015\012h3. Float\015\012\015\012This property enables the [[Clients#Urgent|urgent [[Clients#Floating|floating mode]] for [[Tagging|tagged]] [[clients]]. When set, [[subtle]] automatically sets this [[client]] to [Clients#Urgent|urgent]].\015\012\015\012<pre>{{hide}}<code [[clients]].\015\012\015\012<pre>{{hide}}<code class="ruby">\015\012tag "urgent" "float" do\015\012 match "xterm"\015\012 match"xterm"\015\012 set :urgent\015\012end\015\012</code></pre>\015\012\015\012h3. Zaphod\015\012\015\012Enable float true\015\012end\015\012</code></pre>\015\012\015\012h3. Full\015\012\015\012This property enables the [[Clients#Zaphod|zaphod [[Clients#Fullscreen|fullscreen mode]] for [[Tagging|tagged]] [[clients]]. When set, the [[clients|client]] spans across all connected [[multihead|screens]].\015\012\015\012<pre>{{hide}}<code [[Clients|clients]].\015\012\015\012<pre>{{hide}}<code class="ruby">\015\012tag "zaphod" "full" do\015\012 match "xterm"\015\012 set :zaphod\015\012end</code></pre>\015\012\015\012h2. Options\015\012\015\012Following options exist:\015\012\015\012h3. Set\015\012\015\012Set various [[Tagging#Modes|modes] for [[Tagging|tagged]] [[clients]]. Multiple modes can be set separated by comma.\015\012\015\012<pre>{{hide}}<code class="ruby">\015\012tag "modes" do\015\012 full match "xterm"\015\012 set :floating, :sticky\015\012end\015\012</code></pre>\015\012\015\012h3. Geometry\015\012\015\012Set true\015\012end\015\012</code></pre>\015\012\015\012h3. Geometry\015\012\015\012This property sets a certain geometry for as well as floating to the [[Tagging|tagged]] [[Clients|client]] and put it in floating mode, [[Clients|client]], but +only+ on [[views]] that have this [[Tagging|tag]] in common. Expected is tag too. It expects an "array":http://www.ruby-doc.org/core/classes/Array.html with *x*, *y*, *width* and *height* values whereas width and height *must* be >0.\015\012\015\012<pre>{{hide}}<code class="ruby">\015\012tag "geometry" do\015\012 match "xterm"\015\012 geometry [ 10, 10, 100, 100 ]\015\012end\015\012</code></pre>\015\012\015\012h3. Gravity\015\012\015\012Sets Gravity\015\012\015\012This property sets a certain to [[gravity]] to the [[Tagging|tagged]] [[Clients|client]], but +only+ on [[views]] that have this [[Tagging|tag]] in common.\015\012\015\012<pre>{{hide}}<code [[Tagging|matching]] [[views]].\015\012\015\012<pre>{{hide}}<code class="ruby">\015\012tag "gravity" do\015\012 match "xterm"\015\012 gravity :center\015\012end\015\012</code></pre>\015\012\015\012h3. Match\015\012\015\012Adds Match\015\012\015\012This property adds a matching patterns matcher to a [[Tagging|tag]], this can be done more than once. Matching works that is either via plaintext, a simple "regular expression":http://en.wikipedia.org/wiki/Regular_expression (see "regex(7)":http://linux.die.net/man/7/regex) or a [[Tagging#Selector|selector]] based on different values/properties of a [[Clients|client]].\015\012\015\012h4. Regular expression\015\012\015\012When a "regular expression":http://en.wikipedia.org/wiki/Regular_expression is used, [[subtle]] uses both parts of the [[Clients#WM_CLASS|WM_CLASS]] property for [[Tagging|matching]].\015\012\015\012h4. Selector\015\012\015\012A [[Tagging#Selector|selector]] is a more complicated, but finer grained way to match [[Clients|clients]] and it even allows to combine multiple matcher with simple [[Tagging#Boolean_logic|boolean logic]].\015\012\015\012Every [[Tagging#Selector|selector]] consists of a type and a value:\015\012\015\012<pre>{{hide}}<code class="ruby">\015\012tag "example" do\015\012 match type: value\015\012end\015\012</code></pre>\015\012\015\012Following types exist:\015\012\015\012| *&#58;name* | Match the [[Client#WM_NAME|window name]] |\015\012| *&#58;instance* | Match the [[Client#WM_CLASS|window instance name]] |\015\012| *&#58;class* | Match the [[Client#WM_CLASS|window class name]] |\015\012| *&#58;role* | Match the [[Client#WM_ROLE|window role]] |\015\012| *&#58;type* | Match the [[Clients#Types|window type]] |\015\012\015\012{{needs(r2830)}}\015\012\015\012h4. Boolean logic\015\012\015\012"Boolean logic":http://en.wikipedia.org/wiki/Boolean_algebra_(logic) allows to select a broader range of [[Clients|clients]] without difficult "regular expressions":http://en.wikipedia.org/wiki/Regular_expression and/or a required combination of multiple [[Tagging#Selector|selector]] types.\015\012\015\012h5. AND\015\012\015\012All [[Tagging#Selector|selector]] are required in order for this [[Tagging|tag]] to be applied.\015\012\015\012<pre>{{hide}}<code class="ruby">\015\012tag "AND" do\015\012 match instance: "xterm", instance: "urxvt"\015\012end\015\012</code></pre>\015\012\015\012h5. OR\015\012\015\012Only one matching [[Tagging#Selector|selector]] is required in order for this [[Tagging|tag]] to be applied.\015\012\015\012<pre>{{hide}}<code class="ruby">\015\012tag "OR" do\015\012 match "xterm"\015\012 match "urxvt"\015\012end\015\012</code></pre>\015\012\015\012{{info(When dealing with console-based apps please keep in mind, that [[Tagging|tagging]] via [[Client#WM_NAME|WM_NAME]] won't work as expected. [[Tagging|Tags]] are usually applied *when* the terminal starts and *before* the shell with the app is spawned.)}}\015\012\015\012Please also check the "How do I tag console based programs?":http://subforge.org/ezfaq/show/subtle?faq_id=15 FAQ entry.\015\012\015\012{{needs(r3209)}}\015\012\015\012h3. On_match\015\012\015\012Add a On_match\015\012\015\012This property adds "Ruby":http://ruby-lang.org proc to a [[tagging|tag]] that is executed called whenever the [[tagging|tag]] is applied to a [[clients|client]]. This allows to add logic to a [[tagging|tag]] to ease e.g. simple placement [[tagging|tags]].\015\012\015\012<pre>{{hide}}<code class="ruby">\015\012tag "gimp" do\015\012 match role: "gimp.*"\015\012\015\012 on_match do |c|\015\012 c.gravity = ("gimp_" + c.role.split("-")[1]).to_sym\015\012 end\015\012end\015\012</code></pre>\015\012\015\012h3. Position\015\012\015\012Similar to the geometry option, set property, this property just sets the x/y coordinates of the [[Tagging|tagged]] [[Clients|client]], but +only+ on [[views]] with common [[Tagging|tag]]. \015\012\015\012Expected is that have this [[Tagging|tag]], too. It expects an "array":http://www.ruby-doc.org/core/classes/Array.html with *x* and *y* values.\015\012\015\012<pre>{{hide}}<code class="ruby">\015\012tag "position" do\015\012 match "xterm"\015\012 position [ 10, 10 ]\015\012end\015\012</code></pre>\015\012\015\012h3. Type\015\012\015\012Set Resize\015\012\015\012This property enables the window type [[Clients#Resize|resize mode]] for [[Tagging|tagged]] [[clients]]. When set, [[subtle]] honors "size hints":http://tronche.com/gui/x/icccm/sec-4.html#s-4.1.2.3 of the [[clients]], that define various size constraints like sizes for columns or rows of a terminal.\015\012\015\012<pre>{{hide}}<code class="ruby">\015\012tag "resize" do\015\012 match "xterm"\015\012 resize true\015\012end\015\012</code></pre>\015\012\015\012h3. Stick\015\012\015\012This property enables the [[Clients#Sticky|sticky mode]] for [[Tagging|tagged]] [[Clients|client]], this forces it [[clients]]. When set, [[clients]] are visible on all [[views|view]], even when they don't have matching [[tagging|tags]]. On [[multihead]] [[Clients#Sticky|sticky]] [[clients]] stay on the current [[multihead|screen]] as long as they are [Clients#Sticky|sticky]].\015\012\015\012{{needs(r3164)}}\015\012Supported values are either true or a number to specify a screen.\015\012\015\012<pre>{{hide}}<code class="ruby">\015\012tag "stick" do\015\012 match "xterm"\015\012 stick true\015\012end\015\012</code></pre>\015\012\015\012h3. Type\015\012\015\012This property sets the [[Tagging|tagged]] [[Clients|client]] to be treated as a specific window type though as the window sets the type itself. \015\012\015\012Following types are possible:\015\012\015\012{{needs(r2905)}}\015\012\015\012| *&#58;normal* | Treat as [[Clients#Normal|normal window]] |\015\012| *&#58;desktop* | Treat as [[Clients#Desktop|desktop window]] (__NET_WM_WINDOW_TYPE_DESKTOP_) |\015\012| *&#58;dock* | Treat as [[Clients#Dock|dock window]] (__NET_WM_WINDOW_TYPE_DOCK_) |\015\012| *&#58;toolbar* | Treat as [[Clients#Toolbar|toolbar windows]] (__NET_WM_WINDOW_TYPE_TOOLBAR_) |\015\012| *&#58;splash* | Treat as [[Clients#splash|splash window]] (__NET_WM_WINDOW_TYPE_SPLASH_) |\015\012| *&#58;dialog* | Treat as [[Clients#Dialog|dialog window]] (__NET_WM_WINDOW_TYPE_DIALOG_) |\015\012\015\012<pre>{{hide}}<code class="ruby">\015\012tag "desktop" do\015\012 match "xterm"\015\012 type :desktop\015\012end\015\012</code></pre>\015\012\015\012h2. :desktop\015\012end\015\012</code></pre>\015\012\015\012h3. Urgent\015\012\015\012This property enables the [[Clients#Urgent|urgent mode]] for [[Tagging|tagged]] [[clients]]. When set, [[subtle]] automatically sets this [[client]] to [Clients#Urgent|urgent]].\015\012\015\012<pre>{{hide}}<code class="ruby">\015\012tag "urgent" do\015\012 match "xterm"\015\012 urgent true\015\012end\015\012</code></pre>\015\012\015\012{{needs(r2871)}}\015\012\015\012h3. Zaphod\015\012\015\012This property enables the [[Clients#Zaphod|zaphod mode]] for [[Tagging|tagged]] [[clients]]. When set, the [[clients|client]] spans across all connected [[multihead|screens]].\015\012\015\012<pre>{{hide}}<code class="ruby">\015\012tag "zaphod" do\015\012 match "xterm"\015\012 zaphod true\015\012end</code></pre>\015\012\015\012h2. Examples\015\012\015\012<pre>{{hide}}<code class="ruby">\015\012tag "bashrun" do\015\012 match "bashrun"\015\012 geometry [ 50, 1000, 200, 28 ]#\015\012 stick true\015\012 urgent true\015\012end\015\012\015\012tag "browser" do\015\012 match "chrom[e|ium]"\015\012 gravity :center\015\012end\015\012</code></pre>