From 26f15a13f3c78babf1d448ac5608e8affcf4f6d8 Mon Sep 17 00:00:00 2001 From: Julian Wollrath Date: Fri, 27 Feb 2015 00:24:23 +0100 Subject: [PATCH] Document C API directly in the C source code v2: Add available signals to the docs. Signed-off-by: Julian Wollrath --- CMakeLists.txt | 2 +- awesomeConfig.cmake | 2 +- common/luaobject.c | 27 ++- dbus.c | 88 ++++----- docs/capi/awesome.lua.in | 90 --------- docs/capi/button.lua.in | 31 --- docs/capi/client.lua.in | 156 --------------- docs/capi/dbus.lua.in | 56 ------ docs/capi/drawable.lua.in | 43 ---- docs/capi/drawin.lua.in | 76 -------- docs/capi/key.lua.in | 39 ---- docs/capi/keygrabber.lua.in | 39 ---- docs/capi/mouse.lua.in | 25 --- docs/capi/mousegrabber.lua.in | 24 --- docs/capi/root.lua.in | 51 ----- docs/capi/screen.lua.in | 40 ---- docs/capi/selection.lua.in | 10 - docs/capi/tag.lua.in | 41 ---- docs/config.ld | 15 +- keygrabber.c | 47 +++-- luaa.c | 104 ++++++---- mouse.c | 37 +++- mousegrabber.c | 27 +-- objects/button.c | 42 ++++ objects/client.c | 355 +++++++++++++++++++++++++++++----- objects/drawable.c | 66 ++++++- objects/drawin.c | 92 ++++++++- objects/key.c | 45 +++++ objects/screen.c | 35 +++- objects/tag.c | 57 +++++- objects/window.c | 43 +++- root.c | 84 ++++---- selection.c | 13 ++ spawn.c | 39 +++- xkb.c | 36 ++-- 35 files changed, 991 insertions(+), 986 deletions(-) delete mode 100644 docs/capi/awesome.lua.in delete mode 100644 docs/capi/button.lua.in delete mode 100644 docs/capi/client.lua.in delete mode 100644 docs/capi/dbus.lua.in delete mode 100644 docs/capi/drawable.lua.in delete mode 100644 docs/capi/drawin.lua.in delete mode 100644 docs/capi/key.lua.in delete mode 100644 docs/capi/keygrabber.lua.in delete mode 100644 docs/capi/mouse.lua.in delete mode 100644 docs/capi/mousegrabber.lua.in delete mode 100644 docs/capi/root.lua.in delete mode 100644 docs/capi/screen.lua.in delete mode 100644 docs/capi/selection.lua.in delete mode 100644 docs/capi/tag.lua.in diff --git a/CMakeLists.txt b/CMakeLists.txt index 41e5c3d14..7554859c8 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -230,7 +230,7 @@ if(GENERATE_DOC) file(MAKE_DIRECTORY ${BUILD_DIR}/lib) endif() - file(GLOB_RECURSE AWE_LUA_FILES ${BUILD_DIR}/lib/*.lua ${AWE_DOC_DIR}/capi/*.lua) + file(GLOB_RECURSE AWE_LUA_FILES ${BUILD_DIR}/lib/*.lua) file(GLOB_RECURSE AWE_MD_FILES ${AWE_DOC_DIR}/*.md) add_custom_target(ldoc ALL diff --git a/awesomeConfig.cmake b/awesomeConfig.cmake index 7a391b11d..c48d9e970 100644 --- a/awesomeConfig.cmake +++ b/awesomeConfig.cmake @@ -288,6 +288,7 @@ file(GLOB_RECURSE awesome_lua_configure_files RELATIVE ${SOURCE_DIR}/lib/*.lua ${SOURCE_DIR}/themes/*/*.lua) set(AWESOME_CONFIGURE_FILES + ${awesome_c_configure_files} ${awesome_lua_configure_files} config.h docs/config.ld @@ -316,5 +317,4 @@ foreach(file ${AWESOME_ADDITIONAL_FILES}) endforeach() #}}} - # vim: filetype=cmake:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:textwidth=80:foldmethod=marker diff --git a/common/luaobject.c b/common/luaobject.c index e8a1f7300..8c5a68b7c 100644 --- a/common/luaobject.c +++ b/common/luaobject.c @@ -19,6 +19,14 @@ * */ +/** Handling of signals. + * + * This can not be used as a standalone class, but is instead referenced + * explicitely in the classes, where it can be used. In the respective classes, + * it then can be used via `classname:connect_signal(...)` etc. + * @classmod signals + */ + #include "common/luaobject.h" #include "common/backtrace.h" @@ -160,6 +168,11 @@ luaA_settype(lua_State *L, lua_class_t *lua_class) return 1; } +/** Add a signal. + * @tparam string name A signal name. + * @tparam func func A function to call when the signal is emitted. + * @function connect_signal + */ void luaA_object_connect_signal(lua_State *L, int oud, const char *name, lua_CFunction fn) @@ -168,6 +181,11 @@ luaA_object_connect_signal(lua_State *L, int oud, luaA_object_connect_signal_from_stack(L, oud, name, -1); } +/** Remove a signal. + * @tparam string name A signal name. + * @tparam func func A function to remove. + * @function disconnect_signal + */ void luaA_object_disconnect_signal(lua_State *L, int oud, const char *name, lua_CFunction fn) @@ -242,11 +260,10 @@ signal_object_emit(lua_State *L, signal_array_t *arr, const char *name, int narg lua_pop(L, nargs); } -/** Emit a signal to an object. - * \param L The Lua VM state. - * \param oud The object index on the stack. - * \param name The name of the signal. - * \param nargs The number of arguments to pass to the called functions. +/** Emit a signal. + * @tparam string name A signal name. + * @param[opt] ... Various arguments. + * @function emit_signal */ void luaA_object_emit_signal(lua_State *L, int oud, diff --git a/dbus.c b/dbus.c index f606cd65f..afeaf914d 100644 --- a/dbus.c +++ b/dbus.c @@ -19,6 +19,13 @@ * */ +/** awesome D-Bus API + * @author Julien Danjou <julien@danjou.info> + * @copyright 2008-2009 Julien Danjou + * @release @AWESOME_VERSION@ + * @module dbus + */ + #include "config.h" #include "dbus.h" @@ -666,12 +673,11 @@ a_dbus_bus_getbyname(const char *name) } /** Register a D-Bus name to receive message from. - * \param L The Lua VM state. - * \return The number of elements pushed on stack. - * \luastack - * \lparam A string indicating if we are using system or session bus. - * \lparam A string with the name of the D-Bus name to register. - * \lreturn True if everything worked fine, false otherwise. + * + * @param bus A string indicating if we are using system or session bus. + * @param name A string with the name of the D-Bus name to register. + * @return True if everything worked fine, false otherwise. + * @function request_name */ static int luaA_dbus_request_name(lua_State *L) @@ -684,12 +690,11 @@ luaA_dbus_request_name(lua_State *L) } /** Release a D-Bus name. - * \param L The Lua VM state. - * \return The number of elements pushed on stack. - * \luastack - * \lparam A string indicating if we are using system or session bus. - * \lparam A string with the name of the D-Bus name to unregister. - * \lreturn True if everything worked fine, false otherwise. + * + * @param bus A string indicating if we are using system or session bus. + * @param name A string with the name of the D-Bus name to unregister. + * @return True if everything worked fine, false otherwise. + * @function release_name */ static int luaA_dbus_release_name(lua_State *L) @@ -702,11 +707,10 @@ luaA_dbus_release_name(lua_State *L) } /** Add a match rule to match messages going through the message bus. - * \param L The Lua VM state. - * \return The number of elements pushed on stack. - * \luastack - * \lparam A string indicating if we are using system or session bus. - * \lparam A string with the name of the match rule. + * + * @param bus A string indicating if we are using system or session bus. + * @param name A string with the name of the match rule. + * @function add_match */ static int luaA_dbus_add_match(lua_State *L) @@ -726,11 +730,10 @@ luaA_dbus_add_match(lua_State *L) /** Remove a previously added match rule "by value" * (the most recently-added identical rule gets removed). - * \param L The Lua VM state. - * \return The number of elements pushed on stack. - * \luastack - * \lparam A string indicating if we are using system or session bus. - * \lparam A string with the name of the match rule. + * + * @param bus A string indicating if we are using system or session bus. + * @param name A string with the name of the match rule. + * @function remove_match */ static int luaA_dbus_remove_match(lua_State *L) @@ -749,11 +752,10 @@ luaA_dbus_remove_match(lua_State *L) } /** Add a signal receiver on the D-Bus. - * \param L The Lua VM state. - * \return The number of elements pushed on stack. - * \luastack - * \lparam A string with the interface name. - * \lparam The function to call. + * + * @param interface A string with the interface name. + * @param func The function to call. + * @function connect_signal */ static int luaA_dbus_connect_signal(lua_State *L) @@ -772,12 +774,11 @@ luaA_dbus_connect_signal(lua_State *L) return 0; } -/** Add a signal receiver on the D-Bus. - * \param L The Lua VM state. - * \return The number of elements pushed on stack. - * \luastack - * \lparam A string with the interface name. - * \lparam The function to call. +/** Remove a signal receiver on the D-Bus. + * + * @param interface A string with the interface name. + * @param func The function to call. + * @function disconnect_signal */ static int luaA_dbus_disconnect_signal(lua_State *L) @@ -791,18 +792,17 @@ luaA_dbus_disconnect_signal(lua_State *L) } /** Emit a signal on the D-Bus. - * \param L The Lua VM state. - * \return The number of elements pushed on stack. - * \luastack - * \lparam A string indicating if we are using system or session bus. - * \lparam A string with the dbus path. - * \lparam A string with the dbus interface. - * \lparam A string with the dbus method name. - * \lparam type of 1st arg - * \lparam 1st arg value - * \lparam type of 2nd arg - * \lparam 2nd arg value + * + * @param bus A string indicating if we are using system or session bus. + * @param path A string with the dbus path. + * @param interface A string with the dbus interface. + * @param method A string with the dbus method name. + * @param type_1st_arg type of 1st argument + * @param value_1st_arg value of 1st argument + * @param type_2nd_arg type of 2nd argument + * @param value_2nd_arg value of 2nd argument * ... etc + * @function emit_signal */ static int luaA_dbus_emit_signal(lua_State *L) diff --git a/docs/capi/awesome.lua.in b/docs/capi/awesome.lua.in deleted file mode 100644 index 5afbcad75..000000000 --- a/docs/capi/awesome.lua.in +++ /dev/null @@ -1,90 +0,0 @@ ---- awesome core API --- @author Julien Danjou <julien@danjou.info> --- @copyright 2008-2009 Julien Danjou --- @release @AWESOME_VERSION@ --- @module awesome - ---- awesome global table. --- --- @field version The version of awesome. --- @field release The release name of awesome. --- @field conffile The configuration file which has been loaded. --- @field startup True if we are still in startup, false otherwise. --- @field startup_errors Error message for errors that occured during startup. --- @field composite_manager_running True if a composite manager is running. --- @table awesome - ---- Quit awesome. --- --- @function quit - ---- Execute another application, probably a window manager, to replace --- awesome. --- --- @param cmd The command line to execute. --- @function exec - ---- Restart awesome. --- --- @name restart --- @class function - ---- Spawn a program. --- --- @param cmd The command to launch. Either a string or a table of strings. --- @param use_sn Use startup-notification, true or false, default to true. --- @return Process ID if everything is OK, or an error string if an error occured. - ---- Load an image --- --- @param name The file name --- @return A cairo image surface as light user datum --- @function load_image - ---- Register a new xproperty. --- --- @param name The name of the X11 property --- @param type One of "string", "number" or "boolean" --- @function register_xproperty - ---- Change a xproperty. --- --- @param name The name of the X11 property --- @param value The new value for the property --- @function set_xproperty - ---- Get the value of a xproperty. --- --- @param name The name of the X11 property --- @function get_xproperty - ---- Add a global signal. --- --- @param name A string with the event name. --- @param func The function to call. --- @function connect_signal - ---- Remove a global signal. --- --- @param name A string with the event name. --- @param func The function to call. --- @function disconnect_signal - ---- Emit a global signal. --- --- @param name A string with the event name. --- @param ... Signal arguments. --- @function emit_signal - ---- Switch keyboard layout group. --- @param num keyboard layout number, integer from 0 to 3 --- @function xkb_set_layout_group - ---- Get current keyboard layout group. --- @return current keyboard layout number --- @function xkb_get_layout_group - - ---- Get description of configured layouts --- @return String with description of configured layouts --- @function xkb_get_group_names diff --git a/docs/capi/button.lua.in b/docs/capi/button.lua.in deleted file mode 100644 index 7c0c8beda..000000000 --- a/docs/capi/button.lua.in +++ /dev/null @@ -1,31 +0,0 @@ ---- awesome button API --- @author Julien Danjou <julien@danjou.info> --- @copyright 2008-2009 Julien Danjou --- @release @AWESOME_VERSION@ --- @classmod button - ---- Button object. --- --- @tfield int button The mouse button number, or 0 for any button. --- @tfield table modifiers The modifier key table that should be pressed while the --- button is pressed. --- @table button - ---- Add a signal. --- @tparam string name A signal name. --- @tparam func func A function to call when the signal is emitted. --- @function connect_signal - ---- Remove a signal. --- @tparam string name A signal name. --- @tparam func func A function to remove. --- @function disconnect_signal - ---- Emit a signal. --- @tparam string name A signal name. --- @param[opt] ... Various arguments. --- @function emit_signal - ---- Get the number of instances. --- @treturn int The number of button objects alive. --- @function instances diff --git a/docs/capi/client.lua.in b/docs/capi/client.lua.in deleted file mode 100644 index 522c54e40..000000000 --- a/docs/capi/client.lua.in +++ /dev/null @@ -1,156 +0,0 @@ ---- awesome client API --- @author Julien Danjou <julien@danjou.info> --- @copyright 2008-2009 Julien Danjou --- @release @AWESOME_VERSION@ --- @classmod client - ---- Client object. --- --- @field window The X window id. --- @field name The client title. --- @field skip_taskbar True if the client does not want to be in taskbar. --- @field type The window type (desktop, normal, dock, …). --- @field class The client class. --- @field instance The client instance. --- @field pid The client PID, if available. --- @field role The window role, if available. --- @field machine The machine client is running on. --- @field icon_name The client name when iconified. --- @field icon The client icon. --- @field screen Client screen. --- @field hidden Define if the client must be hidden, i.e. never mapped, --- invisible in taskbar. --- @field minimized Define it the client must be iconify, i.e. only visible in --- taskbar. --- @field size_hints_honor Honor size hints, i.e. respect size ratio. --- @field border_width The client border width. --- @field border_color The client border color. --- @field urgent The client urgent state. --- @field content An image representing the client window content (screenshot). --- @field focus The focused client. --- @field opacity The client opacity between 0 and 1. --- @field ontop The client is on top of every other windows. --- @field above The client is above normal windows. --- @field below The client is below normal windows. --- @field fullscreen The client is fullscreen or not. --- @field maximized The client is maximized (horizontally and vertically) or not. --- @field maximized_horizontal The client is maximized horizontally or not. --- @field maximized_vertical The client is maximized vertically or not. --- @field transient_for The client the window is transient for. --- @field group_window Window identification unique to a group of windows. --- @field leader_window Identification unique to windows spawned by the same command. --- @field size_hints A table with size hints of the client: user_position, --- user_size, program_position, program_size, etc. --- @field sticky Set the client sticky, i.e. available on all tags. --- @field modal Indicate if the client is modal. --- @field focusable True if the client can receive the input focus. --- @field shape_bounding The client's bounding shape as set by awesome as a (native) cairo surface. --- @field shape_clip The client's clip shape as set by awesome as a (native) cairo surface. --- @field shape_client_bounding The client's bounding shape as set by the program as a (native) cairo surface. --- @field shape_client_clip The client's clip shape as set by the program as a (native) cairo surface. --- @field startup_id The FreeDesktop StartId. --- @field valid If the client that this object refers to is still managed by awesome. --- @table client - ---- Get all clients into a table. --- --- @param[opt] screen A screen number. --- @return A table with all clients. --- @function get - ---- Check if a client is visible on its screen. --- --- @return A boolean value, true if the client is visible, false otherwise. --- @function isvisible - ---- Return client geometry. --- --- @param arg1 A table with new coordinates, or none. --- @return A table with client coordinates. --- @function geometry - ---- Apply size hints to a size. --- @param width Desired width of client --- @param height Desired height of client --- @return Actual width of client --- @return Actual height of client --- @name apply_size_hints --- @class function - ---- Return client struts (reserved space at the edge of the screen). --- --- @param struts A table with new strut values, or none. --- @return A table with strut values. --- @function struts - ---- Get or set mouse buttons bindings for a client. --- --- @param buttons_table An array of mouse button bindings objects, or nothing. --- @return A table with all buttons. --- @function buttons - ---- Get or set keys bindings for a client. --- --- @param keys_table An array of key bindings objects, or nothing. --- @return A table with all keys. --- @function keys - ---- Access or set the client tags. --- --- @param tags_table A table with tags to set, or none to get the current tags table. --- @return A table with all tags. --- @function tags - ---- Kill a client. --- --- @function kill - ---- Swap a client with another one in global client list. --- @client A client to swap with. --- @function swap - ---- Raise a client on top of others which are on the same layer. --- --- @function raise - ---- Lower a client on bottom of others which are on the same layer. --- --- @function lower - ---- Stop managing a client. --- --- @function unmanage - ---- Change a xproperty. --- --- @param name The name of the X11 property --- @param value The new value for the property --- @function set_xproperty - ---- Get the value of a xproperty. --- --- @param name The name of the X11 property --- @function get_xproperty - ---- Add a signal. --- --- @param name A signal name. --- @param func A function to call when the signal is emitted. --- @function connect_signal - ---- Remove a signal. --- --- @param name A signal name. --- @param func A function to remove. --- @function disconnect_signal - ---- Emit a signal. --- --- @param name A signal name. --- @param[opt] ... Various arguments. --- @function emit_signal - ---- Get the number of instances. --- --- @return The number of client objects alive. --- @function instances diff --git a/docs/capi/dbus.lua.in b/docs/capi/dbus.lua.in deleted file mode 100644 index a55f43b06..000000000 --- a/docs/capi/dbus.lua.in +++ /dev/null @@ -1,56 +0,0 @@ ---- awesome D-Bus API --- @author Julien Danjou <julien@danjou.info> --- @copyright 2008-2009 Julien Danjou --- @release @AWESOME_VERSION@ --- @module dbus - ---- Register a D-Bus name to receive message from. --- --- @param bus A string indicating if we are using system or session bus. --- @param name A string with the name of the D-Bus name to register. --- @return True if everything worked fine, false otherwise. --- @function request_name - ---- Release a D-Bus name. --- --- @param bus A string indicating if we are using system or session bus. --- @param name A string with the name of the D-Bus name to unregister. --- @return True if everything worked fine, false otherwise. --- @function release_name - ---- Add a match rule to match messages going through the message bus. --- --- @param bus A string indicating if we are using system or session bus. --- @param name A string with the name of the match rule. --- @function add_match - ---- Remove a previously added match rule "by value" --- (the most recently-added identical rule gets removed). --- --- @param bus A string indicating if we are using system or session bus. --- @param name A string with the name of the match rule. --- @function remove_match - ---- Add a signal receiver on the D-Bus. --- --- @param interface A string with the interface name. --- @param func The function to call. --- @function connect_signal - ---- Remove a signal receiver on the D-Bus. --- --- @param interface A string with the interface name. --- @param func The function to call. --- @function disconnect_signal - --- Emit a signal on the D-Bus. --- @param bus A string indicating if we are using system or session bus. --- @param path A string with the dbus path. --- @param interface A string with the dbus interface. --- @param method A string with the dbus method name. --- @param type_1st_arg type of 1st argument --- @param value_1st_arg value of 1st argument --- @param type_2nd_arg type of 2nd argument --- @param value_2nd_arg value of 2nd argument --- ... etc --- @function emit_signal diff --git a/docs/capi/drawable.lua.in b/docs/capi/drawable.lua.in deleted file mode 100644 index 2d322b250..000000000 --- a/docs/capi/drawable.lua.in +++ /dev/null @@ -1,43 +0,0 @@ ---- awesome drawable API --- @author Uli Schlachter <psychon@znc.in> --- @copyright 2012 Uli Schlachter --- @release @AWESOME_VERSION@ --- @classmod drawable - ---- Drawable object. --- --- @field surface The drawable's cairo surface. --- @function drawable - ---- Get drawable geometry. The geometry consists of x, y, width and height. --- --- @return A table with drawable coordinates and geometry. --- @function geometry - ---- Refresh the drawable. When you are drawing to the surface, you have --- call this function when you are done to make the result visible. --- --- @function refresh - ---- Add a signal. --- --- @param name A signal name. --- @param func A function to call when the signal is emitted. --- @function connect_signal - ---- Remove a signal. --- --- @param name A signal name. --- @param func A function to remove. --- @function disconnect_signal - ---- Emit a signal. --- --- @param name A signal name. --- @param[opt] ... Various arguments. --- @function emit_signal - ---- Get the number of instances. --- --- @return The number of drawable objects alive. --- @function instances diff --git a/docs/capi/drawin.lua.in b/docs/capi/drawin.lua.in deleted file mode 100644 index f100a8d35..000000000 --- a/docs/capi/drawin.lua.in +++ /dev/null @@ -1,76 +0,0 @@ ---- awesome drawin API --- @author Julien Danjou <julien@danjou.info> --- @copyright 2008-2009 Julien Danjou --- @release @AWESOME_VERSION@ --- @classmod drawin - ---- Drawin object. --- --- @field border_width Border width. --- @field border_color Border color. --- @field ontop On top of other windows. --- @field cursor The mouse cursor. --- @field visible Visibility. --- @field opacity The opacity of the drawin, between 0 and 1. --- @field type The window type (desktop, normal, dock, …). --- @field x The x coordinates. --- @field y The y coordinates. --- @field width The width of the drawin. --- @field height The height of the drawin. --- @field drawable The drawin's drawable. --- @field window The X window id. --- @field shape_bounding The drawin's bounding shape as a (native) cairo surface. --- @field shape_clip The drawin's clip shape as a (native) cairo surface. --- @table drawin - ---- Get or set mouse buttons bindings to a drawin. --- --- @param buttons_table A table of buttons objects, or nothing. --- @function buttons - ---- Get or set drawin struts. --- --- @param strut A table with new strut, or nothing --- @return The drawin strut in a table. --- @function struts - ---- Get or set drawin geometry. That's the same as accessing or setting the x, y, width or height --- properties of a drawin. --- --- @param A table with coordinates to modify. --- @return A table with drawin coordinates and geometry. --- @function geometry - ---- Change a xproperty. --- --- @param name The name of the X11 property --- @param value The new value for the property --- @function set_xproperty - ---- Get the value of a xproperty. --- --- @param name The name of the X11 property --- @function get_xproperty - ---- Add a signal. --- --- @param name A signal name. --- @param func A function to call when the signal is emitted. --- @function connect_signal - ---- Remove a signal. --- --- @param name A signal name. --- @param func A function to remove. --- @function disconnect_signal - ---- Emit a signal. --- --- @param name A signal name. --- @param[opt] ... Various arguments. --- @function emit_signal - ---- Get the number of instances. --- --- @return The number of drawin objects alive. --- @function instances diff --git a/docs/capi/key.lua.in b/docs/capi/key.lua.in deleted file mode 100644 index 6cd52e04c..000000000 --- a/docs/capi/key.lua.in +++ /dev/null @@ -1,39 +0,0 @@ ---- awesome key API --- @author Julien Danjou <julien@danjou.info> --- @copyright 2008-2009 Julien Danjou --- @release @AWESOME_VERSION@ --- @classmod key - ---- Key object. --- --- @tfield string key The key to trigger an event. --- @tfield string 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'. --- @tfield table 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. --- @table key - ---- Add a signal. --- --- @tparam string name A signal name. --- @tparam function func A function to call when the signal is emitted. --- @function connect_signal - ---- Remove a signal. --- --- @tparam string name A signal name. --- @tparam function func A function to remove. --- @function disconnect_signal - ---- Emit a signal. --- --- @tparam string name A signal name. --- @param[opt] ... Various arguments. --- @function emit_signal - ---- Get the number of instances. --- --- @treturn number The number of key objects alive. --- @function instances diff --git a/docs/capi/keygrabber.lua.in b/docs/capi/keygrabber.lua.in deleted file mode 100644 index 00b082197..000000000 --- a/docs/capi/keygrabber.lua.in +++ /dev/null @@ -1,39 +0,0 @@ ---- awesome keygrabber API --- @author Julien Danjou <julien@danjou.info> --- @copyright 2008-2009 Julien Danjou --- @release @AWESOME_VERSION@ --- @module keygrabber - ---- --- Grab keyboard input and read pressed keys, calling a callback function at --- each keypress, until `keygrabber.stop` is called. --- The callback function receives three arguments: --- --- * a table containing modifiers keys --- * a string with the pressed key --- * a string with either "press" or "release" to indicate the event type. --- --- @param callback A callback function as described above. --- @function run --- @usage The following function can be bound to a key, and will be used to --- resize a client using keyboard. --- --- function resize(c) --- keygrabber.run(function(mod, key, event) --- if event == "release" then return end --- --- if key == 'Up' then awful.client.moveresize(0, 0, 0, 5, c) --- elseif key == 'Down' then awful.client.moveresize(0, 0, 0, -5, c) --- elseif key == 'Right' then awful.client.moveresize(0, 0, 5, 0, c) --- elseif key == 'Left' then awful.client.moveresize(0, 0, -5, 0, c) --- else keygrabber.stop() --- end --- end) --- end - ---- Stop grabbing the keyboard. --- @function stop - ---- Check if the keygrabber is running. --- @return A boolean value, true if running, false otherwise. --- @function isrunning diff --git a/docs/capi/mouse.lua.in b/docs/capi/mouse.lua.in deleted file mode 100644 index cc8aef9f5..000000000 --- a/docs/capi/mouse.lua.in +++ /dev/null @@ -1,25 +0,0 @@ ---- awesome mouse API --- @author Julien Danjou <julien@danjou.info> --- @copyright 2008-2009 Julien Danjou --- @release @AWESOME_VERSION@ --- @module mouse - ---- Mouse library. --- --- @field screen Mouse screen number. --- @table mouse - ---- A table with X and Y coordinates. --- @field x X coordinate. --- @field y Y coordinate. --- @table coords_table - ---- Get or set the mouse coords. --- @tparam coords_table coords_table None or a table with x and y keys as mouse coordinates. --- @tparam boolean silent Disable mouse::enter or mouse::leave events that could be triggered by the pointer when moving. --- @treturn coords_table A table with mouse coordinates. --- @function coords - ---- Get the client or any object which is under the pointer. --- @treturn client.client|nil A client or nil. --- @function object_under_pointer diff --git a/docs/capi/mousegrabber.lua.in b/docs/capi/mousegrabber.lua.in deleted file mode 100644 index 54a2586f3..000000000 --- a/docs/capi/mousegrabber.lua.in +++ /dev/null @@ -1,24 +0,0 @@ ---- awesome mousegrabber API --- @author Julien Danjou <julien@danjou.info> --- @copyright 2008-2009 Julien Danjou --- @release @AWESOME_VERSION@ --- @module mousegrabber - ---- 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. --- --- @param func A callback function as described above. --- @param cursor The name of a X cursor to use while grabbing. --- @function run - ---- Stop grabbing the mouse pointer. --- --- @function stop - ---- Check if the mousegrabber is running. --- --- @return A boolean value, true if running, false otherwise. --- @function isrunning diff --git a/docs/capi/root.lua.in b/docs/capi/root.lua.in deleted file mode 100644 index 1f5f00950..000000000 --- a/docs/capi/root.lua.in +++ /dev/null @@ -1,51 +0,0 @@ ---- awesome root window API --- @author Julien Danjou <julien@danjou.info> --- @copyright 2008-2009 Julien Danjou --- @release @AWESOME_VERSION@ --- @module root - ---- Get or set global mouse bindings. --- This binding will be available when you'll click on root window. --- --- @param button_table An array of mouse button bindings objects, or nothing. --- @return The array of mouse button bindings objects. --- @function buttons - ---- Get or set global key bindings. --- These binding will be available when you press keys on the root window. --- @tparam table|nil keys_array An array of key binding objects, or nothing. --- @return The array of key bindings objects of this client. --- @function keys - ---- Set the root cursor. --- --- @param cursor_name A X cursor name. --- @function cursor - ---- Send fake events. Usually the current focused client will get it. --- --- @param event_type The event type: key_press, key_release, button_press, button_release --- or motion_notify. --- @param detail 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. --- @param x In case of a motion event, this is the X coordinate. --- @param y In case of a motion event, this is the Y coordinate. --- @function fake_input - ---- Get the drawins attached to a screen. --- --- @return A table with all drawins. --- @function drawins - ---- Get the wallpaper as a cairo surface or set it as a cairo pattern. --- --- @param pattern A cairo pattern as light userdata --- @return A cairo surface or nothing. --- @function wallpaper - ---- Get the attached tags. --- --- @return A table with all tags. --- @function tags diff --git a/docs/capi/screen.lua.in b/docs/capi/screen.lua.in deleted file mode 100644 index 745d3a6eb..000000000 --- a/docs/capi/screen.lua.in +++ /dev/null @@ -1,40 +0,0 @@ ---- awesome screen API --- @author Julien Danjou <julien@danjou.info> --- @copyright 2008-2009 Julien Danjou --- @release @AWESOME_VERSION@ --- @classmod screen - ---- Screen is a table where indexes are screen numbers. You can use `screen[1]` --- to get access to the first screen, etc. Alternatively, if RANDR information --- is available, you can use output names for finding screen objects. --- Each screen has a set of properties. --- --- @tfield table geometry The screen coordinates. Immutable. --- @tfield table workarea The screen workarea. --- @tfield int index The screen number. --- @tfield table outputs If RANDR information is available, a list of outputs --- for this screen and their size in mm. --- @table screen - ---- Get the number of screens. --- --- @return The screen count, at least 1. --- @function count - ---- Add a signal to a screen. --- --- @string name A signal name. --- @func func A function to call when the signal is emitted. --- @function connect_signal - ---- Remove a signal to a screen. --- --- @string name A signal name. --- @func func A function to remove --- @function disconnect_signal - ---- Emit a signal to a screen. --- --- @string name A signal name. --- @param[opt] ... Various arguments. --- @function emit_signal diff --git a/docs/capi/selection.lua.in b/docs/capi/selection.lua.in deleted file mode 100644 index c5f13b7a2..000000000 --- a/docs/capi/selection.lua.in +++ /dev/null @@ -1,10 +0,0 @@ ---- awesome selection (clipboard) API --- @author Julien Danjou <julien@danjou.info> --- @copyright 2008-2009 Julien Danjou --- @release @AWESOME_VERSION@ --- @module selection - ---- Get the selection (clipboard) content. --- --- @return A string with the selection (clipboard) content. --- @function selection diff --git a/docs/capi/tag.lua.in b/docs/capi/tag.lua.in deleted file mode 100644 index 1bf4a7e9b..000000000 --- a/docs/capi/tag.lua.in +++ /dev/null @@ -1,41 +0,0 @@ ---- awesome tag API --- @author Julien Danjou <julien@danjou.info> --- @copyright 2008-2009 Julien Danjou --- @release @AWESOME_VERSION@ --- @classmod tag - ---- Tag object. --- --- @field name Tag name. --- @field selected True if the tag is selected to be viewed. --- @field activated True if the tag is active and can be used. --- @table tag - ---- Get or set the clients attached to this tag. --- --- @param clients_table None or a table of clients to set as being tagged with this tag. --- @return A table with the clients attached to this tags. --- @function clients - ---- Add a signal. --- --- @param name A signal name. --- @param func A function to call when the signal is emitted. --- @function connect_signal - ---- Remove a signal. --- --- @param name A signal name. --- @param func A function to remove. --- @function disconnect_signal - ---- Emit a signal. --- --- @param name A signal name. --- @param[opt] ... Various arguments. --- @function emit_signal - ---- Get the number of instances. --- --- @return The number of tag objects alive. --- @function instances diff --git a/docs/config.ld b/docs/config.ld index 707b99d14..c47faf55b 100644 --- a/docs/config.ld +++ b/docs/config.ld @@ -26,6 +26,8 @@ tparam_alias('client', 'client.client') tparam_alias('tag', 'tag') -- Should be default, but is not. Sets up "@tab" => "@tparam table". tparam_alias('tab', 'table') +-- New type for signals +new_type("signal", "Signals", false, "Arguments") -- More fitting section names kind_names={topic='Documentation', module='Libraries'} @@ -34,8 +36,19 @@ kind_names={topic='Documentation', module='Libraries'} sort_modules=true file = { + -- C parts of libraries + '../dbus.c', + '../keygrabber.c', + '../luaa.c', + '../mouse.c', + '../mousegrabber.c', + '../root.c', + '../selection.c', + '../spawn.c', + '../xkb.c', + '../common/luaobject.c', + '../objects/', -- LUA libraries - 'capi/', '../lib/', exclude = { -- exclude these modules, as they do not contain any written diff --git a/keygrabber.c b/keygrabber.c index caef91610..3cb361d18 100644 --- a/keygrabber.c +++ b/keygrabber.c @@ -19,6 +19,13 @@ * */ +/** awesome keygrabber API + * @author Julien Danjou <julien@danjou.info> + * @copyright 2008-2009 Julien Danjou + * @release @AWESOME_VERSION@ + * @module keygrabber + */ + #include #include #include @@ -106,18 +113,31 @@ keygrabber_handlekpress(lua_State *L, xcb_key_press_event_t *e) return true; } -/** Grab keyboard and read pressed keys, calling callback function at each key - * press, until keygrabber.stop is called. - * The function is called with 3 arguments: - * a table containing modifiers keys, a string with the key pressed and a - * string with either "press" or "release" to indicate the event type. +/** Grab keyboard input and read pressed keys, calling a callback function at + * each keypress, until `keygrabber.stop` is called. + * The callback function receives three arguments: * - * \param L The Lua VM state. - * \return The number of elements pushed on stack. + * * a table containing modifiers keys + * * a string with the pressed key + * * a string with either "press" or "release" to indicate the event type. * - * \luastack + * @param callback A callback function as described above. + * @function run + * @usage The following function can be bound to a key, and will be used to + * resize a client using keyboard. * - * \lparam A callback function as described above. + * function resize(c) + * keygrabber.run(function(mod, key, event) + * if event == "release" then return end + * + * if key == 'Up' then awful.client.moveresize(0, 0, 0, 5, c) + * elseif key == 'Down' then awful.client.moveresize(0, 0, 0, -5, c) + * elseif key == 'Right' then awful.client.moveresize(0, 0, 5, 0, c) + * elseif key == 'Left' then awful.client.moveresize(0, 0, -5, 0, c) + * else keygrabber.stop() + * end + * end) + * end */ static int luaA_keygrabber_run(lua_State *L) @@ -137,8 +157,7 @@ luaA_keygrabber_run(lua_State *L) } /** Stop grabbing the keyboard. - * \param L The Lua VM state. - * \return The number of elements pushed on stack. + * @function stop */ int luaA_keygrabber_stop(lua_State *L) @@ -149,10 +168,8 @@ luaA_keygrabber_stop(lua_State *L) } /** Check if keygrabber is running. - * \param L The Lua VM state. - * \return The number of elements pushed on stack. - * \luastack - * \lreturn A boolean value, true if keygrabber is running, false otherwise. + * @function isrunning + * @treturn bool A boolean value, true if keygrabber is running, false otherwise. */ static int luaA_keygrabber_isrunning(lua_State *L) diff --git a/luaa.c b/luaa.c index 2c16152c4..f441e7c7d 100644 --- a/luaa.c +++ b/luaa.c @@ -19,6 +19,14 @@ * */ +/** awesome core API + * + * @author Julien Danjou <julien@danjou.info> + * @copyright 2008-2009 Julien Danjou + * @release @AWESOME_VERSION@ + * @module awesome + */ + #define _GNU_SOURCE #include "luaa.h" @@ -97,8 +105,7 @@ composite_manager_running(void) } /** Quit awesome. - * \param L The Lua VM state. - * \return The number of elements pushed on stack. + * @function quit */ static int luaA_quit(lua_State *L) @@ -109,10 +116,9 @@ luaA_quit(lua_State *L) /** Execute another application, probably a window manager, to replace * awesome. - * \param L The Lua VM state. - * \return The number of elements pushed on stack. - * \luastack - * \lparam The command line to execute. + * + * @param cmd The command line to execute. + * @function exec */ static int luaA_exec(lua_State *L) @@ -126,6 +132,7 @@ luaA_exec(lua_State *L) } /** Restart awesome. + * @function restart */ static int luaA_restart(lua_State *L) @@ -135,10 +142,10 @@ luaA_restart(lua_State *L) } /** Load an image from a given path. - * \param L The Lua VM state. - * \return The number of elements pushed on stack. - * \luastack - * \lparam The command line to execute. + * + * @param name The file name. + * @return A cairo surface as light user datum. + * @function load_image */ static int luaA_load_image(lua_State *L) @@ -196,15 +203,14 @@ luaA_fixups(lua_State *L) } /** awesome global table. - * \param L The Lua VM state. - * \return The number of elements pushed on stack. - * \luastack - * \lfield conffile The configuration file which has been loaded. - * \lfield version The version of awesome. - * \lfield release The release name of awesome. - * \lfield startup True if we are still in startup, false otherwise. - * \lfield startup_errors Error message for errors that occured during startup. - * \lfield composite_manager_running True if a composite manager is running. + * @field version The version of awesome. + * @field release The release name of awesome. + * @field conffile The configuration file which has been loaded. + * @field startup True if we are still in startup, false otherwise. + * @field startup_errors Error message for errors that occured during + * startup. + * @field composite_manager_running True if a composite manager is running. + * @table awesome */ static int luaA_awesome_index(lua_State *L) @@ -256,11 +262,10 @@ luaA_awesome_index(lua_State *L) } /** Add a global signal. - * \param L The Lua VM state. - * \return The number of elements pushed on stack. - * \luastack - * \lparam A string with the event name. - * \lparam The function to call. + * + * @param name A string with the event name. + * @param func The function to call. + * @function connect_signal */ static int luaA_awesome_connect_signal(lua_State *L) @@ -272,11 +277,10 @@ luaA_awesome_connect_signal(lua_State *L) } /** Remove a global signal. - * \param L The Lua VM state. - * \return The number of elements pushed on stack. - * \luastack - * \lparam A string with the event name. - * \lparam The function to call. + * + * @param name A string with the event name. + * @param func The function to call. + * @function disconnect_signal */ static int luaA_awesome_disconnect_signal(lua_State *L) @@ -290,11 +294,10 @@ luaA_awesome_disconnect_signal(lua_State *L) } /** Emit a global signal. - * \param L The Lua VM state. - * \return The number of elements pushed on stack. - * \luastack - * \lparam A string with the event name. - * \lparam The function to call. + * + * @param name A string with the event name. + * @param ... The signal arguments. + * @function emit_signal */ static int luaA_awesome_emit_signal(lua_State *L) @@ -471,16 +474,49 @@ luaA_init(xdgHandle* xdg) lua_pop(L, 2); /* pop "package" and "package.loaded" */ + /** A call into the lua code aborted with an error + * @signal debug::error + */ signal_add(&global_signals, "debug::error"); + /** A deprecated lua function was called + * @signal debug::deprecation + */ signal_add(&global_signals, "debug::deprecation"); + /** An invalid key was read from an object (e.g. c.foo) + * @signal debug::index::miss + */ signal_add(&global_signals, "debug::index::miss"); + /** An invalid key was written to an object (e.g. c.foo = "bar") + * @signal debug::newindex::miss + */ signal_add(&global_signals, "debug::newindex::miss"); + /** + * @signal systray::update + */ signal_add(&global_signals, "systray::update"); + /** + * @signal wallpaper_changed + */ signal_add(&global_signals, "wallpaper_changed"); + /** + * @signal xkb::map_changed + */ signal_add(&global_signals, "xkb::map_changed"); + /** + * @signal xkb::group_changed + */ signal_add(&global_signals, "xkb::group_changed"); + /** + * @signal refresh + */ signal_add(&global_signals, "refresh"); + /** + * @signal startup + */ signal_add(&global_signals, "startup"); + /** + * @signal exit + */ signal_add(&global_signals, "exit"); } diff --git a/mouse.c b/mouse.c index 135bc19f8..0d876d1c0 100644 --- a/mouse.c +++ b/mouse.c @@ -19,6 +19,13 @@ * */ +/** awesome mouse API + * @author Julien Danjou <julien@danjou.info> + * @copyright 2008-2009 Julien Danjou + * @release @AWESOME_VERSION@ + * @module mouse + */ + #include "mouse.h" #include "common/util.h" #include "globalconf.h" @@ -26,6 +33,18 @@ #include "objects/drawin.h" #include "objects/screen.h" +/** Mouse library. + * + * @field screen Mouse screen number. + * @table mouse + */ + +/** A table with X and Y coordinates. + * @field x X coordinate. + * @field y Y coordinate. + * @table coords_table + */ + /** Get the pointer position. * \param window The window to get position on. * \param x will be set to the Pointer-x-coordinate relative to window @@ -174,8 +193,13 @@ luaA_mouse_pushstatus(lua_State *L, int x, int y, uint16_t mask) } /** Get or set the mouse coords. - * \param L The Lua VM state. - * \return The number of elements pushed on stack. + * + * @tparam coords_table coords_table None or a table with x and y keys as mouse + * coordinates. + * @tparam boolean silent Disable mouse::enter or mouse::leave events that + * could be triggered by the pointer when moving. + * @treturn coords_table A table with mouse coordinates. + * @function coords */ static int luaA_mouse_coords(lua_State *L) @@ -212,11 +236,10 @@ luaA_mouse_coords(lua_State *L) return luaA_mouse_pushstatus(L, mouse_x, mouse_y, mask); } -/** Get the client which is under the pointer. - * \param L The Lua VM state. - * \return The number of elements pushed on stack. - * \luastack - * \lreturn A client or nil. +/** Get the client or any object which is under the pointer. + * + * @treturn client.client|nil A client or nil. + * @function object_under_pointer */ static int luaA_mouse_object_under_pointer(lua_State *L) diff --git a/mousegrabber.c b/mousegrabber.c index 1df805de6..28e2b6290 100644 --- a/mousegrabber.c +++ b/mousegrabber.c @@ -19,6 +19,13 @@ * */ +/** awesome mousegrabber API + * @author Julien Danjou <julien@danjou.info> + * @copyright 2008-2009 Julien Danjou + * @release @AWESOME_VERSION@ + * @module mousegrabber + */ + #include "mousegrabber.h" #include "common/xcursor.h" #include "mouse.h" @@ -76,12 +83,9 @@ mousegrabber_handleevent(lua_State *L, int x, int y, uint16_t mask) * The function is called with one argument: * a table containing modifiers pointer coordinates. * - * \param L The Lua VM state. - * \return The number of elements pushed on stack. - * - * \luastack - * - * \lparam A callback function as described above. + * @param func A callback function as described above. + * @param cursor The name of a X cursor to use while grabbing. + * @function run */ static int luaA_mousegrabber_run(lua_State *L) @@ -110,8 +114,8 @@ luaA_mousegrabber_run(lua_State *L) } /** Stop grabbing the mouse pointer. - * \param L The Lua VM state. - * \return The number of elements pushed on stack. + * + * @function stop */ int luaA_mousegrabber_stop(lua_State *L) @@ -122,10 +126,9 @@ luaA_mousegrabber_stop(lua_State *L) } /** Check if mousegrabber is running. - * \param L The Lua VM state. - * \return The number of elements pushed on stack. - * \luastack - * \lreturn A boolean value, true if mousegrabber is running, false otherwise. + * + * @return A boolean value, true if running, false otherwise. + * function isrunning */ static int luaA_mousegrabber_isrunning(lua_State *L) diff --git a/objects/button.c b/objects/button.c index 67258f5b9..29ec2a48d 100644 --- a/objects/button.c +++ b/objects/button.c @@ -19,8 +19,36 @@ * */ +/** awesome button API + * + * Furthermore to the classes described here, one can also use signals as + * described in @{signals}. + * + * Some signal names are starting with a dot. These dots are artefacts from + * the documentation generation, you get the real signal name by + * removing the starting dot. + * + * @author Julien Danjou <julien@danjou.info> + * @copyright 2008-2009 Julien Danjou + * @release @AWESOME_VERSION@ + * @classmod button + */ + #include "button.h" +/** Button object. + * + * @tfield int button The mouse button number, or 0 for any button. + * @tfield table modifiers The modifier key table that should be pressed while the + * button is pressed. + * @table button + */ + +/** Get the number of instances. + * @treturn int The number of button objects alive. + * @function instances + */ + /** Create a new mouse button bindings. * \param L The Lua VM state. * \return The number of elements pushed on stack. @@ -123,9 +151,23 @@ button_class_setup(lua_State *L) (lua_class_propfunc_t) luaA_button_get_modifiers, (lua_class_propfunc_t) luaA_button_set_modifiers); + /** When bound mouse button + modifiers are pressed. + * @param ... One or more arguments are possible + * @signal .press + */ signal_add(&button_class.signals, "press"); + /** When property changes. + * @signal property::button + */ signal_add(&button_class.signals, "property::button"); + /** When property changes. + * @signal property::modifiers + */ signal_add(&button_class.signals, "property::modifiers"); + /** When bound mouse button + modifiers are pressed. + * @param ... One or more arguments are possible + * @signal .release + */ signal_add(&button_class.signals, "release"); } diff --git a/objects/client.c b/objects/client.c index 79230e02d..06bd1ad30 100644 --- a/objects/client.c +++ b/objects/client.c @@ -19,6 +19,21 @@ * */ +/** awesome client API + * + * Furthermore to the classes described here, one can also use signals as + * described in @{signals} and X properties as described in @{xproperties}. + * + * Some signal names are starting with a dot. These dots are artefacts from + * the documentation generation, you get the real signal name by + * removing the starting dot. + * + * @author Julien Danjou <julien@danjou.info> + * @copyright 2008-2009 Julien Danjou + * @release @AWESOME_VERSION@ + * @classmod client + */ + #include "objects/client.h" #include "common/atoms.h" #include "common/xutil.h" @@ -36,6 +51,75 @@ #include #include +/** Client object. + * + * @field window The X window id. + * @field name The client title. + * @field skip_taskbar True if the client does not want to be in taskbar. + * @field type The window type (desktop, normal, dock, …). + * @field class The client class. + * @field instance The client instance. + * @field pid The client PID, if available. + * @field role The window role, if available. + * @field machine The machine client is running on. + * @field icon_name The client name when iconified. + * @field icon The client icon. + * @field screen Client screen. + * @field hidden Define if the client must be hidden, i.e. never mapped, + * invisible in taskbar. + * @field minimized Define it the client must be iconify, i.e. only visible in + * taskbar. + * @field size_hints_honor Honor size hints, i.e. respect size ratio. + * @field border_width The client border width. + * @field border_color The client border color. + * @field urgent The client urgent state. + * @field content An image representing the client window content (screenshot). + * @field focus The focused client. + * @field opacity The client opacity between 0 and 1. + * @field ontop The client is on top of every other windows. + * @field above The client is above normal windows. + * @field below The client is below normal windows. + * @field fullscreen The client is fullscreen or not. + * @field maximized The client is maximized (horizontally and vertically) or not. + * @field maximized_horizontal The client is maximized horizontally or not. + * @field maximized_vertical The client is maximized vertically or not. + * @field transient_for The client the window is transient for. + * @field group_window Window identification unique to a group of windows. + * @field leader_window Identification unique to windows spawned by the same command. + * @field size_hints A table with size hints of the client: user_position, + * user_size, program_position, program_size, etc. + * @field sticky Set the client sticky, i.e. available on all tags. + * @field modal Indicate if the client is modal. + * @field focusable True if the client can receive the input focus. + * @field shape_bounding The client's bounding shape as set by awesome as a (native) cairo surface. + * @field shape_clip The client's clip shape as set by awesome as a (native) cairo surface. + * @field shape_client_bounding The client's bounding shape as set by the program as a (native) cairo surface. + * @field shape_client_clip The client's clip shape as set by the program as a (native) cairo surface. + * @field startup_id The FreeDesktop StartId. + * @field valid If the client that this object refers to is still managed by awesome. + * @table client + */ + +/** Return client struts (reserved space at the edge of the screen). + * + * @param struts A table with new strut values, or none. + * @return A table with strut values. + * @function struts + */ + +/** Get or set mouse buttons bindings for a client. + * + * @param buttons_table An array of mouse button bindings objects, or nothing. + * @return A table with all buttons. + * @function buttons + */ + +/** Get the number of instances. + * + * @return The number of client objects alive. + * @function instances + */ + static area_t titlebar_get_area(client_t *c, client_titlebar_t bar); static drawable_t *titlebar_get_drawable(lua_State *L, client_t *c, int cl_idx, client_titlebar_t bar); @@ -1305,11 +1389,10 @@ client_kill(client_t *c) } /** Get all clients into a table. - * \param L The Lua VM state. - * \return The number of elements pushed on stack. - * \luastack - * \lparam An optional screen number. - * \lreturn A table with all clients. + * + * @param[opt] screen A screen number. + * @return A table with all clients. + * @function get */ static int luaA_client_get(lua_State *L) @@ -1332,11 +1415,9 @@ luaA_client_get(lua_State *L) } /** Check if a client is visible on its screen. - * \param L The Lua VM state. - * \return The number of elements pushed on stack. - * \luastack - * \lvalue A client. - * \lreturn A boolean value, true if the client is visible, false otherwise. + * + * @return A boolean value, true if the client is visible, false otherwise. + * @function isvisible */ static int luaA_client_isvisible(lua_State *L) @@ -1433,10 +1514,8 @@ out: /** Kill a client. - * \param L The Lua VM state. * - * \luastack - * \lvalue A client. + * @function kill */ static int luaA_client_kill(lua_State *L) @@ -1446,11 +1525,9 @@ luaA_client_kill(lua_State *L) return 0; } -/** Swap a client with another one. - * \param L The Lua VM state. - * \luastack - * \lvalue A client. - * \lparam A client to swap with. +/** Swap a client with another one in global client list. + * @client A client to swap with. + * @function swap */ static int luaA_client_swap(lua_State *L) @@ -1481,10 +1558,11 @@ luaA_client_swap(lua_State *L) } /** Access or set the client tags. - * \param L The Lua VM state. - * \return The number of elements pushed on stack. - * \lparam A table with tags to set, or none to get the current tags table. - * \return The clients tag. + * + * @param tags_table A table with tags to set, or none to get the current tags + * table. + * @return A table with all tags. + * @function tags */ static int luaA_client_tags(lua_State *L) @@ -1534,9 +1612,8 @@ luaA_client_tags(lua_State *L) } /** Raise a client on top of others which are on the same layer. - * \param L The Lua VM state. - * \luastack - * \lvalue A client. + * + * @function raise */ static int luaA_client_raise(lua_State *L) @@ -1547,9 +1624,8 @@ luaA_client_raise(lua_State *L) } /** Lower a client on bottom of others which are on the same layer. - * \param L The Lua VM state. - * \luastack - * \lvalue A client. + * + * @function lower */ static int luaA_client_lower(lua_State *L) @@ -1566,10 +1642,8 @@ luaA_client_lower(lua_State *L) } /** Stop managing a client. - * \param L The Lua VM state. - * \return The number of elements pushed on stack. - * \luastack - * \lvalue A client. + * + * @function unmanage */ static int luaA_client_unmanage(lua_State *L) @@ -1783,11 +1857,10 @@ HANDLE_TITLEBAR(bottom, CLIENT_TITLEBAR_BOTTOM) HANDLE_TITLEBAR(left, CLIENT_TITLEBAR_LEFT) /** Return or set client geometry. - * \param L The Lua VM state. - * \return The number of elements pushed on stack. - * \luastack - * \lparam A table with new coordinates, or none. - * \lreturn A table with client coordinates. + * + * @param arg1 A table with new coordinates, or none. + * @return A table with client coordinates. + * @function geometry */ static int luaA_client_geometry(lua_State *L) @@ -1818,14 +1891,13 @@ luaA_client_geometry(lua_State *L) return luaA_pusharea(L, c->geometry); } -/** Apply size hints to a lua-specified geometry. - * \param L The Lua VM state. - * \return The number of elements pushed on stack. - * \luastack - * \lparam Desired width of client. - * \lparam Desired height of client. - * \lreturn Corrected width. - * \lreturn Corrected height. +/** Apply size hints to a size. + * + * @param width Desired width of client + * @param height Desired height of client + * @return Actual width of client + * @return Actual height of client + * @function apply_size_hints */ static int luaA_client_apply_size_hints(lua_State *L) @@ -2310,12 +2382,10 @@ luaA_client_set_shape_clip(lua_State *L, client_t *c) } /** Get or set keys bindings for a client. - * \param L The Lua VM state. - * \return The number of element pushed on stack. - * \luastack - * \lvalue A client. - * \lparam An array of key bindings objects, or nothing. - * \return The array of key bindings objects of this client. + * + * @param keys_table An array of key bindings objects, or nothing. + * @return A table with all keys. + * @function keys */ static int luaA_client_keys(lua_State *L) @@ -2570,66 +2640,249 @@ client_class_setup(lua_State *L) (lua_class_propfunc_t) luaA_client_get_client_shape_clip, NULL); + /** when a client gains focus + * @signal .focus + */ signal_add(&client_class.signals, "focus"); + /** Before manage, after unmanage, and when clients swap. + * @signal .list + */ signal_add(&client_class.signals, "list"); + /** + * @signal .manage + */ signal_add(&client_class.signals, "manage"); + /** + * @signal button::press + */ signal_add(&client_class.signals, "button::press"); + /** + * @signal button::release + */ signal_add(&client_class.signals, "button::release"); + /** + * @signal mouse::enter + */ signal_add(&client_class.signals, "mouse::enter"); + /** + * @signal mouse::leave + */ signal_add(&client_class.signals, "mouse::leave"); + /** + * @signal mouse::move + */ signal_add(&client_class.signals, "mouse::move"); + /** + * @signal property::above + */ signal_add(&client_class.signals, "property::above"); + /** + * @signal property::below + */ signal_add(&client_class.signals, "property::below"); + /** + * @signal property::class + */ signal_add(&client_class.signals, "property::class"); + /** + * @signal property::focusable + */ signal_add(&client_class.signals, "property::focusable"); + /** + * @signal property::fullscreen + */ signal_add(&client_class.signals, "property::fullscreen"); + /** + * @signal property::geometry + */ signal_add(&client_class.signals, "property::geometry"); + /** + * @signal property::group_window + */ signal_add(&client_class.signals, "property::group_window"); + /** + * @signal property::height + */ signal_add(&client_class.signals, "property::height"); + /** + * @signal property::hidden + */ signal_add(&client_class.signals, "property::hidden"); + /** + * @signal property::icon + */ signal_add(&client_class.signals, "property::icon"); + /** + * @signal property::icon_name + */ signal_add(&client_class.signals, "property::icon_name"); + /** + * @signal property::instance + */ signal_add(&client_class.signals, "property::instance"); + /** + * @signal property::keys + */ signal_add(&client_class.signals, "property::keys"); + /** + * @signal property::machine + */ signal_add(&client_class.signals, "property::machine"); + /** + * @signal property::maximized + */ signal_add(&client_class.signals, "property::maximized"); + /** + * @signal property::maximized_horizontal + */ signal_add(&client_class.signals, "property::maximized_horizontal"); + /** + * @signal property::maximized_vertical + */ signal_add(&client_class.signals, "property::maximized_vertical"); + /** + * @signal property::minimized + */ signal_add(&client_class.signals, "property::minimized"); + /** + * @signal property::modal + */ signal_add(&client_class.signals, "property::modal"); + /** + * @signal property::name + */ signal_add(&client_class.signals, "property::name"); + /** + * @signal property::ontop + */ signal_add(&client_class.signals, "property::ontop"); + /** + * @signal property::pid + */ signal_add(&client_class.signals, "property::pid"); + /** + * @signal property::role + */ signal_add(&client_class.signals, "property::role"); + /** + * @signal property::screen + */ signal_add(&client_class.signals, "property::screen"); + /** + * @signal property::shape_bounding + */ signal_add(&client_class.signals, "property::shape_bounding"); + /** + * @signal property::shape_client_bounding + */ signal_add(&client_class.signals, "property::shape_client_bounding"); + /** + * @signal property::shape_client_clip + */ signal_add(&client_class.signals, "property::shape_client_clip"); + /** + * @signal property::shape_clip + */ signal_add(&client_class.signals, "property::shape_clip"); + /** + * @signal property::size_hints_honor + */ signal_add(&client_class.signals, "property::size_hints_honor"); + /** + * @signal property::skip_taskbar + */ signal_add(&client_class.signals, "property::skip_taskbar"); + /** + * @signal property::sticky + */ signal_add(&client_class.signals, "property::sticky"); + /** + * @signal property::struts + */ signal_add(&client_class.signals, "property::struts"); + /** + * @signal property::titlebar_bottom + */ signal_add(&client_class.signals, "property::titlebar_bottom"); + /** + * @signal property::titlebar_left + */ signal_add(&client_class.signals, "property::titlebar_left"); + /** + * @signal property::titlebar_right + */ signal_add(&client_class.signals, "property::titlebar_right"); + /** + * @signal property::titlebar_top + */ signal_add(&client_class.signals, "property::titlebar_top"); + /** + * @signal property::transient_for + */ signal_add(&client_class.signals, "property::transient_for"); + /** + * @signal property::type + */ signal_add(&client_class.signals, "property::type"); + /** + * @signal property::urgent + */ signal_add(&client_class.signals, "property::urgent"); + /** + * @signal property::width + */ signal_add(&client_class.signals, "property::width"); + /** + * @signal property::window + */ signal_add(&client_class.signals, "property::window"); + /** + * @signal property::x + */ signal_add(&client_class.signals, "property::x"); + /** + * @signal property::y + */ signal_add(&client_class.signals, "property::y"); + /** + * @signal request::activate + */ signal_add(&client_class.signals, "request::activate"); + /** + * @signal request::fullscreen + */ signal_add(&client_class.signals, "request::fullscreen"); + /** + * @signal request::maximized_horizontal + */ signal_add(&client_class.signals, "request::maximized_horizontal"); + /** + * @signal request::maximized_vertical + */ signal_add(&client_class.signals, "request::maximized_vertical"); + /** + * @signal request::tag + */ signal_add(&client_class.signals, "request::tag"); + /** + * @signal request::urgent + */ signal_add(&client_class.signals, "request::urgent"); + /** when client is tagged + * @signal .tagged + */ signal_add(&client_class.signals, "tagged"); + /** when a client looses focus + * @signal .unfocus + */ signal_add(&client_class.signals, "unfocus"); + /** + * @signal .unmanage + */ signal_add(&client_class.signals, "unmanage"); + /** when client looses tag + * @signal .untagged + */ signal_add(&client_class.signals, "untagged"); } diff --git a/objects/drawable.c b/objects/drawable.c index e3536875f..dff780ecd 100644 --- a/objects/drawable.c +++ b/objects/drawable.c @@ -20,12 +20,35 @@ * */ +/** awesome drawable API + * + * Furthermore to the classes described here, one can also use signals as + * described in @{signals}. + * + * @author Uli Schlachter <psychon@znc.in> + * @copyright 2012 Uli Schlachter + * @release @AWESOME_VERSION@ + * @classmod drawable + */ + #include "drawable.h" #include "common/luaobject.h" #include "globalconf.h" #include +/** Drawable object. + * + * @field surface The drawable's cairo surface. + * @function drawable + */ + +/** Get the number of instances. + * + * @return The number of drawable objects alive. + * @function instances + */ + static lua_class_t drawable_class; LUA_OBJECT_FUNCS(drawable_class, drawable_t, drawable) @@ -106,8 +129,8 @@ luaA_drawable_get_surface(lua_State *L, drawable_t *drawable) /** Refresh a drawable's content. This has to be called whenever some drawing to * the drawable's surface has been done and should become visible. - * \param L The Lua VM state. - * \return The number of elements pushed on stack. + * + * @function refresh */ static int luaA_drawable_refresh(lua_State *L) @@ -119,11 +142,10 @@ luaA_drawable_refresh(lua_State *L) return 0; } -/** Return drawable geometry. - * \param L The Lua VM state. - * \return The number of elements pushed on stack. - * \luastack - * \lreturn A table with drawable coordinates. +/** Get drawable geometry. The geometry consists of x, y, width and height. + * + * @return A table with drawable coordinates and geometry. + * @function geometry */ static int luaA_drawable_geometry(lua_State *L) @@ -160,15 +182,45 @@ drawable_class_setup(lua_State *L) (lua_class_propfunc_t) luaA_drawable_get_surface, NULL); + /** + * @signal button::press + */ signal_add(&drawable_class.signals, "button::press"); + /** + * @signal button::release + */ signal_add(&drawable_class.signals, "button::release"); + /** + * @signal mouse::enter + */ signal_add(&drawable_class.signals, "mouse::enter"); + /** + * @signal mouse::leave + */ signal_add(&drawable_class.signals, "mouse::leave"); + /** + * @signal mouse::move + */ signal_add(&drawable_class.signals, "mouse::move"); + /** + * @signal property::height + */ signal_add(&drawable_class.signals, "property::height"); + /** + * @signal property::width + */ signal_add(&drawable_class.signals, "property::width"); + /** + * @signal property::x + */ signal_add(&drawable_class.signals, "property::x"); + /** + * @signal property::y + */ signal_add(&drawable_class.signals, "property::y"); + /** + * @signal property::surface + */ signal_add(&drawable_class.signals, "property::surface"); } diff --git a/objects/drawin.c b/objects/drawin.c index 078ef49a8..62c200290 100644 --- a/objects/drawin.c +++ b/objects/drawin.c @@ -20,6 +20,17 @@ * */ +/** awesome drawin API + * + * Furthermore to the classes described here, one can also use signals as + * described in @{signals} and X properties as described in @{xproperties}. + * + * @author Julien Danjou <julien@danjou.info> + * @copyright 2008-2009 Julien Danjou + * @release @AWESOME_VERSION@ + * @classmod drawin + */ + #include "drawin.h" #include "common/atoms.h" #include "common/xcursor.h" @@ -32,6 +43,45 @@ #include #include +/** Drawin object. + * + * @field border_width Border width. + * @field border_color Border color. + * @field ontop On top of other windows. + * @field cursor The mouse cursor. + * @field visible Visibility. + * @field opacity The opacity of the drawin, between 0 and 1. + * @field type The window type (desktop, normal, dock, …). + * @field x The x coordinates. + * @field y The y coordinates. + * @field width The width of the drawin. + * @field height The height of the drawin. + * @field drawable The drawin's drawable. + * @field window The X window id. + * @field shape_bounding The drawin's bounding shape as a (native) cairo surface. + * @field shape_clip The drawin's clip shape as a (native) cairo surface. + * @table drawin + */ + +/** Get or set mouse buttons bindings to a drawin. + * + * @param buttons_table A table of buttons objects, or nothing. + * @function buttons + */ + +/** Get or set drawin struts. + * + * @param strut A table with new strut, or nothing + * @return The drawin strut in a table. + * @function struts + */ + +/** Get the number of instances. + * + * @return The number of drawin objects alive. + * @function instances + */ + LUA_OBJECT_FUNCS(drawin_class, drawin_t, drawin) /** Kick out systray windows. @@ -313,12 +363,12 @@ luaA_drawin_new(lua_State *L) return 1; } -/* Set or get the drawin geometry. - * \param L The Lua VM state. - * \return The number of elements pushed on stack. - * \luastack - * \lparam An optional table with drawin geometry. - * \lreturn The drawin geometry. +/** Get or set drawin geometry. That's the same as accessing or setting the x, + * y, width or height properties of a drawin. + * + * @param A table with coordinates to modify. + * @return A table with drawin coordinates and geometry. + * @function geometry */ static int luaA_drawin_geometry(lua_State *L) @@ -624,15 +674,45 @@ drawin_class_setup(lua_State *L) (lua_class_propfunc_t) luaA_drawin_get_shape_clip, (lua_class_propfunc_t) luaA_drawin_set_shape_clip); + /** + * @signal property::shape_bounding + */ signal_add(&drawin_class.signals, "property::shape_bounding"); + /** + * @signal property::shape_clip + */ signal_add(&drawin_class.signals, "property::shape_clip"); + /** + * @signal property::border_width + */ signal_add(&drawin_class.signals, "property::border_width"); + /** + * @signal property::cursor + */ signal_add(&drawin_class.signals, "property::cursor"); + /** + * @signal property::height + */ signal_add(&drawin_class.signals, "property::height"); + /** + * @signal property::ontop + */ signal_add(&drawin_class.signals, "property::ontop"); + /** + * @signal property::visible + */ signal_add(&drawin_class.signals, "property::visible"); + /** + * @signal property::width + */ signal_add(&drawin_class.signals, "property::width"); + /** + * @signal property::x + */ signal_add(&drawin_class.signals, "property::x"); + /** + * @signal property::y + */ signal_add(&drawin_class.signals, "property::y"); } diff --git a/objects/key.c b/objects/key.c index 0e4819085..dc847a7af 100644 --- a/objects/key.c +++ b/objects/key.c @@ -20,6 +20,21 @@ * */ +/** awesome key API + * + * Furthermore to the classes described here, one can also use signals as + * described in @{signals}. + * + * Some signal names are starting with a dot. These dots are artefacts from + * the documentation generation, you get the real signal name by + * removing the starting dot. + * + * @author Julien Danjou <julien@danjou.info> + * @copyright 2008-2009 Julien Danjou + * @release @AWESOME_VERSION@ + * @classmod key + */ + #include "objects/key.h" #include "common/xutil.h" #include "xkb.h" @@ -28,6 +43,24 @@ #include #include +/** Key object. + * + * @tfield string key The key to trigger an event. + * @tfield string 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'. + * @tfield table 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. + * @table key + */ + +/** Get the number of instances. + * + * @return The number of key objects alive. + * @function instances + */ + static void luaA_keystore(lua_State *L, int ud, const char *str, ssize_t len) { @@ -235,9 +268,21 @@ key_class_setup(lua_State *L) (lua_class_propfunc_t) luaA_key_get_modifiers, (lua_class_propfunc_t) luaA_key_set_modifiers); + /** + * @signal .press + */ signal_add(&key_class.signals, "press"); + /** + * @signal property::key + */ signal_add(&key_class.signals, "property::key"); + /** + * @signal property::modifiers + */ signal_add(&key_class.signals, "property::modifiers"); + /** + * @signal .release + */ signal_add(&key_class.signals, "release"); } diff --git a/objects/screen.c b/objects/screen.c index 3321bd0df..1865e2745 100644 --- a/objects/screen.c +++ b/objects/screen.c @@ -19,6 +19,17 @@ * */ +/** awesome screen API + * + * Furthermore to the classes described here, one can also use signals as + * described in @{signals}. + * + * @author Julien Danjou <julien@danjou.info> + * @copyright 2008-2009 Julien Danjou + * @release @AWESOME_VERSION@ + * @classmod screen + */ + #include "objects/screen.h" #include "banning.h" #include "objects/client.h" @@ -30,6 +41,19 @@ #include #include +/** Screen is a table where indexes are screen numbers. You can use `screen[1]` + * to get access to the first screen, etc. Alternatively, if RANDR information + * is available, you can use output names for finding screen objects. + * Each screen has a set of properties. + * + * @tfield table geometry The screen coordinates. Immutable. + * @tfield table workarea The screen workarea. + * @tfield int index The screen number. + * @tfield table outputs If RANDR information is available, a list of outputs + * for this screen and their size in mm. + * @table screen + */ + struct screen_output_t { /** The XRandR names of the output */ @@ -502,12 +526,10 @@ luaA_screen_get_workarea(lua_State *L, screen_t *s) return 1; } -/** Get the screen count. - * \param L The Lua VM state. - * \return The number of elements pushed on stack. +/** Get the number of screens. * - * \luastack - * \lreturn The screen count, at least 1. + * @return The screen count, at least 1. + * @function count */ static int luaA_screen_count(lua_State *L) @@ -557,6 +579,9 @@ screen_class_setup(lua_State *L) NULL, (lua_class_propfunc_t) luaA_screen_get_workarea, NULL); + /** + * @signal property::workarea + */ signal_add(&screen_class.signals, "property::workarea"); } diff --git a/objects/tag.c b/objects/tag.c index 096a784d4..b694079ab 100644 --- a/objects/tag.c +++ b/objects/tag.c @@ -19,12 +19,41 @@ * */ +/** awesome tag API + * + * Furthermore to the classes described here, one can also use signals as + * described in @{signals}. + * + * Some signal names are starting with a dot. These dots are artefacts from + * the documentation generation, you get the real signal name by + * removing the starting dot. + * + * @author Julien Danjou <julien@danjou.info> + * @copyright 2008-2009 Julien Danjou + * @release @AWESOME_VERSION@ + * @classmod tag + */ + #include "tag.h" #include "banning.h" #include "client.h" #include "ewmh.h" #include "luaa.h" +/** Tag object. + * + * @field name Tag name. + * @field selected True if the tag is selected to be viewed. + * @field activated True if the tag is active and can be used. + * @table tag + */ + +/** Get the number of instances. + * + * @return The number of tag objects alive. + * @function instances + */ + /** Tag type */ struct tag { @@ -179,11 +208,11 @@ luaA_tag_new(lua_State *L) } /** Get or set the clients attached to this tag. - * \param L The Lua VM state. - * \return The number of elements pushed on stack. - * \luastack - * \lparam None or a table of clients to set. - * \lreturn A table with the clients attached to this tags. + * + * @param clients_table None or a table of clients to set as being tagged with + * this tag. + * @return A table with the clients attached to this tags. + * @function clients */ static int luaA_tag_clients(lua_State *L) @@ -350,11 +379,29 @@ tag_class_setup(lua_State *L) (lua_class_propfunc_t) luaA_tag_get_activated, (lua_class_propfunc_t) luaA_tag_set_activated); + /** + * @signal property::name + */ signal_add(&tag_class.signals, "property::name"); + /** + * @signal property::selected + */ signal_add(&tag_class.signals, "property::selected"); + /** + * @signal property::activated + */ signal_add(&tag_class.signals, "property::activated"); + /** + * @signal request::select + */ signal_add(&tag_class.signals, "request::select"); + /** + * @signal tagged + */ signal_add(&tag_class.signals, "tagged"); + /** + * @signal untagged + */ signal_add(&tag_class.signals, "untagged"); } diff --git a/objects/window.c b/objects/window.c index 3f913ee9b..45077bbfd 100644 --- a/objects/window.c +++ b/objects/window.c @@ -19,6 +19,14 @@ * */ +/** Handling of X properties. + * + * This can not be used as a standalone class, but is instead referenced + * explicitely in the classes, where it can be used. In the respective + * classes,it then can be used via `classname:get_xproperty(...)` etc. + * @classmod xproperties + */ + #include "objects/window.h" #include "common/atoms.h" #include "ewmh.h" @@ -385,9 +393,11 @@ window_get_xproperty(lua_State *L, xcb_window_t window, int prop_idx) return 1; } -/** Set an xproperty. - * \param L The Lua VM state. - * \return The number of elements pushed on stack. +/** Change a xproperty. + * + * @param name The name of the X11 property + * @param value The new value for the property + * @function set_xproperty */ static int luaA_window_set_xproperty(lua_State *L) @@ -396,9 +406,10 @@ luaA_window_set_xproperty(lua_State *L) return window_set_xproperty(L, w->window, 2, 3); } -/** Get an xproperty. - * \param L The Lua VM state. - * \return The number of elements pushed on stack. +/** Get the value of a xproperty. + * + * @param name The name of the X11 property + * @function get_xproperty */ static int luaA_window_get_xproperty(lua_State *L) @@ -407,7 +418,7 @@ luaA_window_get_xproperty(lua_State *L) return window_get_xproperty(L, w->window, 2); } -/** Translate a window_type_t into the corresponding EWMH atom. +/* Translate a window_type_t into the corresponding EWMH atom. * @param type The type to return. * @return The EWMH atom for this type. */ @@ -498,11 +509,29 @@ window_class_setup(lua_State *L) (lua_class_propfunc_t) luaA_window_get_border_width, (lua_class_propfunc_t) luaA_window_set_border_width); + /** + * @signal property::border_color + */ signal_add(&window_class.signals, "property::border_color"); + /** + * @signal property::border_width + */ signal_add(&window_class.signals, "property::border_width"); + /** + * @signal property::buttons + */ signal_add(&window_class.signals, "property::buttons"); + /** + * @signal property::opacity + */ signal_add(&window_class.signals, "property::opacity"); + /** + * @signal property::struts + */ signal_add(&window_class.signals, "property::struts"); + /** + * @signal property::type + */ signal_add(&window_class.signals, "property::type"); } diff --git a/root.c b/root.c index e8bc08302..34a170963 100644 --- a/root.c +++ b/root.c @@ -19,6 +19,13 @@ * */ +/** awesome root window API + * @author Julien Danjou <julien@danjou.info> + * @copyright 2008-2009 Julien Danjou + * @release @AWESOME_VERSION@ + * @module root + */ + #include "globalconf.h" #include "common/atoms.h" @@ -133,18 +140,17 @@ _string_to_key_code(const char *s) } } -/** Send fake events. Usually the current focused client will get it. - * \param L The Lua VM state. - * \return The number of elements pushed on stack. - * \luastack - * \lparam The event type: key_press, key_release, button_press, button_release - * or motion_notify. - * \lparam 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. - * \lparam In case of a motion event, this is the X coordinate. - * \lparam In case of a motion event, this is the Y coordinate. - * If not specified, the current one is used. +/** Send fake events. Usually the currently focused client will get it. + * + * @param event_type The event type: key_press, key_release, button_press, + * button_release or motion_notify. + * @param detail 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 makes the + * coordinates relatives. + * @param x In case of a motion event, this is the X coordinate. + * @param y In case of a motion event, this is the Y coordinate. + * @function fake_input */ static int luaA_root_fake_input(lua_State *L) @@ -208,12 +214,11 @@ luaA_root_fake_input(lua_State *L) } /** Get or set global key bindings. - * This binding will be available when you'll press keys on the root window. - * \param L The Lua VM state. - * \return The number of elements pushed on stack. - * \luastack - * \lparam An array of key bindings objects, or nothing. - * \lreturn The array of key bindings objects of this client. + * These bindings will be available when you press keys on the root window. + * + * @tparam table|nil keys_array An array of key binding objects, or nothing. + * @return The array of key bindings objects of this client. + * @function keys */ static int luaA_root_keys(lua_State *L) @@ -250,12 +255,11 @@ luaA_root_keys(lua_State *L) } /** Get or set global mouse bindings. - * This binding will be available when you'll click on the root window. - * \param L The Lua VM state. - * \return The number of elements pushed on stack. - * \luastack - * \lparam An array of mouse button bindings objects, or nothing. - * \lreturn The array of mouse button bindings objects. + * This binding will be available when you click on the root window. + * + * @param button_table An array of mouse button bindings objects, or nothing. + * @return The array of mouse button bindings objects. + * @function buttons */ static int luaA_root_buttons(lua_State *L) @@ -288,10 +292,9 @@ luaA_root_buttons(lua_State *L) } /** Set the root cursor. - * \param L The Lua VM state. - * \return The number of elements pushed on stack. - * \luastack - * \lparam A X cursor name. + * + * @param cursor_name A X cursor name. + * @function cursor */ static int luaA_root_cursor(lua_State *L) @@ -315,10 +318,9 @@ luaA_root_cursor(lua_State *L) } /** Get the drawins attached to a screen. - * \param L The Lua VM state. - * \return The number of elements pushed on stack. - * \luastack - * \lreturn A table with all drawins. + * + * @return A table with all drawins. + * @function drawins */ static int luaA_root_drawins(lua_State *L) @@ -334,11 +336,11 @@ luaA_root_drawins(lua_State *L) return 1; } -/** Get the screen's wallpaper - * \param L The Lua VM state. - * \return The number of elements pushed on stack. - * \luastack - * \lreturn A cairo surface for the wallpaper. +/** Get the wallpaper as a cairo surface or set it as a cairo pattern. + * + * @param pattern A cairo pattern as light userdata + * @return A cairo surface or nothing. + * @function wallpaper */ static int luaA_root_wallpaper(lua_State *L) @@ -398,11 +400,9 @@ luaA_root_wallpaper(lua_State *L) return 1; } -/** Get the screen's wallpaper - * \param L The Lua VM state. - * \return The number of elements pushed on stack. - * \luastack - * \lreturn A cairo surface for the wallpaper. +/** Get the attached tags. + * @return A table with all tags. + * @function tags */ static int luaA_root_tags(lua_State *L) diff --git a/selection.c b/selection.c index 721001e45..6787c7ed8 100644 --- a/selection.c +++ b/selection.c @@ -20,6 +20,13 @@ * */ +/** awesome selection (clipboard) API + * @author Julien Danjou <julien@danjou.info> + * @copyright 2008-2009 Julien Danjou + * @release @AWESOME_VERSION@ + * @module selection + */ + #include "selection.h" #include "globalconf.h" #include "common/atoms.h" @@ -28,6 +35,12 @@ #include #include +/** Get the selection (clipboard) content. + * + * @return A string with the selection (clipboard) content. + * @function selection + */ + static xcb_window_t selection_window = XCB_NONE; /** Get the current X selection buffer. diff --git a/spawn.c b/spawn.c index 37dd3ba50..987f3e1f5 100644 --- a/spawn.c +++ b/spawn.c @@ -19,6 +19,14 @@ * */ +/** awesome core API + * + * @author Julien Danjou <julien@danjou.info> + * @copyright 2008-2009 Julien Danjou + * @release @AWESOME_VERSION@ + * @module awesome + */ + #include "spawn.h" #include @@ -237,10 +245,30 @@ spawn_init(void) spawn_monitor_event, NULL, NULL); + /** For some reason the application aborted startup + * @param arg Table which only got the "id" key set + * @signal spawn::canceled + */ signal_add(&global_signals, "spawn::canceled"); + /** When one of the fields from the @{spawn::initiated} table changes + * @param arg Table which describes the spawn event + * @signal spawn::change + */ signal_add(&global_signals, "spawn::change"); + /** An application finished starting + * @param arg Table which only got the "id" key set + * @signal spawn::completed + */ signal_add(&global_signals, "spawn::completed"); + /** When a new client is beginning to start + * @param arg Table which describes the spawn event + * @signal spawn::initiated + */ signal_add(&global_signals, "spawn::initiated"); + /** An application started a spawn event but didn't start in time. + * @param arg Table which only got the "id" key set + * @signal spawn::timeout + */ signal_add(&global_signals, "spawn::timeout"); } @@ -310,12 +338,11 @@ parse_command(lua_State *L, int idx, GError **error) /** Spawn a program. * This function is multi-head (Zaphod) aware and will set display to * the right screen according to mouse position. - * \param L The Lua VM state. - * \return The number of elements pushed on stack - * \luastack - * \lparam The command to launch. - * \lparam Use startup-notification, true or false, default to true. - * \lreturn Process ID if everything is OK, or an error string if an error occured. + * + * @param cmd The command to launch. + * @param use_sn Use startup-notification, true or false, default to true. + * @return Process ID if everything is OK, or an error string if an error occured. + * @function spawn */ int luaA_spawn(lua_State *L) diff --git a/xkb.c b/xkb.c index 3e1d62457..82db23bbd 100644 --- a/xkb.c +++ b/xkb.c @@ -19,17 +19,21 @@ * */ +/** + * @module awesome + */ + #include "xkb.h" #include "globalconf.h" #include #include #include -/* \brief switch keyboard layout - * \param L The Lua VM state. - * \return The number of elements pushed on stack. - * \luastack - * \lparam layout number, integer from 0 to 3 +/** + * Switch keyboard layout. + * + * @function xkb_set_layout_group + * @tparam integer num keyboard layout number, integer from 0 to 3 */ int luaA_xkb_set_layout_group(lua_State *L) @@ -40,11 +44,11 @@ luaA_xkb_set_layout_group(lua_State *L) return 0; } -/* \brief get current layout number - * \param L The Lua VM state. - * \return The number of elements pushed on stack. - * \luastack - * \lreturn current layout number, integer from 0 to 3 +/** + * Get current layout number. + * + * @function xkb_get_layout_group + * @treturn integer num Current layout number, integer from 0 to 3. */ int luaA_xkb_get_layout_group(lua_State *L) @@ -65,12 +69,12 @@ luaA_xkb_get_layout_group(lua_State *L) return 1; } -/* \brief get layout short names - * \param L The Lua VM state. - * \return The number of elements pushed on stack. - * \luastack - * \lreturn string describing current layout settings, \ - * example: 'pc+us+de:2+inet(evdev)+group(alt_shift_toggle)+ctrl(nocaps)' +/** + * Get layout short names. + * + * @function xkb_get_group_names + * @treturn string A string describing the current layout settings, + * e.g.: 'pc+us+de:2+inet(evdev)+group(alt_shift_toggle)+ctrl(nocaps)' */ int luaA_xkb_get_group_names(lua_State *L)