Class 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
  • Author: Uli Schlachter

Functions

object:connect_signal (name, func) Connect to a signal.
object:weak_connect_signal (name, func) Connect to a signal weakly.
object:disconnect_signal (name, func) Disonnect to a signal.
object:emit_signal (name, ...) Emit a signal.
gears.object ([args={}]) Returns a new object.
object.modulename ([level=2]) Helper function to get the module name out of debug.getinfo .


Functions

object:connect_signal (name, func)
Connect to a signal.
  • name string The name of the signal
  • func function The callback to call when the signal is emitted
object: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.
  • name string The name of the signal
  • func function The callback to call when the signal is emitted
object:disconnect_signal (name, func)
Disonnect to a signal.
  • name string The name of the signal
  • func function The callback that should be disconnected
object:emit_signal (name, ...)
Emit a signal.
  • 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 ([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 mathod 1 2 3 nil In the connection handler! a cow a cow

  • 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 mathod', 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)
object.modulename ([level=2])
Helper function to get the module name out of debug.getinfo .
  • 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)
generated by LDoc 1.4.2