Project

General

Profile

Tagging » History » Version 64

Christoph Kappel, 01/23/2018 12:23 PM

1 64 Christoph Kappel
h1. Tagging
2 64 Christoph Kappel
3 64 Christoph Kappel
{{>toc}}
4 64 Christoph Kappel
5 64 Christoph Kappel
6 64 Christoph Kappel
[[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.
7 64 Christoph Kappel
8 64 Christoph Kappel
There are two ways to define a [[Tags|tag]] in the [[config]]:
9 64 Christoph Kappel
10 64 Christoph Kappel
h2. Simple
11 64 Christoph Kappel
12 64 Christoph Kappel
The simple way just needs a name and a "regular expression":http://en.wikipedia.org/wiki/Regular_expression to just handle the placement:
13 64 Christoph Kappel
14 64 Christoph Kappel
<pre><code class="ruby">tag "tagname", "xterm"</code></pre>
15 64 Christoph Kappel
16 64 Christoph Kappel
h2. Extended
17 64 Christoph Kappel
18 64 Christoph Kappel
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]].
19 64 Christoph Kappel
20 64 Christoph Kappel
<pre><code class="ruby">
21 64 Christoph Kappel
tag "tag" do
22 64 Christoph Kappel
  match   "xterm|[u]?rxvt"
23 64 Christoph Kappel
  gravity :center
24 64 Christoph Kappel
end
25 64 Christoph Kappel
</code></pre>
26 64 Christoph Kappel
27 64 Christoph Kappel
h2. Default
28 64 Christoph Kappel
29 64 Christoph Kappel
Whenever a [[Clients|client]] has no [[Tagging|tags]] it gets the +default+ [[Tagging|tag]] and is placed on the [[Views#Default|default  view]].
30 64 Christoph Kappel
31 64 Christoph Kappel
Example:
32 64 Christoph Kappel
33 64 Christoph Kappel
<pre><code class="ruby">
34 64 Christoph Kappel
view "terms", "terms",
35 64 Christoph Kappel
view "www", "default|browser",
36 64 Christoph Kappel
view "dev", "editor"
37 64 Christoph Kappel
</code></pre>
38 64 Christoph Kappel
39 64 Christoph Kappel
h2. Modes
40 64 Christoph Kappel
41 64 Christoph Kappel
Following modes exist:
42 64 Christoph Kappel
43 64 Christoph Kappel
h3. Borderless 
44 64 Christoph Kappel
45 64 Christoph Kappel
Enables the [[Clients#Borderless|borderless mode]] for [[Tagging|tagged]] [[clients]]. When set, any borders around the [[clients|client]] are absent.
46 64 Christoph Kappel
47 64 Christoph Kappel
<pre><code class="ruby">
48 64 Christoph Kappel
tag "borderless" do
49 64 Christoph Kappel
  match "xterm"
50 64 Christoph Kappel
  set   :borderless
51 64 Christoph Kappel
end</code></pre>
52 64 Christoph Kappel
53 64 Christoph Kappel
h3. Fixed
54 64 Christoph Kappel
55 64 Christoph Kappel
Enables the [[Clients#Fixed|fixed mode]] for [[Tagging|tagged]] [[clients]]. When set, the [[clients|client]] cannot be resized anymore.
56 64 Christoph Kappel
57 64 Christoph Kappel
<pre><code class="ruby">
58 64 Christoph Kappel
tag "fixed" do
59 64 Christoph Kappel
  match "xterm"
60 64 Christoph Kappel
  set   :fixed
61 64 Christoph Kappel
end</code></pre>
62 64 Christoph Kappel
63 64 Christoph Kappel
h3. Floating
64 64 Christoph Kappel
65 64 Christoph Kappel
This property enables the [[Clients#Floating|floating mode]] [[Tagging|tagged]] [[clients]].
66 64 Christoph Kappel
67 64 Christoph Kappel
<pre><code class="ruby">
68 64 Christoph Kappel
tag "floating" do
69 64 Christoph Kappel
  match "xterm"
70 64 Christoph Kappel
  set   :floating
71 64 Christoph Kappel
end
72 64 Christoph Kappel
</code></pre>
73 64 Christoph Kappel
74 64 Christoph Kappel
h3. Full
75 64 Christoph Kappel
76 64 Christoph Kappel
Enable the [[Clients#Fullscreen|fullscreen mode]] for [[Tagging|tagged]] [[Clients|clients]]. When set, the [[clients|client] covers the whole screen size.
77 64 Christoph Kappel
78 64 Christoph Kappel
<pre><code class="ruby">
79 64 Christoph Kappel
tag "full" do
80 64 Christoph Kappel
  match "xterm"
81 64 Christoph Kappel
  set   :full
82 64 Christoph Kappel
end
83 64 Christoph Kappel
</code></pre>
84 64 Christoph Kappel
85 64 Christoph Kappel
h3. Resize
86 64 Christoph Kappel
87 64 Christoph Kappel
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.
88 64 Christoph Kappel
89 64 Christoph Kappel
<pre><code class="ruby">
90 64 Christoph Kappel
tag "resize" do
91 64 Christoph Kappel
  match "xterm"
92 64 Christoph Kappel
  set   :resize
93 64 Christoph Kappel
end
94 64 Christoph Kappel
</code></pre>
95 64 Christoph Kappel
96 64 Christoph Kappel
h3. Sticky
97 64 Christoph Kappel
98 64 Christoph Kappel
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]].
99 64 Christoph Kappel
100 64 Christoph Kappel
Supported values are either true or a number to specify a screen.
101 64 Christoph Kappel
102 64 Christoph Kappel
<pre><code class="ruby">
103 64 Christoph Kappel
tag "sticky" do
104 64 Christoph Kappel
  match "xterm"
105 64 Christoph Kappel
  set   :sticky
106 64 Christoph Kappel
end
107 64 Christoph Kappel
</code></pre>
108 64 Christoph Kappel
109 64 Christoph Kappel
h3. Urgent
110 64 Christoph Kappel
111 64 Christoph Kappel
Enable the [[Clients#Urgent|urgent mode]] for [[Tagging|tagged]] [[clients]]. When set, [[subtle]] automatically sets this [[client]] to [Clients#Urgent|urgent]].
112 64 Christoph Kappel
113 64 Christoph Kappel
<pre><code class="ruby">
114 64 Christoph Kappel
tag "urgent" do
115 64 Christoph Kappel
  match "xterm"
116 64 Christoph Kappel
  set   :urgent
117 64 Christoph Kappel
end
118 64 Christoph Kappel
</code></pre>
119 64 Christoph Kappel
120 64 Christoph Kappel
h3. Zaphod
121 64 Christoph Kappel
122 64 Christoph Kappel
Enable the [[Clients#Zaphod|zaphod mode]] for [[Tagging|tagged]] [[clients]]. When set, the [[clients|client]] spans across all connected [[multihead|screens]].
123 64 Christoph Kappel
124 64 Christoph Kappel
<pre><code class="ruby">
125 64 Christoph Kappel
tag "zaphod" do
126 64 Christoph Kappel
  match "xterm"
127 64 Christoph Kappel
  set   :zaphod
128 64 Christoph Kappel
end</code></pre>
129 64 Christoph Kappel
130 64 Christoph Kappel
h2. Options
131 64 Christoph Kappel
132 64 Christoph Kappel
Following options exist:
133 64 Christoph Kappel
134 64 Christoph Kappel
h3. Set
135 64 Christoph Kappel
136 64 Christoph Kappel
Set various [[Tagging#Modes|modes] for [[Tagging|tagged]] [[clients]]. Multiple modes can be set separated by comma.
137 64 Christoph Kappel
138 64 Christoph Kappel
<pre><code class="ruby">
139 64 Christoph Kappel
tag "modes" do
140 64 Christoph Kappel
  match "xterm"
141 64 Christoph Kappel
  set   :floating, :sticky
142 64 Christoph Kappel
end
143 64 Christoph Kappel
</code></pre>
144 64 Christoph Kappel
145 64 Christoph Kappel
h3. Geometry
146 64 Christoph Kappel
147 64 Christoph Kappel
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.
148 64 Christoph Kappel
149 64 Christoph Kappel
<pre><code class="ruby">
150 64 Christoph Kappel
tag "geometry" do
151 64 Christoph Kappel
  match    "xterm"
152 64 Christoph Kappel
  geometry [ 10, 10, 100, 100 ]
153 64 Christoph Kappel
end
154 64 Christoph Kappel
</code></pre>
155 64 Christoph Kappel
156 64 Christoph Kappel
h3. Gravity
157 64 Christoph Kappel
158 64 Christoph Kappel
Sets a certain to [[gravity]] to the [[Tagging|tagged]] [[Clients|client]], but +only+ on [[views]] that have this [[Tagging|tag]] in common.
159 64 Christoph Kappel
160 64 Christoph Kappel
<pre><code class="ruby">
161 64 Christoph Kappel
tag "gravity" do
162 64 Christoph Kappel
  match   "xterm"
163 64 Christoph Kappel
  gravity :center
164 64 Christoph Kappel
end
165 64 Christoph Kappel
</code></pre>
166 64 Christoph Kappel
167 64 Christoph Kappel
h3. Match
168 64 Christoph Kappel
169 64 Christoph Kappel
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]].
170 64 Christoph Kappel
171 64 Christoph Kappel
h4. Regular expression
172 64 Christoph Kappel
173 64 Christoph Kappel
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]].
174 64 Christoph Kappel
175 64 Christoph Kappel
h4. Selector
176 64 Christoph Kappel
177 64 Christoph Kappel
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]].
178 64 Christoph Kappel
179 64 Christoph Kappel
Every [[Tagging#Selector|selector]] consists of a type and a value:
180 64 Christoph Kappel
181 64 Christoph Kappel
<pre><code class="ruby">
182 64 Christoph Kappel
tag "example" do
183 64 Christoph Kappel
  match type: value
184 64 Christoph Kappel
end
185 64 Christoph Kappel
</code></pre>
186 64 Christoph Kappel
187 64 Christoph Kappel
Following types exist:
188 64 Christoph Kappel
189 64 Christoph Kappel
| *&#58;name*     | Match the [[Client#WM_NAME|window name]]           |
190 64 Christoph Kappel
| *&#58;instance* | Match the [[Client#WM_CLASS|window instance name]] |
191 64 Christoph Kappel
| *&#58;class*    | Match the [[Client#WM_CLASS|window class name]]    |
192 64 Christoph Kappel
| *&#58;role*     | Match the [[Client#WM_ROLE|window role]]           |
193 64 Christoph Kappel
| *&#58;type*     | Match the [[Clients#Types|window type]]            |
194 64 Christoph Kappel
195 64 Christoph Kappel
{{needs(r2830)}}
196 64 Christoph Kappel
197 64 Christoph Kappel
h4. Boolean logic
198 64 Christoph Kappel
199 64 Christoph Kappel
"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.
200 64 Christoph Kappel
201 64 Christoph Kappel
h5. AND
202 64 Christoph Kappel
203 64 Christoph Kappel
All [[Tagging#Selector|selector]] are required in order for this [[Tagging|tag]] to be applied.
204 64 Christoph Kappel
205 64 Christoph Kappel
<pre><code class="ruby">
206 64 Christoph Kappel
tag "AND" do
207 64 Christoph Kappel
  match instance: "xterm", instance: "urxvt"
208 64 Christoph Kappel
end
209 64 Christoph Kappel
</code></pre>
210 64 Christoph Kappel
211 64 Christoph Kappel
h5. OR
212 64 Christoph Kappel
213 64 Christoph Kappel
Only one matching [[Tagging#Selector|selector]] is required in order for this [[Tagging|tag]] to be applied.
214 64 Christoph Kappel
215 64 Christoph Kappel
<pre><code class="ruby">
216 64 Christoph Kappel
tag "OR" do
217 64 Christoph Kappel
  match "xterm"
218 64 Christoph Kappel
  match "urxvt"
219 64 Christoph Kappel
end
220 64 Christoph Kappel
</code></pre>
221 64 Christoph Kappel
222 64 Christoph Kappel
{{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.)}}
223 64 Christoph Kappel
224 64 Christoph Kappel
Please also check the "How do I tag console based programs?":http://subforge.org/ezfaq/show/subtle?faq_id=15 FAQ entry.
225 64 Christoph Kappel
226 64 Christoph Kappel
{{needs(r3209)}}
227 64 Christoph Kappel
228 64 Christoph Kappel
h3. On_match
229 64 Christoph Kappel
230 64 Christoph Kappel
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]].
231 64 Christoph Kappel
232 64 Christoph Kappel
<pre><code class="ruby">
233 64 Christoph Kappel
tag "gimp" do
234 64 Christoph Kappel
  match role: "gimp.*"
235 64 Christoph Kappel
236 64 Christoph Kappel
  on_match do |c|
237 64 Christoph Kappel
    c.gravity = ("gimp_" + c.role.split("-")[1]).to_sym
238 64 Christoph Kappel
  end
239 64 Christoph Kappel
end
240 64 Christoph Kappel
</code></pre>
241 64 Christoph Kappel
242 64 Christoph Kappel
h3. Position
243 64 Christoph Kappel
244 64 Christoph Kappel
Similar to the geometry option, set the x/y coordinates of the [[Tagging|tagged]] [[Clients|client]], but +only+ on [[views]] with common [[Tagging|tag]]. 
245 64 Christoph Kappel
246 64 Christoph Kappel
Expected is an "array":http://www.ruby-doc.org/core/classes/Array.html with *x* and *y* values.
247 64 Christoph Kappel
248 64 Christoph Kappel
<pre><code class="ruby">
249 64 Christoph Kappel
tag "position" do
250 64 Christoph Kappel
  match    "xterm"
251 64 Christoph Kappel
  position [ 10, 10 ]
252 64 Christoph Kappel
end
253 64 Christoph Kappel
</code></pre>
254 64 Christoph Kappel
255 64 Christoph Kappel
h3. Type
256 64 Christoph Kappel
257 64 Christoph Kappel
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. 
258 64 Christoph Kappel
259 64 Christoph Kappel
Following types are possible:
260 64 Christoph Kappel
261 64 Christoph Kappel
{{needs(r2905)}}
262 64 Christoph Kappel
263 64 Christoph Kappel
| *&#58;normal* | Treat as [[Clients#Normal|normal window]]                                     |
264 64 Christoph Kappel
| *&#58;desktop* | Treat as [[Clients#Desktop|desktop window]] (__NET_WM_WINDOW_TYPE_DESKTOP_)  |
265 64 Christoph Kappel
| *&#58;dock*    | Treat as [[Clients#Dock|dock window]] (__NET_WM_WINDOW_TYPE_DOCK_)           |
266 64 Christoph Kappel
| *&#58;toolbar* | Treat as [[Clients#Toolbar|toolbar windows]] (__NET_WM_WINDOW_TYPE_TOOLBAR_) |
267 64 Christoph Kappel
| *&#58;splash*  | Treat as [[Clients#splash|splash window]] (__NET_WM_WINDOW_TYPE_SPLASH_)     |
268 64 Christoph Kappel
| *&#58;dialog*  | Treat as [[Clients#Dialog|dialog window]] (__NET_WM_WINDOW_TYPE_DIALOG_)     |
269 64 Christoph Kappel
270 64 Christoph Kappel
<pre><code class="ruby">
271 64 Christoph Kappel
tag "desktop" do
272 64 Christoph Kappel
  match   "xterm"
273 64 Christoph Kappel
  type    :desktop
274 64 Christoph Kappel
end
275 64 Christoph Kappel
</code></pre>
276 64 Christoph Kappel
277 64 Christoph Kappel
h2. Examples
278 64 Christoph Kappel
279 64 Christoph Kappel
<pre><code class="ruby">
280 64 Christoph Kappel
tag "bashrun" do
281 64 Christoph Kappel
  match    "bashrun"
282 64 Christoph Kappel
  geometry [ 50, 1000, 200, 28 ]#
283 64 Christoph Kappel
  stick    true
284 64 Christoph Kappel
  urgent   true
285 64 Christoph Kappel
end
286 64 Christoph Kappel
287 64 Christoph Kappel
tag "browser" do
288 64 Christoph Kappel
  match   "chrom[e|ium]"
289 64 Christoph Kappel
  gravity :center
290 64 Christoph Kappel
end
291 64 Christoph Kappel
</code></pre>