From d6a7b6c645b9e75decd1aa9b038d9054a1c2556b Mon Sep 17 00:00:00 2001
From: Emmanuel Lepage Vallee <elv1313@gmail.com>
Date: Tue, 17 May 2016 01:17:22 -0400
Subject: [PATCH] object: Add a dynamic property example

---
 lib/gears/object.lua                          |  1 +
 .../examples/text/gears/object/properties.lua | 55 +++++++++++++++++++
 2 files changed, 56 insertions(+)
 create mode 100644 tests/examples/text/gears/object/properties.lua

diff --git a/lib/gears/object.lua b/lib/gears/object.lua
index 7bf63de3d..85bfcc3c2 100644
--- a/lib/gears/object.lua
+++ b/lib/gears/object.lua
@@ -169,6 +169,7 @@ end
 -- Note that `args.enable_auto_signals` is only supported when
 -- `args.enable_properties` is true.
 --
+--@DOC_text_gears_object_properties_EXAMPLE@
 -- @tparam[opt={}] table args The arguments
 -- @tparam[opt=false] boolean args.enable_properties Automatically call getters and setters
 -- @tparam[opt=false] boolean args.enable_auto_signals Generate "property::xxxx" signals
diff --git a/tests/examples/text/gears/object/properties.lua b/tests/examples/text/gears/object/properties.lua
new file mode 100644
index 000000000..032ff9cce
--- /dev/null
+++ b/tests/examples/text/gears/object/properties.lua
@@ -0,0 +1,55 @@
+local gears = require("gears") --DOC_HIDE
+
+ -- Create a class for this object. It will be used as a backup source for
+ -- methods and acessors. It is also possible to set them diretly 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,
+}
+
+o:add_signal "property::foo"
+
+print(o.foo)
+ 
+o.foo = 42
+ 
+print(o.foo)
+ 
+o:method(1, 2, 3)
+
+ -- Random properties can also be added, the signal will be emited automatically.
+o:add_signal "property::something"
+
+o:connect_signal("property::something", function(obj, value)
+    print("In the connection handler!", obj, value)
+end)
+
+print(o.something)
+ 
+o.something = "a cow"
+ 
+print(o.something)