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