From 775e634e13ae02cc64d261630544c1d5c43e72d3 Mon Sep 17 00:00:00 2001 From: Julien Danjou Date: Wed, 25 Jun 2008 19:28:47 +0200 Subject: [PATCH] tabulous: add documentation, cleanup Signed-off-by: Julien Danjou --- lib/tabulous.lua | 168 +++++++++++++++++++++++++---------------------- 1 file changed, 89 insertions(+), 79 deletions(-) diff --git a/lib/tabulous.lua b/lib/tabulous.lua index f930b94c..42e72013 100644 --- a/lib/tabulous.lua +++ b/lib/tabulous.lua @@ -22,13 +22,13 @@ local client = client local table = table local pairs = pairs local awful = awful -local print = print -- Reset env setfenv(1, P) -local tabbed = {} +tabbed = {} +-- Hook creation awful.hooks.userhook_create('tabbed') awful.hooks.userhook_create('untabbed') awful.hooks.userhook_create('tabdisplay') @@ -38,18 +38,22 @@ awful.hooks.userhook_create('tabhide') -- Functions -- --------------- --- Find the key in a table -local function findkey(table, cl) - for i, c in pairs(table) do - if c == cl then - return i +--- Find a key in a table. +-- @param table The table to look into +-- @param value The value to find. +-- @return The key or nil if not found. +function P.findkey(table, value) + for k, v in pairs(table) do + if v == value then + return k end end - return nil end --- Swap which tab is displayed -local function client_display(tabindex, cl) +--- Swap and select which client in tab is displayed. +-- @param tabindex The tab index. +-- @param cl The client to show. +function P.display(tabindex, cl) local p = tabbed[tabindex][1] if cl and p ~= cl then @@ -65,19 +69,24 @@ local function client_display(tabindex, cl) end end --- Check if the client is in the given tabindex -local function client_in_tabindex(tabindex, cl) +--- Check if the client is in the given tabindex. +-- @param tabindex The tab index. +-- @param cl The client +-- @return The key. +function P.tabindex_check(tabindex, cl) local c = cl or client.focus_get() - return findkey(tabbed[tabindex], c) + return P.findkey(tabbed[tabindex], c) end --- Find the tab index or return nil if not tabbed -local function client_find_tabindex(cl) +--- Find the tab index or return nil if not tabbed. +-- @param cl The client to search. +-- @return The tab index. +function P.tabindex_get(cl) local c = cl or client.focus_get() for tabindex, tabdisplay in pairs(tabbed) do -- Loop through all tab displays - local me = client_in_tabindex(tabindex, c) + local me = P.tabindex_check(tabindex, c) if me ~= nil then return tabindex @@ -87,29 +96,39 @@ local function client_find_tabindex(cl) return nil end --- Get all clients on a tabbed display -local function client_get_clients(tabindex) +--- Get all clients on a tabbed display. +-- @param tabindex The tab index. +-- @return All tabbed clients. +function P.clients_get(tabindex) if tabbed[tabindex] == nil then return nil end return tabbed[tabindex][2] end --- Get the displayed client on a tabbed display -local function client_get_displayed(tabindex) +--- Get the displayed client on a tabbed display. +-- @param tabindex The tab index. +-- @return The displayed client. +function P.displayed_get(tabindex) if tabbed[tabindex] == nil then return nil end return tabbed[tabindex][1] end --- Get a client by tab number -local function client_get_position(tabindex, pos) +--- Get a client by tab number. +-- @param tabindex The tab index. +-- @param pos The position in the tab. +-- @return The client at the given position. +function P.position_get(tabindex, pos) if tabbed[tabindex] == nil then return nil end return tabbed[tabindex][2][pos] end --- Get the next client in a tabdisplay -local function client_next(tabindex, cl) +--- Get the next client in a tab display. +-- @param tabindex The tab index. +-- @param cl The current client. +-- @return The next client. +function P.next(tabindex, cl) local c = cl or tabbed[tabindex][1] - local i = findkey(tabbed[tabindex][2], c) + local i = P.findkey(tabbed[tabindex][2], c) if i == nil then return nil @@ -117,16 +136,19 @@ local function client_next(tabindex, cl) if tabbed[tabindex][2][i+1] == nil then return tabbed[tabindex][2][1] - else - return tabbed[tabindex][2][i+1] end + + return tabbed[tabindex][2][i + 1] end --- Get the previous client in a tabdisplay -local function client_prev(tabindex, cl) +--- Get the previous client in a tabdisplay +-- @param tabindex The tab index. +-- @param cl The current client. +-- @return The previous client. +function P.prev(tabindex, cl) local c = cl or tabbed[tabindex][1] - local i = findkey(tabbed[tabindex][2], c) + local i = P.findkey(tabbed[tabindex][2], c) if i == nil then return nil @@ -134,21 +156,24 @@ local function client_prev(tabindex, cl) if tabbed[tabindex][2][i-1] == nil then return tabbed[tabindex][2][table.maxn(tabbed[tabindex][2])] - else - return tabbed[tabindex][2][i-1] end + + return tabbed[tabindex][2][i - 1] end --- Remove a client from a tabbed display -local function client_untab(cl) +--- Remove a client from a tabbed display. +-- @param cl The client to remove. +-- @return True if the client has been untabbed. +function P.untab(cl) local c = cl or client.focus_get() - local tabindex = client_find_tabindex(c) + local tabindex = P.tabindex_get(c) + if tabindex == nil then return false end - local cindex = findkey(tabbed[tabindex][2], c) + local cindex = P.findkey(tabbed[tabindex][2], c) if tabbed[tabindex][1] == c then - client_display(tabindex, client_next(tabindex, c)) + P.display(tabindex, P.next(tabindex, c)) end table.remove(tabbed[tabindex][2], cindex) @@ -162,8 +187,9 @@ local function client_untab(cl) awful.hooks.userhook_call('untabbed', {c}) end --- Untab all clients in a tabbed display -local function client_untab_all(tabindex) +--- Untab all clients in a tabbed display. +-- @param tabindex The tab index. +function P.untab_all(tabindex) for i,c in pairs(tabbed[tabindex][2]) do c:hide(false) awful.hooks.userhook_call('untabbed', {c}) @@ -174,85 +200,69 @@ local function client_untab_all(tabindex) end end --- Create a new tabbed display with client as the master -local function client_tab_create(cl) +--- Create a new tabbed display with client as the master. +-- @param cl The client to set into the tab, focused one otherwise. +-- @return The created tab index. +function P.tab_create(cl) local c = cl or client.focus_get() + if not c then return end + table.insert(tabbed, { - c, -- Window currently being displayed + c, -- Window currently being displayed { c } -- List of windows in tabbed display }) awful.hooks.userhook_call('tabbed', {c}) - return client_find_tabindex(c) + return P.tabindex_get(c) end --- Add a client to a tabbed display -local function client_tab(tabindex, cl) +--- Add a client to a tabbed display. +-- @param tabindex The tab index. +-- @param cl The client to add, or the focused one otherwise. +function P.tab(tabindex, cl) local c = cl or client.focus_get() if tabbed[tabindex] ~= nil then - local x = client_find_tabindex(c) + local x = P.tabindex_get(c) if x == nil then -- Add untabbed client to tabindex table.insert(tabbed[tabindex][2], c) - client_display(tabindex, c) + P.display(tabindex, c) awful.hooks.userhook_call('tabbed', {c}) elseif x ~= tabindex then -- Merge two tabbed views local cc = tabbed[tabindex][1] - local clients = client_get_clients(x) - client_untab_all(x) + local clients = P.clients_get(x) + P.untab_all(x) - tabindex = client_find_tabindex(cc) + tabindex = P.tabindex_get(cc) for i,b in pairs(clients) do - client_tab(tabindex, b) + P.tab(tabindex, b) end end end end --- Start autotabbing, this automatically --- tabs new clients when the current client --- is tabbed -local function autotab_start() +--- Start autotabbing, this automatically tabs new clients when the current +-- client is tabbed. +function P.autotab_start() awful.hooks.manage(function (c) local sel = client.focus_get() - local index = client_find_tabindex(sel) + local index = P.tabindex_get(sel) if index ~= nil then -- Currently focussed client is tabbed, -- add the new window to the tabbed display - client_tab(index, c) + P.tab(index, c) end end) end -- Set up hook so we don't leave lost hidden clients -awful.hooks.unmanage(function (c) client_untab(c) end) - -P.findkey = findkey -P.display = client_display -P.tabindex_check = client_in_tabindex -P.tabindex_get = client_find_tabindex - -P.tab_create = client_tab_create -P.tab = client_tab -P.untab = client_untab -P.untab_all = client_untab_all - -P.next = client_next -P.prev = client_prev - -P.clients_get = client_get_clients -P.displayed_get = client_get_displayed -P.position_get = client_get_position - -P.autotab_start = autotab_start - -P.tabbed = tabbed +awful.hooks.unmanage(function (c) P.untab(c) end) return P