Module capi

capi: awesome C API

Author:

Julien Danjou <julien@danjou.info>

Copyright© 2008 Julien Danjou

Functions

awesome.colors_set (arg1) Set default colors.
awesome.exec (arg1) Execute another application, probably a window manager, to replace awesome.
awesome.font_set (arg1) Set default font.
awesome.mouse_add (arg1) Add a global mouse binding.
awesome.quit () Quit awesome.
awesome.restart () Restart awesome.
awesome.spawn (arg1, arg2) Spawn a program.
client.focus_get () Get the currently focused client (DEPRECATED).
client.focus_set () Focus a client (DEPRECATED).
client.get () Get all clients into a table.
client.kill () Kill a client.
client.mouse_add (arg1) Add mouse bindings over clients's window.
client.mouse_move (arg1) Move a client with mouse.
client.mouse_remove (arg1) Remove mouse bindings over clients's window.
client.mouse_resize (arg1) Resize a client with mouse.
client.raise () Raise a client on top of others which are on the same layer.
client.redraw () Redraw a client by unmapping and mapping it quickly.
client.swap (arg1) Swap a client with another one.
client.tags (arg1) Access or set the client tags.
client.unmanage () Stop managing a client.
client.visible_get (arg1) Get only visible clients for a screen.
graph.plot_data_add (arg1, arg2) Add data to a plot.
graph.plot_properties_set (arg1, arg2) Set various plot graph properties.
hooks.arrange (arg1) Set the function called on each screen arrange.
hooks.focus (arg1) Set the function called each time a client gets focus.
hooks.manage (arg1) Set the function called each time a new client appears.
hooks.mouseover (arg1) Set the function called each time the mouse enter a new window.
hooks.timer (arg1, arg2) Set the function to be called every N seconds.
hooks.titleupdate (arg1) Set the function called on each title update.
hooks.unfocus (arg1) Set the function called each time a client loses focus.
hooks.unmanage (arg1) Set the function called each time a client goes away.
hooks.urgent (arg1) Set the function called when a client get urgency flag.
keybinding (arg1, arg2, arg3) Define a global key binding.
keybinding.add () Add a global key binding.
keybinding.remove () Remove a global key binding.
keygrabber.run (arg1) Grab keyboard and read pressed keys, calling callback function at each key pressed.
mouse (arg1, arg2, arg3) Create a new mouse button bindings.
mouse.coords (arg1) Get or set the mouse coords.
progressbar.bar_data_add (arg1, arg2) Add a value to a progressbar bar.
progressbar.bar_properties_set (arg1, arg2) Set various progressbar bars properties:
screen.count () Get the screen count.
screen.padding (arg1) Set or get the screen padding.
screen.tags (arg1) Get or set screen tags.
statusbar (arg1) Create a new statusbar.
statusbar.widgets (arg1) Get or set the statusbar widgets.
tag (arg1) Create a new tag.
tag.clients (arg1) Get or set the clients attached to this tag.
titlebar (arg1) Create a new titlebar.
widget (arg1) Create a new widget.
widget.mouse_add (arg1) Add a mouse button bindings to a widget.
widget.mouse_remove (arg1) Remove a mouse button bindings from a widget.

Tables

client Client object.
graph Graph widget.
mouse Mouse object.
otable Object table.
progressbar Progressbar widget.
screen A screen.
statusbar Statusbar object.
tag Tag object.
taglist Taglist widget.
tasklist Tasklist widget.
textbox Textbox widget.
titlebar Titlebar object.
widget Generic widget.


Functions

awesome.colors_set (arg1)
Set default colors.

Parameters

  • arg1: A table with `fg' and `bg' elements, containing colors.
awesome.exec (arg1)
Execute another application, probably a window manager, to replace awesome.

Parameters

  • arg1: The command line to execute.
awesome.font_set (arg1)
Set default font.

Parameters

  • arg1: A string with a font name in Pango format.
awesome.mouse_add (arg1)
Add a global mouse binding. This binding will be available when you'll click on root window.

Parameters

  • arg1: A mouse button binding.
awesome.quit ()
Quit awesome.
awesome.restart ()
Restart awesome.
awesome.spawn (arg1, arg2)
Spawn a program. This function is multi-head (Zaphod) aware and will set display to the right screen according to mouse position.

Parameters

  • arg1: The command to launch.
  • arg2: The optional screen number to spawn the command on.
client.focus_get ()
Get the currently focused client (DEPRECATED).

Return value:

The currently focused client.
client.focus_set ()
Focus a client (DEPRECATED).
client.get ()
Get all clients into a table.

Return value:

A table with all clients.
client.kill ()
Kill a client.
client.mouse_add (arg1)
Add mouse bindings over clients's window.

Parameters

  • arg1: A button binding.
client.mouse_move (arg1)
Move a client with mouse.

Parameters

  • arg1: An optional table with keys: `snap' for pixel to snap (default to 8), and `infobox' to enable or disable the coordinates and dimensions box (default to enabled).
client.mouse_remove (arg1)
Remove mouse bindings over clients's window.

Parameters

  • arg1: A button binding.
client.mouse_resize (arg1)
Resize a client with mouse.

Parameters

  • arg1: An optional table with keys: `corner', such as bottomleft, topright, etc, to specify which corner to grab (default to auto) and `infobox' to enable or disable the coordinates and dimensions box (default to enabled).
client.raise ()
Raise a client on top of others which are on the same layer.
client.redraw ()
Redraw a client by unmapping and mapping it quickly.
client.swap (arg1)
Swap a client with another one.

Parameters

  • arg1: A client to swap with.
client.tags (arg1)
Access or set the client tags.

Parameters

  • arg1: A table with tags to set, or none to get the current tags table.
client.unmanage ()
Stop managing a client.
client.visible_get (arg1)
Get only visible clients for a screen.

Parameters

  • arg1: A screen number.

Return value:

A table with all visible clients for this screen.
graph.plot_data_add (arg1, arg2)
Add data to a plot.

Parameters

  • arg1: A plot name.
  • arg2: A data value.
graph.plot_properties_set (arg1, arg2)
Set various plot graph properties.

Parameters

  • arg1: A plot name.
  • arg2: A table with various properties set.
hooks.arrange (arg1)
Set the function called on each screen arrange. This function is called with the screen number as argument.

Parameters

  • arg1: A function to call on each screen arrange.
hooks.focus (arg1)
Set the function called each time a client gets focus. This function is called with the client object as argument.

Parameters

  • arg1: A function to call each time a client gets focus.
hooks.manage (arg1)
Set the function called each time a new client appears. This function is called with the client object as argument.

Parameters

  • arg1: A function to call on each new client.
hooks.mouseover (arg1)
Set the function called each time the mouse enter a new window. This function is called with the client object as argument.

Parameters

  • arg1: A function to call each time a client gets mouse over it.
hooks.timer (arg1, arg2)
Set the function to be called every N seconds.

Parameters

  • arg1: The number of seconds to run function every. Set 0 to disable.
  • arg2: A function to call every N seconds (optional).
hooks.titleupdate (arg1)
Set the function called on each title update. This function is called with the client object as argument.

Parameters

  • arg1: A function to call on each title update of each client.
hooks.unfocus (arg1)
Set the function called each time a client loses focus. This function is called with the client object as argument.

Parameters

  • arg1: A function to call each time a client loses focus.
hooks.unmanage (arg1)
Set the function called each time a client goes away. This function is called with the client object as argument.

Parameters

  • arg1: A function to call when a client goes away.
hooks.urgent (arg1)
Set the function called when a client get urgency flag. This function is called with the client object as argument.

Parameters

  • arg1: A function to call when a client get the urgent flag.
keybinding (arg1, arg2, arg3)
Define a global key binding. This key binding will always be available.

Parameters

  • arg1: A table with modifier keys.
  • arg2: A key name.
  • arg3: A function to execute.

Return value:

The keybinding.
keybinding.add ()
Add a global key binding. This key binding will always be available.
keybinding.remove ()
Remove a global key binding.
keygrabber.run (arg1)
Grab keyboard and read pressed keys, calling callback function at each key pressed. The callback function must return a boolean value: true to continue grabbing, false to stop. The function is called with 2 arguments: a table containing modifiers keys and a string, the key pressed.

Parameters

  • arg1: A callback function as described above.
mouse (arg1, arg2, arg3)
Create a new mouse button bindings.

Parameters

  • arg1: A table with modifiers keys.
  • arg2: A mouse button number.
  • arg3: A function to execute on click events.

Return value:

A mouse button binding.
mouse.coords (arg1)
Get or set the mouse coords.

Parameters

  • arg1: None or a table with x and y keys as mouse coordinates.

Return value:

A table with mouse coordinates.
progressbar.bar_data_add (arg1, arg2)
Add a value to a progressbar bar.

Parameters

  • arg1: A bar name.
  • arg2: A data value.
progressbar.bar_properties_set (arg1, arg2)
Set various progressbar bars properties:

Parameters

  • arg1: A bar name.
  • arg2: A table with keys as properties names.
screen.count ()
Get the screen count.

Return value:

The screen count, at least 1.
screen.padding (arg1)
Set or get the screen padding.

Parameters

  • arg1: None or a table with new padding values.

Return value:

The screen padding. A table with top, right, left and bottom keys and values in pixel.
screen.tags (arg1)
Get or set screen tags.

Parameters

  • arg1: None or a table of tags to set to the screen. The table must contains at least one tag.
statusbar (arg1)
Create a new statusbar.

Parameters

  • arg1: A table with at least a name attribute. Optionaly defined values are: position, align, fg, bg, width and height.

Return value:

A brand new statusbar.
statusbar.widgets (arg1)
Get or set the statusbar widgets.

Parameters

  • arg1: None, or a table of widgets to set.

Return value:

The current statusbar widgets.
tag (arg1)
Create a new tag.

Parameters

  • arg1: A table with at least a name attribute. Optional attributes are: mwfact, ncol, nmaster and layout.

Return value:

A new tag object.
tag.clients (arg1)
Get or set the clients attached to this tag.

Parameters

  • arg1: None or a table of clients to set.

Return value:

A table with the clients attached to this tags.
titlebar (arg1)
Create a new titlebar.

Parameters

  • arg1: A table with values: align, position, fg, bg, border_width, border_color, width and height.

Return value:

A brand new titlebar.
widget (arg1)
Create a new widget.

Parameters

  • arg1: A table with at least a name and a type value. Optional attributes are: align.

Return value:

A brand new widget.
widget.mouse_add (arg1)
Add a mouse button bindings to a widget.

Parameters

  • arg1: A mouse button bindings object.
widget.mouse_remove (arg1)
Remove a mouse button bindings from a widget.

Parameters

  • arg1: A mouse button bindings object.

Tables

client
Client object. Fields
  • name: The client title.
  • class: The client class.
  • instance: The client instance.
  • pid: The client PID, if available.
  • role: The window role, if available.
  • machine: The machine client is running on.
  • icon_name: The client name when iconified.
  • floating_placement: The floating placement used for this client.
  • screen: Client screen number.
  • hide: Define if the client must be hidden, i.e. never mapped.
  • icon_path: Path to the icon used to identify.
  • floating: True always floating.
  • honorsizehints: Honor size hints, i.e. respect size ratio.
  • border_width: The client border width.
  • border_color: The client border color.
  • titlebar: The client titlebar.
  • urgent: The client urgent state.
  • focus: The focused client.
  • opacity: The client opacity between 0 and 1.
graph
Graph widget. Fields
  • plot_properties_set: A function to set plot properties.
  • plot_add_add: A function to add data to a plot.
  • height: Graph height.
  • widget: Graph width.
  • bg: Background color.
  • grow: Direction to grow: left or right.
mouse
Mouse object. Fields
  • coords: Mouse coordinates.
  • screen: Mouse screen number.
otable
Object table. This table can use safely object as key.
progressbar
Progressbar widget. Fields
  • bar_properties_set: Set the properties of a bar.
  • bar_data_add: Add data to a bar.
  • gap: Gap betweens bars.
  • ticks_gap: Gap between ticks.
  • ticks_count: Number of ticks.
  • border_padding: Border padding.
  • border_width: Border width.
  • width: Bars width.
  • height: Bars height.
  • vertical: True: draw bar vertically, false: horizontally.
screen
A screen. Fields
  • coords: The screen coordinates. Immutable.
  • workarea: The screen workarea, i.e. without statusbar.
statusbar
Statusbar object. Fields
  • screen: Screen number.
  • align: The alignment.
  • fg: Foreground color.
  • bg: Background color.
  • position: The position.
tag
Tag object. Fields
  • name: Tag name.
  • screen: Screen number of the tag.
  • layout: Tag layout.
  • selected: True if the client is selected to be viewed.
  • mwfact: Master width factor.
  • nmaster: Number of master windows.
  • ncol: Number of column for slave windows.
taglist
Taglist widget. Fields
  • label: Function used to get the string to display as the tag title. It gets the tag as argument, and must return a string.
tasklist
Tasklist widget. Fields
  • show_icons: Show icons near client title.
  • label: Function used to get the string to display as the window title. It gets the client and a screen number as argument, and must return a string.
textbox
Textbox widget. Fields
  • text: The text to display.
  • width: The width of the textbox. Set to 0 for auto.
titlebar
Titlebar object. Fields
  • client: The client attached to this titlebar.
  • align: Alignment relative to the client.
  • border_width: Border width.
  • border_color: Border color.
  • fg: Foreground color.
  • bg: Background color.
  • position: Position.
widget
Generic widget. Fields
  • visible: The widget visibility.
  • name: The widget name.

Valid XHTML 1.0!