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.

lib.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.

Usage example output:

In get foo  bar
bar
In set foo  42
In get foo  42
42
In a method 1   2   3
nil
In the connection handler!  a cow
a cow

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

Usage:

    -- Create a class for this object. It will be used as a backup source for
-- methods and accessors. It is also possible to set them directly on the
-- object.
local class = {}
function class:get_foo()
    print("In get foo", self._foo or "bar")
    return self._foo or "bar"
end
function class:set_foo(value)
    print("In set foo", value)
    -- In case it is necessary to bypass the object property system, use
    -- rawset
    rawset(self, "_foo", value)
    -- When using custom accessors, the signals need to be handled manually
    self:emit_signal("property::foo", value)
end
function class:method(a, b, c)
    print("In a method", a, b, c)
end
local o = gears.object {
    class               = class,
    enable_properties   = true,
    enable_auto_signals = true,
}
print(o.foo)
o.foo = 42
print(o.foo)
o:method(1, 2, 3)
-- Random properties can also be added, the signal will be emitted automatically.
o:connect_signal("property::something", function(obj, value)
    assert(obj == o)
    print("In the connection handler!", value)
end)
print(o.something)
o.something = "a cow"
print(o.something)

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.

Usage example output:

In slot [obj]   nil nil nil
In slot [obj]   foo bar 42

Parameters:

Name Type(s) Description
name string The name of the signal.
func function The callback to call when the signal is emitted.

Usage:

    local o = gears.object{}
-- Function can be attached to signals
local function slot(obj, a, b, c)
    print("In slot", obj, a, b, c)
end
o:connect_signal("my_signal", slot)
-- Emitting can be done without arguments. In that case, the object will be
-- implicitly added as an argument.
o:emit_signal "my_signal"
-- It is also possible to add as many random arguments are required.
o:emit_signal("my_signal", "foo", "bar", 42)
-- Finally, to allow the object to be garbage collected (the memory freed), it
-- is necessary to disconnect the signal or use weak_connect_signal
o:disconnect_signal("my_signal", slot)
-- This time, the slot wont be called as it is no longer connected.
o:emit_signal "my_signal"
🔗 :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()

lib.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