Module: gears.object

The object oriented programming base class used by various Awesome widgets and components.

It provide basic observer pattern, signaling and dynamic properties.

Info:

  • Copyright: 2010 Uli Schlachter
  • Originally authored by: Uli Schlachter
    (Full contributors list available on our github project)

Constructors

gears.object {[args]} Returns a new object.

Functions

t.emit_signal (name, ...) Emit a notification signal.
t.disconnect_signal (name, func) Disconnect a signal from a source.

Static module functions

gears.object.modulename (level) -> string Helper function to get the module name out of debug.getinfo.

Object methods

:connect_signal (name, func) Connect to a signal.
:weak_connect_signal (name, func) Connect to a signal weakly.
:disconnect_signal (name, func) Disconnect from a signal.
:emit_signal (name, ...) Emit a signal.

gears.object.properties Functions

gears.object.properties.capi_index_fallback (class, args) Add the missing properties handler to a CAPI object such as client/tag/screen.


Constructors

🔗 gears.object {[args]}
Returns a new object. You can call :emit_signal(), :disconnect_signal() and :connect_signal() on the resulting object.

Note that args.enable_auto_signals is only supported when args.enable_properties is true.

Parameters:

Note: This constructors uses named parameters calling convention. It means you call it with {} and omit the parantheses. For example, calling this will all default argument would be gears.object{}. This is a Lua shortcut syntax equivalent to gears.object({}). args is only a placeholder name for the "lone table argument" used in named parameters calls.
Name Type(s) Description Default value
args Optional table The arguments {}
enable_properties Optional boolean Automatically call getters and setters false
enable_auto_signals Optional boolean Generate "property::xxxx" signals when an unknown property is set. false
class Optional table nil

Returns:

    table A new object

Functions

🔗 t.emit_signal (name, ...)
Emit a notification signal.

Parameters:

Name Type(s) Description
name string The signal name.
... The signal callback arguments
🔗 t.disconnect_signal (name, func)
Disconnect a signal from a source.

Parameters:

Name Type(s) Description
name string The name of the signal
func function The attached function

Returns:

    boolean If the disconnection was successful

Static module functions

🔗 gears.object.modulename (level) -> string
Helper function to get the module name out of debug.getinfo.

Parameters:

Name Type(s) Description Default value
level Optional integer Level for debug.getinfo(level, "S"). Typically 2 or 3. 2

Returns:

    string The module name, e.g. "wibox.container.background".

Usage:

    local mt = {}
mt.__tostring = function(o)
    return require("gears.object").modulename(2)
end
return setmetatable(ret, mt)

Object methods

🔗 :connect_signal (name, func)
Connect to a signal.

Parameters:

Name Type(s) Description
name string The name of the signal.
func function The callback to call when the signal is emitted.
🔗 :weak_connect_signal (name, func)
Connect to a signal weakly.

This allows the callback function to be garbage collected and automatically disconnects the signal when that happens. Warning: Only use this function if you really, really, really know what you are doing.

Parameters:

Name Type(s) Description
name string The name of the signal.
func function The callback to call when the signal is emitted.
🔗 :disconnect_signal (name, func)
Disconnect from a signal.

Parameters:

Name Type(s) Description
name string The name of the signal.
func function The callback that should be disconnected.
🔗 :emit_signal (name, ...)
Emit a signal.

Parameters:

Name Type(s) Description
name string The name of the signal
... Extra arguments for the callback functions. Each connected function receives the object as first argument and then any extra arguments that are given to emit_signal()

gears.object.properties Functions

🔗 gears.object.properties.capi_index_fallback (class, args)

Add the missing properties handler to a CAPI object such as client/tag/screen. Valid args:

  • getter: A smart getter (handle property getter itself)
  • getter_fallback: A dumb getter method (don't handle individual property getter)
  • getter_class: A module with individual property getter/setter
  • getter_prefix: A special getter prefix (like "get" or "get_" (default))
  • setter: A smart setter (handle property setter itself)
  • setter_fallback: A dumb setter method (don't handle individual property setter)
  • setter_class: A module with individual property getter/setter
  • setter_prefix: A special setter prefix (like "set" or "set_" (default))
  • auto_emit: Emit "property::__" automatically (default: false). This is ignored when setterfallback is set or a setter is found

Parameters:

Name Type(s) Description Default value
class A standard luaobject derived object Not applicable
args Optional table A set of accessors configuration parameters {}
generated by LDoc 1.5.0 based on AwesomeWM template