From awesome

Contents 1 背景 2 設定ファイルのパス 3 Luaの基礎 4 awesome object types 4.1 Screen 4.2 Client 4.3 Tag 4.4 Widget 4.5 Titlebar 4.6 Statusbar 5 Building our interface 5.1 Tag creation 5.2 Client manipulation 5.3 Widget creation 5.4 Statusbar creation 5.5 Titlebar creation 5.6 Using hooks 5.7 Setting up key chains 5.8 Executing commands and scripts 6 awesome Lua libraries 6.1 awful 6.2 beautiful 6.3 eminent 6.4 wicked

[edit] 背景

awesome 3 では設定ファイルにLua言語を使用しています。大半のawesome 2からの利用者はlibconfuse形式だった古い設定ファイルが使えなくなることに泣きを見るでしょう。また何人かはionの設定ファイルが理解できなかった経験から嫌になるかもしれません。

なぜLuaなのか？その理由は多機能だからです。例えば、以前はawesomeで何か事象が発生した際に何らかアクションを起こすことはできませんでしたが、今は（ウィンドウマネージャが可能な範囲であれば）どんなアクションも起こすことが可能です。

[edit] 設定ファイルのパス

• ~/.config/awesome/rc.lua
• /etc/xdg/awesome/rc.lua

[edit] Luaの基礎

"まず初めにLuaについて学びましょう。学びたくないなら、awesome 3は諦めましょう。これ以上読み進める必要はありません。こんなことはどこにも英語の原文には書いてないです。そうです、英語すらろくに訳せなくてもawesomeを使いこなせるのです！"　(このオリジナルの日本語訳の訳者は書籍を売ろうとしているアリフィエイターです。)
　(代わりに、ソースtarballやどこかから設定ファイルを引っぱってきてカスタマイズすれば、Luaの知識がなくてもある程度の動作は可能です。）

まだ読んでますか？いいですね！Luaはシンプルな言語です。その一方で、もしあなたがプログラミングに疎いのであれば、言い換えるとオブジェクトやメソッドや引数が何であるかを知らないのであれば、このドキュメントは理解できないと思います。プログラミングの基礎を学んでから戻ってきてください！

awesome 3はコンピュータを扱うことに長けた上級ユーザーを対象としています。しかしやる気さえあれば、awesomeを設定したり制御する程度の設定方法は身につけることができます。

Luaを学ぶ最も良い方法は、一、二時間ほど書籍Programming In Luaを読むことです。これはLuaで何ができるかの外観が分かる素晴らしい書籍です。フロー制御や役立つ記述などにしおりをはさむことを躊躇してはいけません。例えば設定ファイルを書いている状況でfor構文を探す苦労を考えればきっと役に立ちます。（訳注：日本語の書籍では入門Luaプログラミングがあります）

[edit] awesome object types

For people coming from the outer space and who did not use awesome, here are the basic objects that awesome will give to you and you will have to manipulate soon.

[edit] Screen

There is no real screen object in awesome, but we will talk about screens later. A screen is a physical monitor plugged to your computer. They are represented by their index, starting at 1.

[edit] Client

A client is a window. I guess I'm clear.

[edit] Tag

A tag is something like a workspace/desktop but the concept is less rigid. Each client has at least one tag assigned to it. Each screen has at least one tag. At any time, on a screen, you can view any tag number. Watching no tag will hide every client. Watching one or more tags will show you all client which have these tags.

[edit] Widget

Widgets are objects which draw things on the screen. There are several types of widget. For example there's a text box widget which prints text on screen. There's also a icon box widget which draws icon on the screen.

[edit] Titlebar

A titlebar is a bar which is around a client and attached to it. You can put widgets in it.

[edit] Statusbar

A statusbar is a bar which is fixed at the edge of a screen. You can put widgets in it.

[edit] Building our interface

To build our interface, we need to use awesome functions and methods: everything is documented in the awesomerc(5) manpage and in the luadoc. Read them. They are your development reference. I repeat: read it, everything is documented in this manpage and in luadoc.

Which manpage?… awesomerc(5). Good. You're following.

[edit] Tag creation

If you start awesome without any Lua operation, you will have 0 tag, which is fatal. awesome wants at least one tag.

So first, we need to create one tag. How do we do that? We look for tag.new and it documentation, the tag creator function in the manpage. It says that the paramater of the function must be a table with at least a name attribute. Let's do that.

mytagone = tag({ name = "one" })

mytag is now a tag object, and its name is one. If we want to set the default layout, we can add its as a key/value pair inside the table, as explained in the documentation.

mytagtwo = tag({name = "two", layout = "floating" })

Now, we have a second tag: its name is two, and by default it arrange client with the floating algorithm, which like its name says, let the clients float.

Creating object is nice, but well, for now it's useless. Remember: each screen has at least one tag. So we need to add this created tags to our first screen. The screen attribute of the tag object do that for us, we only need to give it the screen number value.

mytagone.screen = 1

We just added that tag to the screen #1. If we have a second screen (multi-head: Zaphod, Xinerama or XRandR are identical for awesome), we can add our second tag to this screen:

mytagtwo.screen = 2

And if we have 3 screen, we need to... Well, I guess you got it.

If you want to know how many screens you have, you can use the screen.count() function.

You can manipulate tag viewing with the selected attribute. If you want to view your tag one:

mytagone.selected

If you want to hide it, you can obviously set the value to false.

You can manipulate all the tag settings with its attribute. See the documentation.

[edit] Client manipulation

Sometimes, you will get client object. This is very useful in hooks functions, which we will discuss later.

A client is an object which has methods too, like tags and others. We decide that the c variable is our client object. For example, if we want to set a client floating we can use the floating attribute like this:

c.floating = true

Some methods return value that can be used later for analyse. If we want to know if a client is floating, we can get the floating attribute:

is_client_floating = c.floating

The variable is_client_floating now contains a boolean value: true if the client is floating or false if the client is not.

We can combine these 2 functions to create a toggle function: this function will set the client floating state to true if it's not, or to false if it is.

function client_floating_toggle(c)
    if c then
        c.floating = not c.floating
    end
end

We can also use that to toggle tag on our client:

function client_tag_with_tag_one(c)
    if c then
        local t = c.tags
        table.insert(t, one)
        c.tags = t
    end
end

[edit] Widget creation

Widgets are small object that can be placed either on a titlebar either on a statusbar. Like tags, if you do not add them somewhere, they're totally useless. To create a widget you use the widget.new() function:

mytextbox = widget({ type = "textbox", name = "mytextbox" })

mytextbox now contains a widget object. Widget objects are particular in one way: they do not have a lot of methods. However, widgets have one very useful method which is set(). This method permits to set a lot of property of the widget. It takes 2 arguments, as described in the documentation, the key and the value.

mytextbox.text = "Hello, world!

This will set the text printed by the widget to Hello, world!.

[edit] Statusbar creation

Statusbars are widget containers that you can put on top, bottom, left or right screen edges.

First, create a statusbar:

mystatusbar = statusbar({ position = "top", name = "mystatusbar" })

mystatusbar is now a variable which contains a statusbar object. Since we set position to top, it will be placed on top of our screen. Obviously, we did not add it to the screen, so it's useless for now. Let's do it:

mystatusbar.screen = 1

Our statusbar is now visible on top of the screen. Well, it does nothing, so it's very useful. Let's add some widget!

-- Create a textbox
mytextbox = widget({ type = "textbox", name = "mytextbox" })
-- Set text of the textbox
mytextbox.text = "Hello, world!"
-- Create a statusbar
mystatusbar = statusbar({ position = "top", name = "mystatusbar" })
-- Add a widget to the statusbar
mystatusbar.widgets = { mytextbox }
-- Add the statusbar on the screen #1
mystatusbar.screen = 1

And voilà. We now have a brand new statusbar on top of the screen which print Hello, world!. Using this methods, you can set up a statusbar with lots of widgets before starting awesome, in your configuration file.

[edit] Titlebar creation

Like I said before, titlebars are like statusbar except that they are around a window. To create a titlebar, you know the drill:

mytitlebar = titlebar({ position = "top" })

Then, you probably want to put widget in it. It works like statusbars:

mytitlebartitle = widget({ type = "textbox", name = "mytitlebartitle" })
mytitlebar.widgets = { mytitlebartitle }

A titlebar must be added to a client object. We can get the currently focused client with the client.focus_get function. Let's do that:

-- Get the focused client
c = client.focus_get()
-- Set a titlebar on it
c.titlebar = mytitlebar

Now, the focused client has a nice titlebar on top of it! But it has nothing in it. No, wait! Remember, in the titlebar we already added a textbox widget. We can now print the client name in it:

mytitlebartitle.text = c.name

The name attribute is a string with the client's title, and we set it as the text of the widget. Now the titlebar print the client's title.

Remember: a titlebar is one object, and a client is another object. So you need to create a titlebar for each client you want a titlebar around.

[edit] Using hooks

With what we seen before, you can build a nice interface. However, imagine you want to update the title printed in the titlebar of a client: you can't. Wait! Here's the solution: hooks.

With hooks, you can define functions that are called when an event happens. Let's try with an example.

When a new client pop up on screen, awesome runs the function hooked by the manage hook. This function is called with the new client as argument. Here's an example:

function hook_manage(c)
    if c.name:find("mplayer") then
        c.floating = true
    end
end

First, we defined a hook_manage function, with an argument named c, which will be the client. Then, we try to found if the string "mplayer" is in the name of the client, and if so, we set it floating.

 hooks.manage(hook_manage)

Then, with that call we define that the function to call on each new client arrival is hook_manage.

There's a lot of hooks you can use and define: focus, unfocus, manage, unmanage, mouseover, arrange, titleupdate, urgent, timer, … Refer to the manpage for more information.

[edit] Setting up key chains

Sometimes it can be helpful to map certain actions to a series of keys, which are often easier to press than Mod-shift-ctrl-x. In the following example you can type Ctrl-f and AFTERWARDS press "a" instead of all keys at the same time.

 -- Create a list of keybindings to be added when Ctrl-f is pressed 
 keybind_ctrl_f = {} 
  
 function keychain_ctrl_f_add() 
     for k, v in pairs(keybind_ctrl_f) do 
         v:add() 
     end 
 end 
 
 function keychain_ctrl_f_remove() 
     for k, v in pairs(keybind_ctrl_f) do 
         v:remove() 
     end 
 end 
 
 table.insert(keybind_ctrl_f, keybinding({}, "a", function () 
     mytextbox.text = "You pressed a!"
     keychain_ctrl_f_remove() 
 end)) 
 
 table.insert(keybind_ctrl_f, keybinding({ "Mod4" }, "b", function () 
     mytextbox.text = "You pressed Mod4 + b!"
     keychain_ctrl_f_remove() 
 end)) 
 
 table.insert(keybind_ctrl_f, keybinding({}, "Escape", keychain_ctrl_f_remove)) 
 
 keybinding({ "Control" }, "f", keychain_ctrl_f_add):add()

[edit] Executing commands and scripts

You can execute commands and scripts from the lua based configuration. Here is an example function that takes command as parameter and returns its output. This is usefull for example for putting stuff from command outputs to textboxes.

-- Execute command and return its output. You probably wan't only execute commands with one
-- line of output
function execute_command(command)
   local fh = io.popen(command)
   local str = ""
   for i in fh:lines() do
      str = str .. i
   end
   io.close(fh)
   return str
end

Here is an example of putting /proc/loadavg to mytextbox:

 mytextbox.text = " " .. execute_command("cat /proc/loadavg") .. " "

[edit] awesome Lua libraries

[edit] awful

Awful is the default library to interact with awesome, like mouse action or keybinds.

[edit] beautiful

Beautiful is as library to theme the look of awesome.

[edit] eminent

Eminent is a Lua library that will enable you to use dynamic tagging. Dynamic tagging in this instance means that the amount of tags you have is not pre-defined, you can give specific tags names, but simply going to the next tag when you're on the last tag will provide you with a brand new one, allowing you to adapt to various usage situations without changing your configuration file to give you more or less tags.

[edit] wicked

Wicked is a Lua library for awesome to provide more widgets, like MPD Widget, CPU usage, memory usage, etc.