Module capi

capi: awesome C API

Author:

Julien Danjou <julien@danjou.info>

Copyright© 2008 Julien Danjou

Functions

awesome.exec (arg1) Execute another application, probably a window manager, to replace awesome.
awesome.quit () Quit awesome.
awesome.restart () Restart awesome.
button (arg1, arg2, arg3, arg4) Create a new mouse button bindings.
client.buttons (arg1) Get or set mouse buttons bindings for a client.
client.geometry (arg1) Return client geometry.
client.get (arg1) Get all clients into a table.
client.isvisible () Check if a client is visible on its screen.
client.keys (arg1) Get or set keys bindings for a client.
client.kill () Kill a client.
client.lower () Lower a client on bottom of others which are on the same layer.
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.struts (arg1) Return client struts (reserved space at the edge of the screen).
client.swap (arg1) Swap a client with another one.
client.tags (arg1) Access or set the client tags.
client.unmanage () Stop managing a client.
dbus.add_match (arg1, arg2) Add a match rule to match messages going through the message bus.
dbus.release_name (arg1, arg2) Release a D-Bus name.
dbus.remove_match (arg1, arg2) Remove a previously added match rule "by value" (the most recently-added identical rule gets removed).
dbus.request_name (arg1, arg2) Register a D-Bus name to receive message from.
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.clients (arg1) Set the function called on each client list change.
hooks.dbus (arg1) Set the function to be called when a D-Bus event is received.
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.mouse_enter (arg1) Set the function called each time the mouse enter a window.
hooks.mouse_leave (arg1) Set the function called each time the mouse leave a window.
hooks.property (arg1) Set the function called on each client's property change.
hooks.startup_notification (arg1) Set the function called on each startup-notification events This function is called with a table and various fields set to describe the vents.
hooks.tagged (arg1) Set the function called on each client's tags change.
hooks.tags (arg1) Set the function called on each screen tag list change.
hooks.timer (arg1, arg2) Set the function to be called every N seconds.
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.
image (arg1) Create a new image object.
image.argb32 (arg1, arg2, arg3) Create a new image object from ARGB32 data.
image.crop (arg1, arg2, arg3, arg4) Crop an image to the given rectangle.
image.crop_and_scale (arg1, arg2, arg3, arg4, arg5, arg6) Crop the image to the given rectangle and scales it.
image.draw_circle (arg1, arg2, arg3, arg4, arg5, arg6) Draw a circle in an image \lvalua An image.
image.draw_pixel (arg1, arg2, arg3) Draw a pixel in an image \lvalua An image.
image.draw_rectangle (arg1, arg2, arg3, arg4, arg5, arg6) Draw a rectangle in an image \lvalua An image.
image.orientate (arg1) Performs 90 degree rotations on the current image.
image.rotate (arg1) Rotate an image with specified angle radians and return a new image.
image.save (arg1) Saves the image to the given path.
key (arg1, arg2, arg3, arg4) Define a global key binding.
keygrabber.run (arg1) Grab keyboard and read pressed keys, calling callback function at each key pressed.
keygrabber.stop () Stop grabbing the keyboard.
mouse.coords (arg1) Get or set the mouse coords.
mouse.object_under_pointer () Get the client which is under the pointer.
mousegrabber.run (arg1) Grab the mouse pointer and list motions, calling callback function at each motion.
mousegrabber.stop () Stop grabbing the mouse pointer.
progressbar.bar_data_add (arg1, arg2) Add a value to a progressbar bar.
progressbar.bar_properties_set (arg1, arg2) Set various progressbar bars properties:
root.buttons (arg1) Get or set global mouse bindings.
root.cursor (arg1) Set the root cursor.
root.fake_input (arg1, arg2, arg3, arg4, arg5) Send fake events.
root.keys (arg1) Get or set global key bindings.
screen.count () Get the screen count.
screen.padding (arg1) Set or get the screen padding.
screen.tags (arg1) Get or set screen tags.
tag (arg1) Create a new tag.
tag.clients (arg1) Get or set the clients attached to this tag.
wibox (arg1) Create a new wibox.
wibox.buttons (arg1) Get or set mouse buttons bindings to a wibox.
widget (arg1) Create a new widget.
widget.buttons (arg1) Get or set mouse buttons bindings to a widget.

Tables

awesome awesome global table.
button Button object.
client Client object.
graph Graph widget.
image Image object.
imagebox Imagebox widget.
key Key object.
mouse Mouse library.
progressbar Progressbar widget.
screen A screen.
tag Tag object.
textbox Textbox widget.
wibox Wibox object.
widget Generic widget.
wtable Index function of wtable objects.


Functions

awesome.exec (arg1)
Execute another application, probably a window manager, to replace awesome.

Parameters

  • arg1: The command line to execute.
awesome.quit ()
Quit awesome.
awesome.restart ()
Restart awesome.
button (arg1, arg2, arg3, arg4)
Create a new mouse button bindings.

Parameters

  • arg1: A table with modifiers keys, or a button to clone.
  • arg2: A mouse button number, or 0 to match any button.
  • arg3: A function to execute on click events.
  • arg4: A function to execute on release events.

Return value:

A mouse button binding.
client.buttons (arg1)
Get or set mouse buttons bindings for a client.

Parameters

  • arg1: An array of mouse button bindings objects, or nothing.
client.geometry (arg1)
Return client geometry.

Parameters

  • arg1: A table with new coordinates, or none.

Return value:

A table with client coordinates.
client.get (arg1)
Get all clients into a table.

Parameters

  • arg1: An optional screen nunmber.

Return value:

A table with all clients.
client.isvisible ()
Check if a client is visible on its screen.

Return value:

A boolean value, true if the client is visible, false otherwise.
client.keys (arg1)
Get or set keys bindings for a client.

Parameters

  • arg1: An array of key bindings objects, or nothing.
client.kill ()
Kill a client.
client.lower ()
Lower a client on bottom of others which are on the same layer.
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.struts (arg1)
Return client struts (reserved space at the edge of the screen).

Parameters

  • arg1: A table with new strut values, or none.

Return value:

A table with strut values.
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.
dbus.add_match (arg1, arg2)
Add a match rule to match messages going through the message bus.

Parameters

  • arg1: A string indicating if we are using system or session bus.
  • arg2: A string with the name of the match rule.
dbus.release_name (arg1, arg2)
Release a D-Bus name.

Parameters

  • arg1: A string indicating if we are using system or session bus.
  • arg2: A string with the name of the D-Bus name to unregister.

Return value:

True if everything worked fine, false otherwise.
dbus.remove_match (arg1, arg2)
Remove a previously added match rule "by value" (the most recently-added identical rule gets removed).

Parameters

  • arg1: A string indicating if we are using system or session bus.
  • arg2: A string with the name of the match rule.
dbus.request_name (arg1, arg2)
Register a D-Bus name to receive message from.

Parameters

  • arg1: A string indicating if we are using system or session bus.
  • arg2: A string with the name of the D-Bus name to register. Note that org.awesome is registered by default.

Return value:

True if everything worked fine, false otherwise.
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.clients (arg1)
Set the function called on each client list change. This function is called without any argument.

Parameters

  • arg1: A function to call on each client list change.
hooks.dbus (arg1)
Set the function to be called when a D-Bus event is received. The first argument passed to this function is the type of the message we receive: signal, method_call, method_return or error. The second argument is the path. The other arguments are a variable list of arguments. The function can return values using pair of type, value. For example: return "s", "hello", "i", 32

Parameters

  • arg1: A function to call on D-Bus events.
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, plus a boolean argument which is true if the client is managed at startup.

Parameters

  • arg1: A function to call on each new client.
hooks.mouse_enter (arg1)
Set the function called each time the mouse enter a 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.mouse_leave (arg1)
Set the function called each time the mouse leave a 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.property (arg1)
Set the function called on each client's property change. This function is called with the client object as argument and the property name.

Parameters

  • arg1: A function to call on each client property update.
hooks.startup_notification (arg1)
Set the function called on each startup-notification events This function is called with a table and various fields set to describe the vents.

Parameters

  • arg1: A function to call on each startup-notification event.
hooks.tagged (arg1)
Set the function called on each client's tags change. This function is called with the client and the tag as argument.

Parameters

  • arg1: A function to call on each client's tags change.
hooks.tags (arg1)
Set the function called on each screen tag list change. This function is called with a screen number as first argument, the tag object as second and the action (add or remove) as third.

Parameters

  • arg1: A function to call on each tag list change.
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.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.
image (arg1)
Create a new image object.

Parameters

  • arg1: The image path.

Return value:

An image object.
image.argb32 (arg1, arg2, arg3)
Create a new image object from ARGB32 data.

Parameters

  • arg1: The image width.
  • arg2: The image height.
  • arg3: The image data as a string in ARGB32 format, or nil to create an empty image.

Return value:

An image object.
image.crop (arg1, arg2, arg3, arg4)
Crop an image to the given rectangle.

Parameters

  • arg1: The top left x coordinate of the rectangle.
  • arg2: The top left y coordinate of the rectangle.
  • arg3: The width of the rectangle.
  • arg4: The height of the rectangle.

Return value:

A cropped image.
image.crop_and_scale (arg1, arg2, arg3, arg4, arg5, arg6)
Crop the image to the given rectangle and scales it.

Parameters

  • arg1: The top left x coordinate of the source rectangle.
  • arg2: The top left y coordinate of the source rectangle.
  • arg3: The width of the source rectangle.
  • arg4: The height of the source rectangle.
  • arg5: The width of the destination rectangle.
  • arg6: The height of the destination rectangle.

Return value:

A cropped image.
image.draw_circle (arg1, arg2, arg3, arg4, arg5, arg6)
Draw a circle in an image \lvalua An image.

Parameters

  • arg1: The x coordinate of the center of the circle
  • arg2: The y coordinate of the center of the circle
  • arg3: The horizontal amplitude (width)
  • arg4: The vertical amplitude (height)
  • arg5: True if the circle should be filled, False otherwise
  • arg6: The color to draw the circle in
image.draw_pixel (arg1, arg2, arg3)
Draw a pixel in an image \lvalua An image.

Parameters

  • arg1: The x coordinate of the pixel to draw
  • arg2: The y coordinate of the pixel to draw
  • arg3: The color to draw the pixel in
image.draw_rectangle (arg1, arg2, arg3, arg4, arg5, arg6)
Draw a rectangle in an image \lvalua An image.

Parameters

  • arg1: The x coordinate of the rectangles top left corner
  • arg2: The y coordinate of the rectangles top left corner
  • arg3: The width of the rectangle
  • arg4: The height of the rectangle
  • arg5: True if the rectangle should be filled, False otherwise
  • arg6: The color to draw the rectangle in
image.orientate (arg1)
Performs 90 degree rotations on the current image. Passing 0 orientation does not rotate, 1 rotates clockwise by 90 degree, 2, rotates clockwise by 180 degrees, 3 rotates clockwise by 270 degrees.

Parameters

  • arg1: The rotation to perform.
image.rotate (arg1)
Rotate an image with specified angle radians and return a new image.

Parameters

  • arg1: The angle in radians.

Return value:

A rotated image.
image.save (arg1)
Saves the image to the given path. The file extension (e.g. .png or .jpg) will affect the output format.

Parameters

  • arg1: The image path.
key (arg1, arg2, arg3, arg4)
Define a global key binding. This key binding will always be available.

Parameters

  • arg1: A table with modifier keys: can be Control or Ctrl, Shift, Lock, Mod1, Mod2, Mod3, Mod4, Mod5 or Any.
  • arg2: A key name.
  • arg3: A function to execute on key press.
  • arg4: A function to execute on key release.

Return value:

The key.
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 3 arguments: a table containing modifiers keys, a string with the key pressed and a string with eithe "press" or "release" to indicate the event type.

Parameters

  • arg1: A callback function as described above.
keygrabber.stop ()
Stop grabbing the keyboard.
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.
mouse.object_under_pointer ()
Get the client which is under the pointer.

Return value:

A client or nil.
mousegrabber.run (arg1)
Grab the mouse pointer and list motions, calling callback function at each motion. The callback function must return a boolean value: true to continue grabbing, false to stop. The function is called with one argument: a table containing modifiers pointer coordinates.

Parameters

  • arg1: A callback function as described above.
mousegrabber.stop ()
Stop grabbing the mouse pointer.
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.
root.buttons (arg1)
Get or set global mouse bindings. This binding will be available when you'll click on root window.

Parameters

  • arg1: An array of mouse button bindings objects, or nothing.

Return value:

The array of mouse button bindings objects.
root.cursor (arg1)
Set the root cursor.

Parameters

  • arg1: A X cursor name.
root.fake_input (arg1, arg2, arg3, arg4, arg5)
Send fake events. Usually the current focused client will get it.

Parameters

  • arg1: The event type: key_press, key_release, button_press, button_release or motion_notify.
  • arg2: The detail: in case of a key event, this is the keycode to send, in case of a button event this is the number of the button. In case of a motion event, this is a boolean value which if true make the coordinates relatives.
  • arg3: In case of a motion event, this is the X coordinate.
  • arg4: In case of a motion event, this is the Y coordinate.
  • arg5: In case of a motion event, this is the screen number to move on. If not specified, the current one is used.
root.keys (arg1)
Get or set global key bindings. This binding will be available when you'll press keys on root window.

Parameters

  • arg1: An array of key bindings objects, or nothing.

Return value:

The array of key bindings objects of this client.
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.
tag (arg1)
Create a new tag.

Parameters

  • arg1: A name.

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.
wibox (arg1)
Create a new wibox.

Parameters

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

Return value:

A brand new wibox.
wibox.buttons (arg1)
Get or set mouse buttons bindings to a wibox.

Parameters

  • arg1: An array of mouse button bindings objects, or nothing.
widget (arg1)
Create a new widget.

Parameters

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

Return value:

A brand new widget.
widget.buttons (arg1)
Get or set mouse buttons bindings to a widget.

Parameters

  • arg1: An array of mouse button bindings objects, or nothing.

Tables

awesome
awesome global table. Fields
  • font: The default font.
  • conffile: The configuration file which has been loaded.
button
Button object. Fields
  • press: The function called when button press event is received.
  • release: The function called when button release event is received.
  • button: The mouse button number, or 0 for any button.
  • modifiers: The modifier key table that should be pressed while the button is pressed.
client
Client object. Fields
  • id: The window X id.
  • name: The client title.
  • skip_taskbar: True if the client does not want to be in taskbar.
  • type: The window type (desktop, normal, dock, …).
  • 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.
  • screen: Client screen number.
  • hide: Define if the client must be hidden, i.e. never mapped, invisible in taskbar.
  • minimized: Define it the client must be iconify, i.e. only visible in taskbar.
  • size_hints_honor: 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.
  • content: An image representing the client window content (screenshot).
  • focus: The focused client.
  • opacity: The client opacity between 0 and 1.
  • ontop: The client is on top of every other windows.
  • above: The client is above normal windows.
  • below: The client is below normal windows.
  • fullscreen: The client is fullscreen or not.
  • maximized_horizontal: The client is maximized horizontally or not.
  • maximized_vertical: The client is maximized vertically or not.
  • transient_for: Return the client the window is transient for.
  • group_id: Identification unique to a group of windows.
  • leader_id: Identification unique to windows spawned by the same command.
  • size_hints: A table with size hints of the client: user_position, user_size, program_position, program_size, etc.
graph
Graph widget. Fields
  • plot_properties_set: A function to set plot properties.
  • plot_data_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.
image
Image object. Fields
  • width: The image width.
  • height: The image height.
imagebox
Imagebox widget. Fields
  • image: The image to display.
  • bg: The background color to use.
key
Key object. Fields
  • key: The key to press to triggers an event.
  • keysym: Same as key, but return the name of the key symbol. It can be identical to key, but for characters like '.' it will return 'period'.
  • modifiers: The modifier key that should be pressed while the key is pressed. An array with all the modifiers. Valid modifiers are: Any, Mod1, Mod2, Mod3, Mod4, Mod5, Shift, Lock and Control.
  • press: The function which is called when the key combination is pressed.
  • release: The function which is called when the key combination is released.
mouse
Mouse library. Fields
  • coords: Mouse coordinates.
  • screen: Mouse screen number.
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 wiboxes.
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.
textbox
Textbox widget. Fields
  • text: The text to display.
  • width: The width of the textbox. Set to 0 for auto.
  • wrap: The wrap mode: word, char, word_char.
  • ellipsize: The ellipsize mode: start, middle or end.
  • border_width: The border width to draw around.
  • border_color: The border color.
  • align: Text alignment, left, center or right.
  • margin: Method to pass text margin: a table with top, left, right and bottom keys.
  • bg: Background color.
  • bg_image: Background image.
  • bg_align: Background image alignment, left, center, right, bottom, top or middle
  • bg_resize: Background resize.
wibox
Wibox object. Fields
  • screen: Screen number.
  • client: The client attached to (titlebar).
  • border_width: Border width.
  • border_color: Border color.
  • align: The alignment.
  • fg: Foreground color.
  • bg: Background color.
  • bg_image: Background image.
  • position: The position.
  • ontop: On top of other windows.
  • cursor: The mouse cursor.
  • visible: Visibility.
  • orientation: The drawing orientation: east, north or south.
  • widgets: An array with all widgets drawn on this wibox.
  • opacity: The opacity of the wibox, between 0 and 1.
  • mouse_enter: A function to execute when the mouse enter the widget.
  • mouse_leave: A function to execute when the mouse leave the widget.
widget
Generic widget. Fields
  • align: The widget alignment.
  • visible: The widget visibility.
  • mouse_enter: A function to execute when the mouse enter the widget.
  • mouse_leave: A function to execute when the mouse leave the widget.
wtable
Index function of wtable objects.

Valid XHTML 1.0!