File capi.lua
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.