Module awful
awful: AWesome Functions very UsefuL
Author:
Julien Danjou <julien@danjou.info> |
Copyright© 2008 Julien Danjou
Release: v3.0
Functions
beautiful.register (btheme, The) | Set the beautiful theme if any. |
calculate_distance (dir, cA, cB) | Calculate distance between two points. |
client.focus.history.add (c) | Update client focus history. |
client.focus.history.delete (c) | Remove a client from the focus history |
client.focus.history.get (screen, idx) | Get the latest focused client for a screen in history. |
client.focus.history.previous () | Focus the previous client in history. |
client.focusbydirection (dir, c) | Focus a client by the given direction. |
client.focusbyidx (i, c) | Focus a client by its relative index. |
client.getmarked () | Return the marked clients and empty the marked table. |
client.ismarked (c) | Check if a client is marked. |
client.mark (c) | Mark a client, and then call 'marked' hook. |
client.master (screen) | Get the master window. |
client.maximize (c) | Maximize a client to use the full workarea. |
client.moveresize (x, y, w, h, c) | Move/resize a client relative to current coordinates. |
client.movetoscreen (c, s) | Move a client to a screen. |
client.movetotag (target, c) | Move a client to a tag. |
client.next (i, c) | Get a client by its relative index to the focused window. |
client.swap (i, c) | Swap a client by its relative index. |
client.togglefloating (c) | Toggle the floating status of a client. |
client.togglemarked (c) | Toggle a client as marked. |
client.toggletag (target, c) | Toggle a tag on a client. |
client.unmark (c) | Unmark a client and then call 'unmarked' hook. |
client.urgent.get () | Get the first client that got the urgent hint. |
client.urgent.jumpto () | Jump to the client that received the urgent hint first. |
client.urgent.stack.add (c, The) | Adds client to urgent stack. |
client.urgent.stack.delete (c, The) | Remove client from urgent stack. |
client_maximize_clean (c) | Erase eventual client data in maximize. |
completion.bash (command, cur_pos, ncomp) | Use bash completion system to complete command and filename. |
completion.bashcomp_load (src) | Enable programmable bash completion in awful.completion.bash at the price of a slight overhead |
cycle (t, i) | Make i cycle. |
escape (text) | Escape a string from XML char. |
eval (s) | Eval Lua code. |
hooks.user.call (name, ...) | Call a created userhook (for external libs). |
hooks.user.create (name) | Create a new userhook (for external libs). |
is_in_direction (dir, cA, cB) | Return true whether client B is in the right direction compared to client A. |
layout.get (screen) | Get the current layout name. |
layout.inc (layouts, i) | Change the layout of the current tag. |
layout.set (layout) | Set the layout of the current tag by name. |
mkdir (dir) | Create a directory |
prompt.run (args, textbox, exe_callback, completion_callback, history_path, history_max, done_callback) | Run a prompt in a box. |
prompt_history_add (id, command) | Add an entry to the history file |
prompt_history_check_load (id, max) | Load history file in history table |
prompt_history_items (id) | Return the number of items in history table regarding the id |
prompt_history_save (id) | Save history table in history file |
prompt_text_with_cursor (text, text_color, cursor_color, cursor_pos) | Draw the prompt text with a cursor. |
screen.focus (i, Screen) | Give the focus to a screen, and move pointer. |
spawn (cmd, screen) | Spawn a program. |
tag.history.update (screen) | Update the tag history. |
tag.incmwfact (add) | Increase master width factor. |
tag.incncol (add) | Increase number of column windows. |
tag.incnmaster (add) | Increase the number of master windows. |
tag.selected (s) | Return only the first visible tag. |
tag.selectedlist (s) | Return a table with all visible tags |
tag.setmwfact (mwfact) | Set master width factor. |
tag.setncol (ncol) | Set number of column windows. |
tag.setnmaster (nmaster) | Set the number of master windows. |
tag.viewidx (i, screen) | View a tag by its index. |
tag.viewmore (tags, screen) | View only a set of tags. |
tag.viewnext () | View next tag. |
tag.viewnone (screen, Optional) | View no tag. |
tag.viewonly (t) | View only a tag. |
tag.viewprev () | View previous tag. |
tag_compare_select (a, b) | Compare 2 tables of tags. |
titlebar.add (c, args) | Create a standard titlebar. |
titlebar.remove (c) | Remove a titlebar from a client. |
titlebar.update (c) | Update a titlebar. |
unescape (text) | Unescape a string from entities. |
widget.taglist.label.all (t, args) | Return labels for a taglist widget with all tag from screen. |
widget.taglist.label.noempty (t, args) | Return labels for a taglist widget with all *non empty* tags from screen. |
widget.tasklist.label.allscreen (c, screen, args) | Return labels for a tasklist widget with clients from all tags and screen. |
widget.tasklist.label.alltags (c, screen, args) | Return labels for a tasklist widget with clients from all tags. |
widget.tasklist.label.currenttags (c, screen, args) | Return labels for a tasklist widget with clients from currently selected tags. |
Functions
- beautiful.register (btheme, The)
-
Set the beautiful theme if any.
Parameters
- btheme:
- The: beautiful theme.
- calculate_distance (dir, cA, cB)
-
Calculate distance between two points. i.e: if we want to move to the right, we will take the right border of the currently focused client and the left side of the checked client. This avoid the focus of an upper client when you move to the right in a tilebottom layout with nmaster=2 and 5 clients open, for instance.
Parameters
- dir: The direction.
- cA: The first client.
- cB: The second client.
Return value:
The distance between the clients. - client.focus.history.add (c)
-
Update client focus history.
Parameters
- c: The client that has been focused.
- client.focus.history.delete (c)
-
Remove a client from the focus history
Parameters
- c: The client that must be removed.
- client.focus.history.get (screen, idx)
-
Get the latest focused client for a screen in history.
Parameters
- screen: The screen number to look for.
- idx: The index: 0 will return first candidate, 1 will return second, etc.
Return value:
A client. - client.focus.history.previous ()
- Focus the previous client in history.
- client.focusbydirection (dir, c)
-
Focus a client by the given direction.
Parameters
- dir: The direction, can be either "up", "down", "left" or "right".
- c: Optional client.
- client.focusbyidx (i, c)
-
Focus a client by its relative index.
Parameters
- i: The index.
- c: Optional client.
- client.getmarked ()
-
Return the marked clients and empty the marked table.
Return value:
A table with all marked clients. - client.ismarked (c)
-
Check if a client is marked.
Parameters
- c: The client to check, or the focused one otherwise.
- client.mark (c)
-
Mark a client, and then call 'marked' hook.
Parameters
- c: The client to mark, the focused one if not specified.
Return value:
True if the client has been marked. False if the client was already marked. - client.master (screen)
-
Get the master window.
Parameters
- screen: Optional screen number, otherwise screen mouse is used.
Return value:
The master window. - client.maximize (c)
-
Maximize a client to use the full workarea.
Parameters
- c: A client, or the focused one if nil.
- client.moveresize (x, y, w, h, c)
-
Move/resize a client relative to current coordinates.
Parameters
- x: The relative x coordinate.
- y: The relative y coordinate.
- w: The relative width.
- h: The relative height.
- c: The optional client, otherwise focused one is used.
- client.movetoscreen (c, s)
-
Move a client to a screen. Default is next screen, cycling.
Parameters
- c: The client to move.
- s: The screen number, default to current + 1.
- client.movetotag (target, c)
-
Move a client to a tag.
Parameters
- target: The tag to move the client to.
- c: Optional client to move, otherwise the focused one is used.
- client.next (i, c)
-
Get a client by its relative index to the focused window.
Parameters
- i: The index.
- c: Optional client.
Usage:
Set i to 1 to get next, -1 to get previous.Return value:
A client, or nil if no client is available. - client.swap (i, c)
-
Swap a client by its relative index.
Parameters
- i: The index.
- c: Optional client, otherwise focused one is used.
- client.togglefloating (c)
-
Toggle the floating status of a client.
Parameters
- c: Optional client, the focused on if not set.
- client.togglemarked (c)
-
Toggle a client as marked.
Parameters
- c: The client to toggle mark.
- client.toggletag (target, c)
-
Toggle a tag on a client.
Parameters
- target: The tag to toggle.
- c: Optional client to toggle, otherwise the focused one is used.
- client.unmark (c)
-
Unmark a client and then call 'unmarked' hook.
Parameters
- c: The client to unmark, or the focused one if not specified.
Return value:
True if the client has been unmarked. False if the client was not marked. - client.urgent.get ()
-
Get the first client that got the urgent hint.
Return value:
The first urgent client. - client.urgent.jumpto ()
- Jump to the client that received the urgent hint first.
- client.urgent.stack.add (c, The)
-
Adds client to urgent stack.
Parameters
- c:
- The: client object.
- client.urgent.stack.delete (c, The)
-
Remove client from urgent stack.
Parameters
- c:
- The: client object.
- client_maximize_clean (c)
-
Erase eventual client data in maximize.
Parameters
- c: The client.
- completion.bash (command, cur_pos, ncomp)
-
Use bash completion system to complete command and filename.
Parameters
- command: The command line.
- cur_pos: The cursor position.
- ncomp: The element number to complete.
Return value:
The new command and the new cursor position. - completion.bashcomp_load (src)
-
Enable programmable bash completion in awful.completion.bash at the price of a slight overhead
Parameters
- src: The bash completion source file, /etc/bash_completion by default.
- cycle (t, i)
-
Make i cycle.
Parameters
- t: A length.
- i: An absolute index to fit into #t.
Return value:
The object at new index. - escape (text)
-
Escape a string from XML char. Useful to set raw text in textbox.
Parameters
- text: Text to escape.
Return value:
Escape text. - eval (s)
-
Eval Lua code.
Parameters
- s:
Return value:
The return value of Lua code. - hooks.user.call (name, ...)
-
Call a created userhook (for external libs).
Parameters
- name: Hook name.
- ...:
- hooks.user.create (name)
-
Create a new userhook (for external libs).
Parameters
- name: Hook name.
- is_in_direction (dir, cA, cB)
-
Return true whether client B is in the right direction compared to client A.
Parameters
- dir: The direction.
- cA: The first client.
- cB: The second client.
Return value:
True if B is in the direction of A. - layout.get (screen)
-
Get the current layout name.
Parameters
- screen: The screen number.
- layout.inc (layouts, i)
-
Change the layout of the current tag.
Parameters
- layouts: A table of layouts.
- i: Relative index.
- layout.set (layout)
-
Set the layout of the current tag by name.
Parameters
- layout: Layout name.
- mkdir (dir)
-
Create a directory
Parameters
- dir: The directory.
Return value:
mkdir return code - prompt.run (args, textbox, exe_callback, completion_callback, history_path, history_max, done_callback)
-
Run a prompt in a box.
Parameters
- args: A table with optional arguments: fg_cursor, bg_cursor, prompt.
- textbox: The textbox to use for the prompt.
- exe_callback: The callback function to call with command as argument when finished.
- completion_callback: The callback function to call to get completion.
- history_path: Optional parameter: file path where the history should be saved, set nil to disable history
- history_max: Optional parameter: set the maximum entries in history file, 50 by default
- done_callback: Optional parameter: the callback function to always call without arguments, regardless of whether the prompt was cancelled.
- prompt_history_add (id, command)
-
Add an entry to the history file
Parameters
- id: The prompt history identifier
- command: The command to add
- prompt_history_check_load (id, max)
-
Load history file in history table
Parameters
- id: The prompt history identifier which is the path to the filename
- max: Optional parameter, the maximum number of entries in file
- prompt_history_items (id)
-
Return the number of items in history table regarding the id
Parameters
- id: The prompt history identifier
Return value:
the number of items in history table, -1 if history is disabled - prompt_history_save (id)
-
Save history table in history file
Parameters
- id: The prompt history identifier
- prompt_text_with_cursor (text, text_color, cursor_color, cursor_pos)
-
Draw the prompt text with a cursor.
Parameters
- text: The text.
- text_color: The text color.
- cursor_color: The cursor color.
- cursor_pos: The cursor position.
- screen.focus (i, Screen)
-
Give the focus to a screen, and move pointer.
Parameters
- i:
- Screen: number.
- spawn (cmd, screen)
-
Spawn a program.
Parameters
- cmd: The command.
- screen: The screen where to spawn window.
Return value:
The awesome.spawn return value. - tag.history.update (screen)
-
Update the tag history.
Parameters
- screen: The screen number.
- tag.incmwfact (add)
-
Increase master width factor.
Parameters
- add: Value to add to master width factor.
- tag.incncol (add)
-
Increase number of column windows.
Parameters
- add: Value to add to number of column windows.
- tag.incnmaster (add)
-
Increase the number of master windows.
Parameters
- add: Value to add to number of master windows.
- tag.selected (s)
-
Return only the first visible tag.
Parameters
- s: Screen number.
- tag.selectedlist (s)
-
Return a table with all visible tags
Parameters
- s: Screen number.
Return value:
A table with all selected tags. - tag.setmwfact (mwfact)
-
Set master width factor.
Parameters
- mwfact: Master width factor.
- tag.setncol (ncol)
-
Set number of column windows.
Parameters
- ncol: The number of column.
- tag.setnmaster (nmaster)
-
Set the number of master windows.
Parameters
- nmaster: The number of master windows.
- tag.viewidx (i, screen)
-
View a tag by its index.
Parameters
- i: The relative index to see.
- screen: Optional screen number.
- tag.viewmore (tags, screen)
-
View only a set of tags.
Parameters
- tags: A table with tags to view only.
- screen: Optional screen number of the tags.
- tag.viewnext ()
- View next tag. This is the same as tag.viewidx(1).
- tag.viewnone (screen, Optional)
-
View no tag.
Parameters
- screen:
- Optional: screen number.
- tag.viewonly (t)
-
View only a tag.
Parameters
- t: The tag object.
- tag.viewprev ()
- View previous tag. This is the same a tag.viewidx(-1).
- tag_compare_select (a, b)
-
Compare 2 tables of tags.
Parameters
- a: The first table.
- b: The second table of tags.
Return value:
True if the tables are identical, false otherwise. - titlebar.add (c, args)
-
Create a standard titlebar.
Parameters
- c: The client.
- args: Arguments. fg: the foreground color. bg: the background color. fg_focus: the foreground color for focused window. fg_focus: the background color for focused window.
- titlebar.remove (c)
-
Remove a titlebar from a client.
Parameters
- c: The client.
- titlebar.update (c)
-
Update a titlebar. This should be called in some hooks.
Parameters
- c: The client to update.
- unescape (text)
-
Unescape a string from entities.
Parameters
- text: Text to unescape.
Return value:
Unescaped text. - widget.taglist.label.all (t, args)
-
Return labels for a taglist widget with all tag from screen. It returns the tag name and set a special foreground and background color for selected tags.
Parameters
- t: The tag.
- args: The arguments table. bg_focus The background color for selected tag. fg_focus The foreground color for selected tag. bg_urgent The background color for urgent tags. fg_urgent The foreground color for urgent tags. taglist_squares Optional: set "true" or nil to display the taglist squares. taglist_squares_sel Optional: an user provided image for selected squares. taglist_squares_unsel Optional: an user provided image for unselected squares.
Return value:
A string to print. - widget.taglist.label.noempty (t, args)
-
Return labels for a taglist widget with all *non empty* tags from screen. It returns the tag name and set a special foreground and background color for selected tags.
Parameters
- t: The tag.
- args: The arguments table. bg_focus The background color for selected tag. fg_focus The foreground color for selected tag. bg_urgent The background color for urgent tags. fg_urgent The foreground color for urgent tags.
Return value:
A string to print. - widget.tasklist.label.allscreen (c, screen, args)
-
Return labels for a tasklist widget with clients from all tags and screen. It returns the client name and set a special foreground and background color for focused client. It also puts a special icon for floating windows.
Parameters
- c: The client.
- screen: The screen we are drawing on.
- args: The arguments table. bg_focus The background color for focused client. fg_focus The foreground color for focused client. bg_urgent The background color for urgent clients. fg_urgent The foreground color for urgent clients.
Return value:
A string to print. - widget.tasklist.label.alltags (c, screen, args)
-
Return labels for a tasklist widget with clients from all tags. It returns the client name and set a special foreground and background color for focused client. It also puts a special icon for floating windows.
Parameters
- c: The client.
- screen: The screen we are drawing on.
- args: The arguments table. bg_focus The background color for focused client. fg_focus The foreground color for focused client. bg_urgent The background color for urgent clients. fg_urgent The foreground color for urgent clients.
Return value:
A string to print. - widget.tasklist.label.currenttags (c, screen, args)
-
Return labels for a tasklist widget with clients from currently selected tags. It returns the client name and set a special foreground and background color for focused client. It also puts a special icon for floating windows.
Parameters
- c: The client.
- screen: The screen we are drawing on.
- args: The arguments table. bg_focus The background color for focused client. fg_focus The foreground color for focused client. bg_urgent The background color for urgent clients. fg_urgent The foreground color for urgent clients.
Return value:
A string to print.