Tyrannical—A simple tag managment engine for Awesome

Description

Shifty was great and served us well since the early days of the Awesome 3.* series, but just as many aged kid TV stars, it has not grown that well. Many of its once unique features are now supported by the default awful.tag engine, adding legacy complexity to the code base and affecting performance.

This is why Tyrannical was created. It is a light rule engine offering pretty much the same rule configuration, but without all the dynamic tag code. Note that dynamic tagging is now supported directly by awesome. Tyrannical support Awesome WM version 3.5 and higher.

Installation

This is how to install Tyrannical

    mkdir -p ~/.config/awesome
    cd ~/.config/awesome
    git clone https://github.com/Elv13/tyrannical.git

Then either use the sample rc.lua or upgrade your existing one.

Examples

Install Xephyr and run the following script

 sh utils/xephyr.sh start

Note: The tyrannical repository must be named awesome-tyrannical for the script to work out of the box.

Also see samples.rc.lua for a sample.

Configuration

If you previously used Shifty, you will feel comfortable using Tyrannical. The only difference is that in Tyrannical class matching is integrated into the tag configuration section. More advanced rules can be created using awful.rules. Again, Tyrannical was not created to duplicate awful, but to make dynamic (and static, as a side effect) tagging configuration easier. This module doesn't require any major initialisation. Compared to shifty, it is much more transparent.

The first modification is to include the module at the top of your rc.lua (after awful.rules = require("awful.rules")):

local tyrannical = require("tyrannical")

Then this section have to be replaced:

-- {{{ Tags
-- Define a tag table which hold all screen tags.
tags = {}
for s = 1, screen.count() do
    -- Each screen has its own tag table.
    tags[s] = awful.tag({ 1, 2, 3, 4, 5, 6, 7, 8, 9 }, s, layouts[1])
end
-- }}}

by:

tyrannical.tags = {
    {
        name        = "Term",                 -- Call the tag "Term"
        init        = true,                   -- Load the tag on startup
        exclusive   = true,                   -- Refuse any other type of clients (by classes)
        screen      = {1,2},                  -- Create this tag on screen 1 and screen 2
        layout      = awful.layout.suit.tile, -- Use the tile layout
        class       = { --Accept the following classes, refuse everything else (because of "exclusive=true")
            "xterm" , "urxvt" , "aterm","URxvt","XTerm","konsole","terminator","gnome-terminal"
        }
    } ,
    {
        name        = "Internet",
        init        = true,
        exclusive   = true,
      --icon        = "~net.png",                 -- Use this icon for the tag (uncomment with a real path)
        screen      = screen.count()>1 and 2 or 1,-- Setup on screen 2 if there is more than 1 screen, else on screen 1
        layout      = awful.layout.suit.max,      -- Use the max layout
        class = {
            "Opera"         , "Firefox"        , "Rekonq"    , "Dillo"        , "Arora",
            "Chromium"      , "nightly"        , "minefield"     }
    } ,
    {
        name = "Files",
        init        = true,
        exclusive   = true,
        screen      = 1,
        layout      = awful.layout.suit.tile,
        exec_once   = {"dolphin"}, --When the tag is accessed for the first time, execute this command
        class  = {
            "Thunar", "Konqueror", "Dolphin", "ark", "Nautilus","emelfm"
        }
    } ,
    {
        name = "Develop",
        init        = true,
        exclusive   = true,
        screen      = 1,
        clone_on    = 2, -- Create a single instance of this tag on screen 1, but also show it on screen 2
                         -- The tag can be used on both screen, but only one at once
        layout      = awful.layout.suit.max                          ,
        class ={ 
            "Kate", "KDevelop", "Codeblocks", "Code::Blocks" , "DDD", "kate4"}
    } ,
    {
        name        = "Doc",
        init        = false, -- This tag wont be created at startup, but will be when one of the
                             -- client in the "class" section will start. It will be created on
                             -- the client startup screen
        exclusive   = true,
        layout      = awful.layout.suit.max,
        class       = {
            "Assistant"     , "Okular"         , "Evince"    , "EPDFviewer"   , "xpdf",
            "Xpdf"          ,                                        }
    } ,
}

-- Ignore the tag "exclusive" property for the following clients (matched by classes)
tyrannical.properties.intrusive = {
    "ksnapshot"     , "pinentry"       , "gtksu"     , "kcalc"        , "xcalc"               ,
    "feh"           , "Gradient editor", "About KDE" , "Paste Special", "Background color"    ,
    "kcolorchooser" , "plasmoidviewer" , "Xephyr"    , "kruler"       , "plasmaengineexplorer",
}

-- Ignore the tiled layout for the matching clients
tyrannical.properties.floating = {
    "MPlayer"      , "pinentry"        , "ksnapshot"  , "pinentry"     , "gtksu"          ,
    "xine"         , "feh"             , "kmix"       , "kcalc"        , "xcalc"          ,
    "yakuake"      , "Select Color$"   , "kruler"     , "kcolorchooser", "Paste Special"  ,
    "New Form"     , "Insert Picture"  , "kcharselect", "mythfrontend" , "plasmoidviewer" 
}

-- Make the matching clients (by classes) on top of the default layout
tyrannical.properties.ontop = {
    "Xephyr"       , "ksnapshot"       , "kruler"
}

-- Force the matching clients (by classes) to be centered on the screen on init
tyrannical.properties.centered = {
    "kcalc"
}

tyrannical.settings.block_children_focus_stealing = true --Block popups ()
tyrannical.settings.group_children = true --Force popups/dialogs to have the same tags as the parent client

Then edit this section to fit your needs.

The available tag properties are:

Property	Description	Type
class	Match these classes to this tag	array of string
clone_on	Create a clone on screen(s)	number or array
exclusive	Allow only client from the "class" attributes	boolean
exec_once	Execute when the tag is first selected	string (command)
force_screen	Force a screen	number
hide	Hide this tag from view	boolean
icon	Tag icon	path
init	Create when awesome launch	boolean
layout	The tag layout	layout
mwfact	Tiled layout master/slave ratio	float(0-1)
ncol	Number of columns	number
nmaster	Number of master clients	number
no_focus_stealing	Do not change focus then a new client is added	boolean
no_focus_stealing_in	Do not select this tag when a new client is added	boolean
no_focus_stealing_out	Do not unselect when a new client is added elsewhere	boolean
screen	Tag screen(s)	number or array
selected	Select when created	boolean
volatile	Destroy when the last client is closed	boolean
fallback	Use this tag for unmatched clients	boolean
locked	Do not add any more clients to this tag	boolean
max_clients	Maximum number of clients before creating a new tag	number

The available client properties are:

Property	Description	Type
above	Display above other clients	boolean
below	Display below other clients	boolean
border_color	Change client default border color*	string
border_width	Change the client border width	number
centered	Center the client on the screen at launch	boolean
floating	Make the client floating or insert into layout	boolean
focusable	Allow focus	boolean
fullscreen	Cover the whole screen	boolean
hidden	Hide this client (minimize)	boolean
intrusive	Ignore tag "exclusive" property	boolean
maximized_horizontal	Cover all horizontal space	boolean
maximized_vertical	Cover all vertical space	boolean
ontop	Display on top of the normal layout layer	boolean
skip_taskbar	Do not add to tasklist	boolean
sticky	Display in all tags	boolean

*Need default rc.lua modifications in the "client.connect_signal('focus')" section

The available global settings are:

Property	Description	Type
block_children_focus_stealing	Prevent popups from stealing focus	boolean
default_layout	The default layout for tags	layout
group_children	Add dialogs to the same tags as their parent client	boolean
mwfact	The default master/slave ratio	float (0-1)
force_odd_as_intrusive	Make all non-normal (dock, splash) intrusive	boolean
no_focus_stealing_out	Do not unselect tags when a new client is added	boolean

It's worth noting that some settings like mwfact and default_layout should be set before the tag arrow. Otherwise they wont take effect at startup.

---

FAQ

Is it possible to add, remove and move tags?

Yes, this feature is now part of awful. It does not require an external module anymore. Awful's dynamic tag implementation is compatible with Tyrannical. See the API and this user contribution

How do I get a client class?

From a terminal, execute xprop, then click on an instance of that client. There will be a "CLASS" line with one or more class. Always pick the second one, Tyrannical is not case sensitive.

Is it possible to have relative indexes (position) for tags?

Tyrannical shares awful's tag list. It does not keep its own indexes since this would make it harder to implement this feature in the core. Given that, this feature is outside the project scope. That being said, nothing prevents you from adding a "position" property to the tag. Once this is done, edit the default rc.lua keybindings to find the position by looping the tags. In case the tag is not yet created, you can access it with tyrannical.tags_by_name["your tag name"] array. This array is automatically generated. You can then add it using

name"].name,tyrannical.tags_by_name["your tag name"])```. Tyrannical's purpose
is not to duplicate or change ```awful.tag``` behavior, it is simply a
configuration wrapper.

#### What is Tyrannical license?

Tyrannical is licensed under the [2 clause BSD](http://opensource.org/licenses/BSD-2-Clause)