Page 1 of 2 12 LastLast
Results 1 to 10 of 15

Thread: HOWTO: write an awesome 3 configuration file

  1. #1
    Join Date
    Jul 2006
    Location
    Marlborough, UK
    Beans
    519
    Distro
    Ubuntu 10.04 Lucid Lynx

    HOWTO: write an awesome 3 configuration file

    This howto aims to cover the basics of writing an awesome 3 configuration file in simple lua code, based on the example rc file. IT DOES NOT COVER INSTALLING, as awesome 3 is still in development (the rc has only just been released), and I'm running archlinux atm. When awesome 3 has been released, and I've set up my ubuntu machine (I need one for some work), I'll redo my old awesome howto to cover installing awesome 3.

    This guide also assumes some knowledge of previous awesome versions. It is in essence the few changes I made to convert my old awesomerc to the new lua syntax.

    Some info on this guide's syntax:
    1. Bold is generally important, or the start of a new step.
    2. Italic is code outside a "code" block.
    3. Blocked code is either terminal commands, or an extended rc file section.

    Contents
    1. Set up
    2. Open the rc file
    3. Variables
    4. "Floatings"
    5. Appearance
    6. Tags
    7. Iconboxes
    8. Widgets
    9. Statusbars and showing widgets
    10. Keybindings
    11. Getting programs to open where you want them
    12. Links


    THE GUIDE
    1. Firstly, make sure you have wicked installed. This is what we will be using for some of the widgets you may currently use. If you use conky-cli for all your widgets, don't worry about this. I don't, and so I needed wicked.

    Start out by copying the example file to your home directory. On my system this was achieved with:
    Code:
    cd ~
    mkdir -p .config/awesome
    cp /etc/xdg/awesome/rc.lua .config/awesome/rc.lua
    This cd's to the home directory, creates the hidden config directory, and copies the example file.

    2. Open this file with your favourite editor, however you like. The first thing to do is to include the wicked library right at the top.
    Add require("wicked") to the section at the top, under awful and tabulous.

    3. Now add some variables to make things easier. Under "variable definitions" I added:
    Code:
    terminal = "urxvt"
    browser = "firefox3"
    colorlight = "#4b7885"
    colordark = "#223b56"
    In the case of terminal, it was changed from xterm. The colours are simply how I do my themes - a light colour and a dark colour on a black background, with a cool wallpaper. If you want more/less colours, or no variables for the here at all, that's cool.

    4. The next thing to note is the floatings section. Programs added here are launched (generally, although at time of writing gedit is coming up tiled. hmmm.) floating on all tags. Things you want to appear on top of terminals/browser windows/etc on the tag you're working on are good things to add, just like the 2 examples mplayer and pinentry. I added gedit, and only that.

    5. The Color and Appearance settings are what used to be the style section in the old rc file. Adjust as appropriate.

    6. Tags is the next section. This is very important. If you read through this section in the rc file, you'll see that by default awesome gets the number of attached monitors (screens), and adds 9 tags to them. I changed this in my file to what I used to have in awesome 2.3 - 4 tags with names:
    Code:
    term = tag({ name = 'term', layout = 'tile' })
    term.screen = 1
    term.selected = true
    net = tag({ name = 'net', layout = 'max' })
    net.screen = 1
    main = tag({ name = 'main', layout = 'max' })
    main.screen = 1
    float = tag({ name = 'float', layout = 'floating' })
    float.screen = 1
    These are written in the form:
    internalname = tag ({ name = "displayedname", layout = "layout" })
    Where internalname is the name for the tag when referenced in the rc file, and displayedname is the name shown on the screen. Layout is one of the layouts described in the section near the top of the file, just as in 2.3.
    With all of the tags you must add them to a screen (term.screen = 1), and you must select one to start on. You should also note that screens start from 1, not 0.

    7. Iconboxes are accomplished as follows:
    Code:
    myiconbox = widget({ type = "textbox", name = "myiconbox", align = "left" })
    myiconbox.text = "<bg image=\"/full/path/to/icon\" resize=\"true\"/>"
    8. You can leave the next few sections as they are, with the exception of maybe removing the awesome version textbox. We'll create our own.
    These go like this:
    Code:
    internalname = widget ({ type = "textbox", name = "displayedname", align = "left/right" })
    internalname.text = "some text"
    This is where wicked comes in - it has some very useful built-in status functions designed for awesome. The ones I use are:
    Code:
    wicked.register(rootbox, 'fs', '  ${/ usep}%  ', 30)
    wicked.register(homebox, 'fs', '  ${/home usep}%  ', 30)
    wicked.register(mpdbox, 'mpd', '  $1  ')
    wicked.register(clockbox, 'date', '  %H:%M  ')
    wicked.register(linkbox, 'net', '  ${wlan0 rx} // ${wlan0 tx}  ')
    These give me the used disk space as a percentage, the current mpd state, the time, and the up/down speeds of my network connection.
    The other boxes I have run os functions to display things like battery status and connected network. These use wicked's built in capability to call os functions, and allow me to get rid of the status script that I used in 2.3. The code for this is as follows:
    Code:
    wicked.register(internalname, 'function', function (widget, args)
       local filedescriptor = io.popen('os commmand')
       local value = filedescriptor:read()
       filedescriptor:close()
       return value
    end, timebetweenupdates)
    For more info on wicked have a look here.
    See my attached rc file at the end for the 2 I use.

    9. Once we've created our widgets, we need to create a statusbar or two, and add the widgets to them. I use 2; a top one for tags, widgets, and other things; and a bottom one for the tasklist and systemtray. If you look at the example rc file which you copied, it probably does something in a for loop to add a statusbar to each screen. I only use 1 monitor, so I changed it to this:
    Code:
    mystatusbartop = statusbar({ position = "top", name = "statustop", fg = fg_normal, bg = bg_normal })
    mystatusbarbtm = statusbar({ position = "bottom", name = "statusbottom", fg = fg_normal, bg = bg_normal })
    I then added all my widgets with the simple code (for each one)
    Code:
    mystatusbarname:widget_add(internalname)
    Don't forget to put the statusbar onto a screen with mystatusbarname.screen = 1. Also don't forget that the tasklist, taglist, systemtray are all widgets, and needed to be added as such.


    10. KEYBINDINGS. Now the fun part you've all been waiting for. Keybindings in awesome 3 are nice and easy once you know how. Because you (possibly/probably) changed the tag names, you'll need to redo the mod4 + number hotkeys. These are the ones that let you use the numbers to refer to tags, allowing you to view/toggle/move clients and tags. There are 4 commands relevant for each tag - you can simply read them from the example file (inside the for loop), and adapt them, or you can copy and paste these ones, changing the number and internalname.
    Code:
    keybinding({ modkey }, "number", function () awful.tag.viewonly(internalname) end):add()
    keybinding({ modkey, "Control" }, "number", function () internalname.selected = not internalname.selected end):add()
    keybinding({ modkey, "Shift" }, "number", function () awful.client.movetotag(internalname) end):add()
    keybinding({ modkey, "Control", "Shift" }, "number", function () awful.client.toggletag(internalname) end):add()
    The other useful command is the spawn one, which launches programs. This is in the Standard program section, and is simply
    Code:
    keybinding({ modkey }, "yourkey", function () awful.spawn(terminal) end):add()
    This is why we specified a terminal and browser variable, mostly for neatness. If you don't use a variable, you must put the program name in quotes, otherwise it won't work. You also need to check for conflicts in the shortcuts - the default ones seem to override any user-set ones. You can use this command in a terminal to scan through for the key you wish to check:
    Code:
    cat .config/awesome/rc.lua | grep \"key\"
    where key is just the lower-case keyname, ie "o", "t", "p", etc.


    11. Lastly, getting clients to open on tags. This is done right at the end of the file, in the Hooks section. Under function hook_manage(c), which is executed everytime a new client is spawned, just above -- Honor size hints, add this:
    Code:
        function program(p)
            return c.class:lower():find(p)
        end
        if program("firefox") then
            awful.client.movetotag(internalname)
        end
    This gets the class name in lower case, and if its a match, moves it to the tag. The class name can be found with xprop | grep WM_CLASS and a click on the relevant window.
    I simply have one if statement for each program I wish to tag, however I'm sure there's a neater way of doing it with lists or whatever. At the mo, this works for me, so until I learn some more lua, I'll stick with this.



    12. Well, thats about it. If you get stuck, post here and i'll try and help out, but let me also point you towards some resources that I found very very helpful:
    The awesome wiki
    The awesome wiki article on writing an rc.lua file
    The awesome wiki Wicked page
    Some example rc.lua files

    Basically, use the wiki!
    Attached is my rc file for your viewing pleasure - everything works fine, including all my widgets, so if you get stuck it may well help.

    Good Luck!
    Ubuntu user #11075
    Howto: AwesomeWM (OUTDATED) || My BitBucket Page || My deviantArt page
    If you find a post helpful, click the medal icon to give thanks!
    Quote Originally Posted by chucky chuckaluck View Post
    ... wallpaper is a tiling of the opera icons.

  2. #2
    Join Date
    Apr 2006
    Beans
    Hidden!

    Re: HOWTO: write an awesome 3 configuration file

    Attached is my rc file for your viewing pleasure - everything works fine, including all my widgets, so if you get stuck it may well help.
    Great guide! I'm new to awesome, and wanted to dive right in the deep end with version 3.

    I couldn't find your attached rc file though... I'm not super familiar with these message boards, so maybe I missed it, can you point me in the right direction?

  3. #3
    Join Date
    Aug 2007
    Location
    Cluj/Kolozsvár, Romania
    Beans
    189

    Re: HOWTO: write an awesome 3 configuration file

    Quote Originally Posted by shearn89 View Post
    Programs added here are launched (generally, although at time of writing gedit is coming up tiled. hmmm.) floating on all tags.
    as of rc4 or so, you can use ctrl+mod4+i to get the active window's class (the manpage says "Mod4 + Shift + i Print the client class and instance", but for some reason it's ctrl and not shift for me).
    i had a little sizing-trouble with vlc before i found out its class was not more not less than "."

  4. #4
    Join Date
    Mar 2008
    Beans
    796

    Re: HOWTO: write an awesome 3 configuration file

    Nice guide that helped get me started ,along with the awesome wiki, on using awesome3. Just wondering could you repost your rc.lua file?

  5. #5
    Join Date
    Jul 2006
    Location
    Marlborough, UK
    Beans
    519
    Distro
    Ubuntu 10.04 Lucid Lynx

    Re: HOWTO: write an awesome 3 configuration file

    hey all - just re-found this thread. I'll try and update it this week to cover any little changes in syntax etc, and post my latest rc.lua.
    Ubuntu user #11075
    Howto: AwesomeWM (OUTDATED) || My BitBucket Page || My deviantArt page
    If you find a post helpful, click the medal icon to give thanks!
    Quote Originally Posted by chucky chuckaluck View Post
    ... wallpaper is a tiling of the opera icons.

  6. #6
    Join Date
    Sep 2007
    Beans
    102
    Distro
    Xubuntu 8.04 Hardy Heron

    Re: HOWTO: write an awesome 3 configuration file

    Quote Originally Posted by shearn89 View Post
    hey all - just re-found this thread. I'll try and update it this week to cover any little changes in syntax etc, and post my latest rc.lua.
    Yeah, unfortunately a lot of this stuff is already out-of-date for Awesome 3.1

    Shame they keep breaking things

  7. #7
    Join Date
    Oct 2005
    Location
    De Kwakel - Holland
    Beans
    3,657

    Re: HOWTO: write an awesome 3 configuration file

    Quote Originally Posted by gladstone View Post
    Yeah, unfortunately a lot of this stuff is already out-of-date for Awesome 3.1

    Shame they keep breaking things
    Well, the breaking of things makes the hole Awesome-experience fun.
    Listen.. if it's a tiling wm you need and don't want to have the newest of features you shouldn't upgrade the package.
    Awesome is moving, and it's moving fast, one reason why I use it.

  8. #8
    Join Date
    Jul 2006
    Location
    Marlborough, UK
    Beans
    519
    Distro
    Ubuntu 10.04 Lucid Lynx

    Re: HOWTO: write an awesome 3 configuration file

    I don't think i'll ever be able to keep up with number of updates - there seems to be a new rc out each week! I guess this will have to stay as a basic (slightly unhelpful) reference...
    Ubuntu user #11075
    Howto: AwesomeWM (OUTDATED) || My BitBucket Page || My deviantArt page
    If you find a post helpful, click the medal icon to give thanks!
    Quote Originally Posted by chucky chuckaluck View Post
    ... wallpaper is a tiling of the opera icons.

  9. #9
    Join Date
    Dec 2007
    Location
    Belgium
    Beans
    185

    Re: HOWTO: write an awesome 3 configuration file

    Quote Originally Posted by shearn89 View Post
    I don't think i'll ever be able to keep up with number of updates - there seems to be a new rc out each week! I guess this will have to stay as a basic (slightly unhelpful) reference...
    Config files changes are not happening THAT often, imo, and it's only for the better.

    Ofcourse if you're using git then you will have some more work ^^
    [Configuration files]
    Linux IS user-friendly, it's just picky about its friends.

  10. #10
    Join Date
    Mar 2007
    Beans
    Hidden!

    Re: HOWTO: write an awesome 3 configuration file

    Hi
    Thanks for the tutorials and the PPA reposatories , i was using Awesome 2 for quite sometime now , and now moved to Awesome 3 , however , there are issue in here i don't know if they are common or not :

    1: playing around configuration won't take effects unless i logout/login again ! back to Awesome 2 all what i needed to do is to restart Awesome , not to logout to see changes taking effect !!!!

    2: sometimes changing anything in the rc.lua file get me back to the defualt setting which in the /etc dir !

    3: i select the theme i customize , which is unler .config/awesome/themes/mytheme/ but thats won't work , except for once which back also to the orginal setting !!!!

    am using Awesome 3.3.1

    Any suggestions ?!

    Best regards

Page 1 of 2 12 LastLast

Bookmarks

Posting Permissions

  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts
  •