Class gears.object - awesome API documentation

# 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

gears.object ([args={}]) | Returns a new object.

## Methods

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

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

## Functions

Methods

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

  - 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)

## Methods

gears.object:connect_signal (name, func)

  Connect to a signal.

  Usage example output:

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

  - 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'

gears.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
gears.object:disconnect_signal (name, func)
  Disonnect to a signal.
  - name string The name of the signal
  - func function The callback that should be disconnected
gears.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: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)

## 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
  - class A standard luaobject derived object
  - args table A set of accessors configuration parameters (default {})

generated by LDoc 1.5.0 Last updated 2025-09-27 02:02:16