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.

Note that it is also possible to listen to signal on the parent class too. In that case, the signal handler first argument will be the object sending the signal and all other arguments will be the same as they are when connecting directly to the object.

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=2]) -> 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) Disonnect 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:

  • args The arguments
    • enable_properties boolean Automatically call getters and setters (default false)
    • enable_auto_signals boolean Generate "property::xxxx" signals when an unknown property is set. (default false)
    • class table (default 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

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

Parameters:

  • name string The signal name.
  • ... The signal callback arguments
t.disconnect_signal (name, func)
Disconnect a signal from a source.

Parameters:

  • 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=2]) -> string
Helper function to get the module name out of debug.getinfo.

Parameters:

  • level integer Level for debug.getinfo(level, "S"). Typically 2 or 3. (default 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 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 string The name of the signal.
  • func function The callback to call when the signal is emitted.
:disconnect_signal (name, func)
Disonnect from a signal.

Parameters:

  • name string The name of the signal.
  • func function The callback that should be disconnected.
:emit_signal (name, ...)
Emit a signal.

Parameters:

  • 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:

  • class A standard luaobject derived object
  • args table A set of accessors configuration parameters (default {})
generated by LDoc 1.4.6 Last updated 2021-11-13 00:35:50