1 ---------------------------------------------------------------------------
2 -- @author Julien Danjou <julien@danjou.info>
3 -- @copyright 2008 Julien Danjou
4 -- @release @AWESOME_VERSION@
5 ---------------------------------------------------------------------------
7 -- Grab environment we need
8 local util
= require("awful.util")
9 local tostring = tostring
13 local setmetatable
= setmetatable
23 --- Useful functions for tag manipulation.
25 local tag = { mt
= {} }
30 data
.tags
= setmetatable({}, { __mode
= 'k' })
34 tag.history
.limit
= 20
36 --- Move a tag to an absolute position in the screen[]:tags() table.
37 -- @param new_index Integer absolute position in the table to insert.
38 -- @param target_tag The tag that should be moved. If null, the currently
39 -- selected tag is used.
40 function tag.move(new_index
, target_tag
)
41 local target_tag
= target_tag
or tag.selected()
42 local scr
= tag.getscreen(target_tag
)
43 local tmp_tags
= tag.gettags(scr
)
45 if (not new_index
) or (new_index
< 1) or (new_index
> #tmp_tags
) then
49 for i
, t
in ipairs(tmp_tags
) do
50 if t
== target_tag
then
51 table.remove(tmp_tags
, i
)
56 table.insert(tmp_tags
, new_index
, target_tag
)
58 for _
, tmp_tag
in ipairs(tmp_tags
) do
59 tag.setscreen(tmp_tag
, scr
)
64 -- @param name The tag name, a string
65 -- @param props The tags properties, a table
66 -- @return The created tag
67 function tag.add(name
, props
)
68 local properties
= props
or {}
69 local newtag = capi
.tag{ name
= name
, activated
= true }
70 properties
.screen
= properties
.screen
or capi
.mouse
.screen
72 for k
, v
in pairs(properties
) do
73 tag.setproperty(newtag, k
, v
)
79 --- Create a set of tags and attach it to a screen.
80 -- @param names The tag name, in a table
81 -- @param screen The tag screen, or 1 if not set.
82 -- @param layout The layout or layout table to set for this tags by default.
83 -- @return A table with all created tags.
84 function tag.new(names
, screen
, layout
)
85 local screen
= screen
or 1
87 for id
, name
in ipairs(names
) do
88 table.insert(tags
, id
, tag.add(name
, {screen
= screen
,
89 layout
= (layout
and layout
[id
]) or
91 -- Select the first tag.
93 tags
[id
].selected
= true
100 --- Find a suitable fallback tag.
101 -- @param screen The screen number to look for a tag on. [mouse.screen]
102 -- @param invalids A table of tags we consider unacceptable. [selectedlist(scr)]
103 function tag.find_fallback(screen
, invalids
)
104 local scr
= screen
or capi
.mouse
.screen
105 local t
= invalids
or tag.selectedlist(scr
)
107 for _
, v
in pairs(tag.gettags(scr
)) do
108 if not util
.table.hasitem(t
, v
) then return v
end
113 -- @param target_tag Optional tag object to delete. [selected()]
114 -- @param fallback_tag Tag to assign stickied tags to. [~selected()]
115 -- @return Returns true if the tag is successfully deleted, nil otherwise.
116 -- If there are no clients exclusively on this tag then delete it. Any
117 -- stickied clients are assigned to the optional 'fallback_tag'.
118 -- If after deleting the tag there is no selected tag, try and restore from
119 -- history or select the first tag on the screen.
120 function tag.delete(target_tag
, fallback_tag
)
121 -- abort if no tag is passed or currently selected
122 local target_tag
= target_tag
or tag.selected()
123 if target_tag
== nil then return end
125 local target_scr
= tag.getscreen(target_tag
)
126 local ntags
= #tag.gettags(target_scr
)
128 -- We can't use the target tag as a fallback.
129 local fallback_tag
= fallback_tag
130 if fallback_tag
== target_tag
then return end
132 -- No fallback_tag provided, try and get one.
133 if fallback_tag
== nil then
134 fallback_tag
= tag.find_fallback(target_scr
, {target_tag
})
137 -- Abort if we would have un-tagged clients.
138 local clients
= target_tag
:clients()
139 if ( #clients
> 0 and ntags
<= 1 ) or fallback_tag
== nil then return end
141 -- Move the clients we can off of this tag.
142 for _
, c
in pairs(clients
) do
144 -- If a client has only this tag, or stickied clients with
145 -- nowhere to go, abort.
146 if (not c
.sticky
and #c
:tags() == 1) or
147 (c
.sticky
and fallback_tag
== nil) then
150 c
:tags({fallback_tag
})
155 data
.tags
[target_tag
].screen
= nil
157 -- If no tags are visible, try and view one.
158 if tag.selected(target_scr
) == nil and ntags
> 0 then
159 tag.history
.restore()
160 if tag.selected(target_scr
) == nil then
161 tag.gettags(target_scr
)[1].selected
= true
168 --- Update the tag history.
169 -- @param obj Screen object.
170 function tag.history
.update(obj
)
172 local curtags
= tag.selectedlist(s
)
173 -- create history table
174 if not data
.history
[s
] then
177 if data
.history
[s
].current
then
178 -- Check that the list is not identical
179 local identical
= true
180 for idx
, _tag
in ipairs(data
.history
[s
].current
) do
181 if curtags
[idx
] ~= _tag
then
187 -- Do not update history the table are identical
188 if identical
then return end
192 if #data
.history
[s
] >= tag.history
.limit
then
193 for i
= tag.history
.limit
, #data
.history
[s
] do
194 data
.history
[s
][i
] = nil
199 -- store previously selected tags in the history table
200 table.insert(data
.history
[s
], 1, data
.history
[s
].current
)
201 data
.history
[s
].previous
= data
.history
[s
][1]
202 -- store currently selected tags
203 data
.history
[s
].current
= setmetatable(curtags
, { __mode
= 'v' })
206 --- Revert tag history.
207 -- @param screen The screen number.
208 -- @param idx Index in history. Defaults to "previous" which is a special index
209 -- toggling between last two selected sets of tags. Number (eg 1) will go back
210 -- to the given index in history.
211 function tag.history
.restore(screen
, idx
)
212 local s
= screen
or capi
.mouse
.screen
213 local i
= idx
or "previous"
214 local sel
= tag.selectedlist(s
)
215 -- do nothing if history empty
216 if not data
.history
[s
] or not data
.history
[s
][i
] then return end
217 -- if all tags been deleted, try next entry
218 if #data
.history
[s
][i
] == 0 then
219 if i
== "previous" then i
= 0 end
220 tag.history
.restore(s
, i
+ 1)
225 -- select tags from the history entry
226 for _
, t
in ipairs(data
.history
[s
][i
]) do
229 -- update currently selected tags table
230 data
.history
[s
].current
= data
.history
[s
][i
]
231 -- store previously selected tags
232 data
.history
[s
].previous
= setmetatable(sel
, { __mode
= 'v' })
233 -- remove the reverted history entry
234 if i
~= "previous" then table.remove(data
.history
[s
], i
) end
237 --- Get a list of all tags on a screen
238 -- @param s Screen number
239 -- @return A table with all available tags
240 function tag.gettags(s
)
242 for i
, t
in ipairs(root
.tags()) do
243 if tag.getscreen(t
) == s
then
244 table.insert(tags
, t
)
250 --- Set a tag's screen
251 -- @param t tag object
252 -- @param s Screen number
253 function tag.setscreen(t
, s
)
254 tag.setproperty(t
, "screen", s
)
257 --- Get a tag's screen
258 -- @param t tag object
259 -- @return Screen number
260 function tag.getscreen(t
)
261 return tag.getproperty(t
, "screen")
264 --- Return a table with all visible tags
265 -- @param s Screen number.
266 -- @return A table with all selected tags.
267 function tag.selectedlist(s
)
268 local screen
= s
or capi
.mouse
.screen
269 local tags
= tag.gettags(screen
)
271 for i
, t
in pairs(tags
) do
273 vtags
[#vtags
+ 1] = t
279 --- Return only the first visible tag.
280 -- @param s Screen number.
281 function tag.selected(s
)
282 return tag.selectedlist(s
)[1]
285 --- Set master width factor.
286 -- @param mwfact Master width factor.
287 -- @param t The tag to modify, if null tag.selected() is used.
288 function tag.setmwfact(mwfact
, t
)
289 local t
= t
or tag.selected()
290 if mwfact
>= 0 and mwfact
<= 1 then
291 tag.setproperty(t
, "mwfact", mwfact
)
295 --- Increase master width factor.
296 -- @param add Value to add to master width factor.
297 -- @param t The tag to modify, if null tag.selected() is used.
298 function tag.incmwfact(add
, t
)
299 tag.setmwfact(tag.getmwfact(t
) + add
, t
)
302 --- Get master width factor.
303 -- @param t Optional tag.
304 function tag.getmwfact(t
)
305 local t
= t
or tag.selected()
306 return tag.getproperty(t
, "mwfact") or 0.5
309 --- Set the number of master windows.
310 -- @param nmaster The number of master windows.
311 -- @param t Optional tag.
312 function tag.setnmaster(nmaster
, t
)
313 local t
= t
or tag.selected()
315 tag.setproperty(t
, "nmaster", nmaster
)
319 --- Get the number of master windows.
320 -- @param t Optional tag.
321 function tag.getnmaster(t
)
322 local t
= t
or tag.selected()
323 return tag.getproperty(t
, "nmaster") or 1
326 --- Increase the number of master windows.
327 -- @param add Value to add to number of master windows.
328 -- @param t The tag to modify, if null tag.selected() is used.
329 function tag.incnmaster(add
, t
)
330 tag.setnmaster(tag.getnmaster(t
) + add
, t
)
335 -- @param icon the icon to set, either path or image object
336 -- @param _tag the tag
337 function tag.seticon(icon
, _tag
)
338 local _tag
= _tag
or tag.selected()
339 tag.setproperty(_tag
, "icon", icon
)
343 -- @param _tag the tag
344 function tag.geticon(_tag
)
345 local _tag
= _tag
or tag.selected()
346 return tag.getproperty(_tag
, "icon")
349 --- Set number of column windows.
350 -- @param ncol The number of column.
351 -- @param t The tag to modify, if null tag.selected() is used.
352 function tag.setncol(ncol
, t
)
353 local t
= t
or tag.selected()
355 tag.setproperty(t
, "ncol", ncol
)
359 --- Get number of column windows.
360 -- @param t Optional tag.
361 function tag.getncol(t
)
362 local t
= t
or tag.selected()
363 return tag.getproperty(t
, "ncol") or 1
366 --- Increase number of column windows.
367 -- @param add Value to add to number of column windows.
368 -- @param t The tag to modify, if null tag.selected() is used.
369 function tag.incncol(add
, t
)
370 tag.setncol(tag.getncol(t
) + add
, t
)
374 -- @param Optional screen number.
375 function tag.viewnone(screen
)
376 local tags
= tag.gettags(screen
or capi
.mouse
.screen
)
377 for i
, t
in pairs(tags
) do
382 --- View a tag by its taglist index.
383 -- @param i The relative index to see.
384 -- @param screen Optional screen number.
385 function tag.viewidx(i
, screen
)
386 local screen
= screen
or capi
.mouse
.screen
387 local tags
= tag.gettags(screen
)
389 for k
, t
in ipairs(tags
) do
390 if not tag.getproperty(t
, "hide") then
391 table.insert(showntags
, t
)
394 local sel
= tag.selected(screen
)
396 for k
, t
in ipairs(showntags
) do
398 showntags
[util
.cycle(#showntags
, k
+ i
)].selected
= true
401 capi
.screen
[screen
]:emit_signal("tag::history::update")
404 --- Get a tag's index in the gettags() table.
405 -- @param query_tag The tag object to find. [selected()]
406 -- @return The index of the tag, nil if the tag is not found.
407 function tag.getidx(query_tag
)
408 local query_tag
= query_tag
or tag.selected()
409 if query_tag
== nil then return end
411 for i
, t
in ipairs(tag.gettags(tag.getscreen(query_tag
))) do
412 if t
== query_tag
then
418 --- View next tag. This is the same as tag.viewidx(1).
419 -- @param screen The screen number.
420 function tag.viewnext(screen
)
421 return tag.viewidx(1, screen
)
424 --- View previous tag. This is the same a tag.viewidx(-1).
425 -- @param screen The screen number.
426 function tag.viewprev(screen
)
427 return tag.viewidx(-1, screen
)
431 -- @param t The tag object.
432 function tag.viewonly(t
)
433 local tags
= tag.gettags(tag.getscreen(t
))
434 -- First, untag everyone except the viewed tag.
435 for _
, _tag
in pairs(tags
) do
437 _tag
.selected
= false
440 -- Then, set this one to selected.
441 -- We need to do that in 2 operations so we avoid flickering and several tag
442 -- selected at the same time.
444 capi
.screen
[tag.getscreen(t
)]:emit_signal("tag::history::update")
447 --- View only a set of tags.
448 -- @param tags A table with tags to view only.
449 -- @param screen Optional screen number of the tags.
450 function tag.viewmore(tags
, screen
)
451 local screen_tags
= tag.gettags(screen
or capi
.mouse
.screen
)
452 for _
, _tag
in ipairs(screen_tags
) do
453 if not util
.table.hasitem(tags
, _tag
) then
454 _tag
.selected
= false
457 for _
, _tag
in ipairs(tags
) do
460 capi
.screen
[screen
]:emit_signal("tag::history::update")
463 --- Toggle selection of a tag
464 -- @param tag Tag to be toggled
465 function tag.viewtoggle(t
)
466 t
.selected
= not t
.selected
467 capi
.screen
[tag.getscreen(t
)]:emit_signal("tag::history::update")
470 --- Get tag data table.
471 -- @param tag The Tag.
472 -- @return The data table.
473 function tag.getdata(_tag
)
474 return data
.tags
[_tag
]
477 --- Get a tag property.
478 -- @param _tag The tag.
479 -- @param prop The property name.
480 -- @return The property.
481 function tag.getproperty(_tag
, prop
)
482 if data
.tags
[_tag
] then
483 return data
.tags
[_tag
][prop
]
487 --- Set a tag property.
488 -- This properties are internal to awful. Some are used to draw taglist, or to
489 -- handle layout, etc.
490 -- @param _tag The tag.
491 -- @param prop The property name.
492 -- @param value The value.
493 function tag.setproperty(_tag
, prop
, value
)
494 if not data
.tags
[_tag
] then
497 data
.tags
[_tag
][prop
] = value
498 _tag
:emit_signal("property::" .. prop
)
501 --- Tag a client with the set of current tags.
502 -- @param c The client to tag.
503 -- @param startup Optional: don't do anything if true.
504 function tag.withcurrent(c
, startup
)
505 if startup
~= true then
507 for k
, t
in ipairs(c
:tags()) do
508 if tag.getscreen(t
) == c
.screen
then
509 table.insert(tags
, t
)
513 tags
= tag.selectedlist(c
.screen
)
519 local function attached_connect_signal_screen(screen
, sig
, func
)
520 capi
.tag.connect_signal(sig
, function(_tag
, ...)
521 if tag.getscreen(_tag
) == screen
then
527 --- Add a signal to all attached tag and all tag that will be attached in the
528 -- future. When a tag is detach from the screen, its signal is removed.
529 -- @param screen The screen concerned, or all if nil.
530 function tag.attached_connect_signal(screen
, ...)
532 attached_connect_signal_screen(screen
, ...)
534 capi
.tag.connect_signal(...)
538 -- Register standards signals
539 capi
.client
.connect_signal("manage", function(c
, startup
)
540 -- If we are not managing this application at startup,
541 -- move it to the screen where the mouse is.
542 -- We only do it for "normal" windows (i.e. no dock, etc).
543 if not startup
and c
.type ~= "desktop" and c
.type ~= "dock" then
544 if c
.transient_for
then
545 c
.screen
= c
.transient_for
.screen
547 c
:tags(c
.transient_for
:tags())
550 c
.screen
= capi
.mouse
.screen
553 c
:connect_signal("property::screen", tag.withcurrent
)
556 capi
.client
.connect_signal("manage", tag.withcurrent
)
558 capi
.tag.add_signal("property::hide")
559 capi
.tag.add_signal("property::icon")
560 capi
.tag.add_signal("property::layout")
561 capi
.tag.add_signal("property::mwfact")
562 capi
.tag.add_signal("property::ncol")
563 capi
.tag.add_signal("property::nmaster")
564 capi
.tag.add_signal("property::windowfact")
565 capi
.tag.add_signal("property::screen")
567 for s
= 1, capi
.screen
.count() do
568 capi
.screen
[s
]:add_signal("tag::history::update")
569 capi
.screen
[s
]:connect_signal("tag::history::update", tag.history
.update
)
572 function tag.mt
:__call(...)
576 return setmetatable(tag, tag.mt
)
578 -- vim: filetype=lua:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80