Project

General

Profile

unexist.dev

subtle

Assorted tidbits and projects

History

Tagging

Tags are generally used in subtle for placement of clients. This placement is mandatory, that means that - aside from other tiling window managers - clients must have a matching tag to be on a certain view. This also includes that clients, that are started on a certain view, aren't automatically placed there.

There are two ways to define a tag in the config:

Simple

The simple way just needs a name and a regular expression to just handle the placement:

tag "tagname", "xterm"

Extended

Additionally tags can do a lot more then just control the placement - they also have properties to define and control some aspects of a client like the gravity or modes.

tag "tag" do
  match   "xterm|[u]?rxvt" 
  gravity :center
end

Default

Whenever a client has no tags it gets the default tag and is placed on the default view.

Example:

view "terms", "terms",
view "www", "default|browser",
view "dev", "editor"

Modes

Following modes exist:

Borderless

Enables the borderless mode for tagged clients. When set, any borders around the client are absent.

tag "borderless" do
  match "xterm" 
  set   :borderless
end

Fixed

Enables the fixed mode for tagged clients. When set, the client cannot be resized anymore.

tag "fixed" do
  match "xterm" 
  set   :fixed
end

Floating

This property enables the floating mode tagged clients.

tag "floating" do
  match "xterm" 
  set   :floating
end

Full

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

tag "full" do
  match "xterm" 
  set   :full
end

Resize

Enable the resize mode for tagged clients. When set, subtle honors size hints of the clients, that define various size constraints like sizes for columns or rows of a terminal.

tag "resize" do
  match "xterm" 
  set   :resize
end

Sticky

Enable the sticky mode for tagged clients. When set, subtle keeps the [[clients|client] on the current screen, regardless of the tags.

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

tag "sticky" do
  match "xterm" 
  set   :sticky
end

Urgent

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

tag "urgent" do
  match "xterm" 
  set   :urgent
end

Zaphod

Enable the zaphod mode for tagged clients. When set, the client spans across all connected screens.

tag "zaphod" do
  match "xterm" 
  set   :zaphod
end

Options

Following options exist:

Set

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

tag "modes" do
  match "xterm" 
  set   :floating, :sticky
end

Geometry

Set a certain geometry for the tagged client and put it in floating mode, but only on views that have this tag in common. Expected is an array with x, y, width and height values whereas width and height must be >0.

tag "geometry" do
  match    "xterm" 
  geometry [ 10, 10, 100, 100 ]
end

Gravity

Sets a certain to gravity to the tagged client, but only on views that have this tag in common.

tag "gravity" do
  match   "xterm" 
  gravity :center
end

Match

Adds a matching patterns to a tag, this can be done more than once. Matching works either via plaintext, regular expression (see regex) or a selector based on different values/properties of a client.

Regular expression

When a regular expression is used, subtle uses both parts of the WM_CLASS property for matching.

Selector

A selector is a more complicated, but finer grained way to match clients and it even allows to combine multiple matcher with simple boolean logic.

Every selector consists of a type and a value:

tag "example" do
  match type: value
end

Following types exist:

:name Match the window name
:instance Match the window instance name
:class Match the window class name
:role Match the window role
:type Match the window type

{{needs(r2830)}}

Boolean logic

Boolean logic allows to select a broader range of clients without difficult regular expressions and/or a required combination of multiple selector types.

AND

All selector are required in order for this tag to be applied.

tag "AND" do
  match instance: "xterm", instance: "urxvt" 
end
OR

Only one matching selector is required in order for this tag to be applied.

tag "OR" do
  match "xterm" 
  match "urxvt" 
end

{{info(When dealing with console-based apps please keep in mind, that tagging via WM_NAME won't work as expected. 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? FAQ entry.

{{needs(r3209)}}

On_match

Add a Ruby proc to a tag that is executed whenever the tag is applied to a client. This allows to add logic to a tag to ease e.g. simple placement tags.

tag "gimp" do
  match role: "gimp.*" 

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

Position

Similar to the geometry option, set the x/y coordinates of the tagged client, but only on views with common tag.

Expected is an array with x and y values.

tag "position" do
  match    "xterm" 
  position [ 10, 10 ]
end

Type

Set the window type of the tagged 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 normal window
:desktop Treat as desktop window (_NET_WM_WINDOW_TYPE_DESKTOP)
:dock Treat as dock window (_NET_WM_WINDOW_TYPE_DOCK)
:toolbar Treat as toolbar windows (_NET_WM_WINDOW_TYPE_TOOLBAR)
:splash Treat as splash window (_NET_WM_WINDOW_TYPE_SPLASH)
:dialog Treat as dialog window (_NET_WM_WINDOW_TYPE_DIALOG) 
tag "desktop" do
  match   "xterm" 
  type    :desktop
end

Examples

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