unexist.dev

h1. Tagging

{{>toc}}

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

There are two ways to define a [[Tags|tag]] in the [[config]]:

h2. Simple

The simple way just needs a name and a "regular expression":http://en.wikipedia.org/wiki/Regular_expression to just handle the placement:

<pre><code class="ruby">tag "tagname", "xterm"</code></pre>

h2. Extended

Additionally [[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]].

<pre><code class="ruby">

tag "tag" do

  match   "xterm|[u]?rxvt"

  gravity :center

end

</code></pre>

h2. Default

Whenever a [[Clients|client]] has no [[Tagging|tags]] it gets the +default+ [[Tagging|tag]] and is placed on the [[Views#Default|default  view]].

Example:

<pre><code class="ruby">

view "terms", "terms",

view "www", "default|browser",

view "dev", "editor"

</code></pre>

h2. Modes

Following modes exist:

h3. Borderless 

Enables the [[Clients#Borderless|borderless mode]] for [[Tagging|tagged]] [[clients]]. When set, any borders around the [[clients|client]] are absent.

<pre><code class="ruby">

tag "borderless" do

  match "xterm"

  set   :borderless

end</code></pre>

h3. Fixed

Enables the [[Clients#Fixed|fixed mode]] for [[Tagging|tagged]] [[clients]]. When set, the [[clients|client]] cannot be resized anymore.

<pre><code class="ruby">

tag "fixed" do

  match "xterm"

  set   :fixed

end</code></pre>

h3. Floating

This property enables the [[Clients#Floating|floating mode]] [[Tagging|tagged]] [[clients]].

<pre><code class="ruby">

tag "floating" do

  match "xterm"

  set   :floating

end

</code></pre>

h3. Full

Enable the [[Clients#Fullscreen|fullscreen mode]] for [[Tagging|tagged]] [[Clients|clients]]. When set, the [[clients|client] covers the whole screen size.

<pre><code class="ruby">

tag "full" do

  match "xterm"

  set   :full

end

</code></pre>

h3. Resize

Enable the [[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.

<pre><code class="ruby">

tag "resize" do

  match "xterm"

  set   :resize

end

</code></pre>

h3. Sticky

Enable 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]].

Supported values are either true or a number to specify a screen.

<pre><code class="ruby">

tag "sticky" do

  match "xterm"

  set   :sticky

end

</code></pre>

h3. Urgent

Enable the [[Clients#Urgent|urgent mode]] for [[Tagging|tagged]] [[clients]]. When set, [[subtle]] automatically sets this [[client]] to [Clients#Urgent|urgent]].

<pre><code class="ruby">

tag "urgent" do

  match "xterm"

  set   :urgent

end

</code></pre>

h3. Zaphod

Enable the [[Clients#Zaphod|zaphod mode]] for [[Tagging|tagged]] [[clients]]. When set, the [[clients|client]] spans across all connected [[multihead|screens]].

<pre><code class="ruby">

tag "zaphod" do

  match "xterm"

  set   :zaphod

end</code></pre>

h2. Options

Following options exist:

h3. Set

Set various [[Tagging#Modes|modes] for [[Tagging|tagged]] [[clients]]. Multiple modes can be set separated by comma.

<pre><code class="ruby">

tag "modes" do

  match "xterm"

  set   :floating, :sticky

end

</code></pre>

h3. Geometry

Set a certain geometry for the [[Tagging|tagged]] [[Clients|client]] and put it in floating mode, but +only+ on [[views]] that have this [[Tagging|tag]] in common. Expected is 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.

<pre><code class="ruby">

tag "geometry" do

  match    "xterm"

  geometry [ 10, 10, 100, 100 ]

end

</code></pre>

h3. Gravity

Sets a certain to [[gravity]] to the [[Tagging|tagged]] [[Clients|client]], but +only+ on [[views]] that have this [[Tagging|tag]] in common.

<pre><code class="ruby">

tag "gravity" do

  match   "xterm"

  gravity :center

end

</code></pre>

h3. Match

Adds a matching patterns to a [[Tagging|tag]], this can be done more than once. Matching works either via plaintext, "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]].

h4. Regular expression

When 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]].

h4. Selector

A [[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]].

Every [[Tagging#Selector|selector]] consists of a type and a value:

<pre><code class="ruby">

tag "example" do

  match type: value

end

</code></pre>

Following types exist:

| *:name*     | Match the [[Client#WM_NAME|window name]]           |

| *:instance* | Match the [[Client#WM_CLASS|window instance name]] |

| *:class*    | Match the [[Client#WM_CLASS|window class name]]    |

| *:role*     | Match the [[Client#WM_ROLE|window role]]           |

| *:type*     | Match the [[Clients#Types|window type]]            |

{{needs(r2830)}}

h4. Boolean logic

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

h5. AND

All [[Tagging#Selector|selector]] are required in order for this [[Tagging|tag]] to be applied.

<pre><code class="ruby">

tag "AND" do

  match instance: "xterm", instance: "urxvt"

end

</code></pre>

h5. OR

Only one matching [[Tagging#Selector|selector]] is required in order for this [[Tagging|tag]] to be applied.

<pre><code class="ruby">

tag "OR" do

  match "xterm"

  match "urxvt"

end

</code></pre>

{{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.)}}

Please also check the "How do I tag console based programs?":http://subforge.org/ezfaq/show/subtle?faq_id=15 FAQ entry.

{{needs(r3209)}}

h3. On_match

Add a "Ruby":http://ruby-lang.org proc to a [[tagging|tag]] that is executed 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]].

<pre><code class="ruby">

tag "gimp" do

  match role: "gimp.*"

  on_match do |c|

    c.gravity = ("gimp_" + c.role.split("-")[1]).to_sym

  end

end

</code></pre>

h3. Position

Similar to the geometry option, set the x/y coordinates of the [[Tagging|tagged]] [[Clients|client]], but +only+ on [[views]] with common [[Tagging|tag]]. 

Expected is an "array":http://www.ruby-doc.org/core/classes/Array.html with *x* and *y* values.

<pre><code class="ruby">

tag "position" do

  match    "xterm"

  position [ 10, 10 ]

end

</code></pre>

h3. Type

Set the window type of the [[Tagging|tagged]] [[Clients|client]], this forces it to be treated as a specific window type though as the window sets the type itself. 

Following types are possible:

{{needs(r2905)}}

| *:normal* | Treat as [[Clients#Normal|normal window]]                                     |

| *:desktop* | Treat as [[Clients#Desktop|desktop window]] (__NET_WM_WINDOW_TYPE_DESKTOP_)  |

| *:dock*    | Treat as [[Clients#Dock|dock window]] (__NET_WM_WINDOW_TYPE_DOCK_)           |

| *:toolbar* | Treat as [[Clients#Toolbar|toolbar windows]] (__NET_WM_WINDOW_TYPE_TOOLBAR_) |

| *:splash*  | Treat as [[Clients#splash|splash window]] (__NET_WM_WINDOW_TYPE_SPLASH_)     |

| *:dialog*  | Treat as [[Clients#Dialog|dialog window]] (__NET_WM_WINDOW_TYPE_DIALOG_)     |

<pre><code class="ruby">

tag "desktop" do

  match   "xterm"

  type    :desktop

end

</code></pre>

h2. Examples

<pre><code class="ruby">

tag "bashrun" do

  match    "bashrun"

  geometry [ 50, 1000, 200, 28 ]#

  stick    true

  urgent   true

end

tag "browser" do

  match   "chrom[e|ium]"

  gravity :center

end

</code></pre>