Merge pull request #69 from ddemidov/button-doc

Improve documentation for Button and RemoteControl classes

Author: rhempel

docs/index.rst

@@ -101,6 +101,7 @@ Sensors
 
 .. autoclass:: RemoteControl
     :members:
+    :inherited-members:
 
 Other
 ^^^^^
@@ -113,6 +114,7 @@ Other
 
 .. autoclass:: Button
     :members:
+    :inherited-members:
 
 .. autoclass:: Sound
     :members:

ev3dev/core.py

@@ -1694,7 +1694,14 @@ class ButtonBase(object):
     Abstract button interface.
     """
 
-    on_change = None
+    @staticmethod
+    def on_change(changed_buttons):
+        """
+        This handler is called by `process()` whenever state of any button has
+        changed since last `process()` call. `changed_buttons` is a list of
+        tuples of changed button names and their states.
+        """
+        pass
 
     _state = set([])
 
@@ -1763,6 +1770,9 @@ def _button_buffer(self, name):
 
     @property
     def buttons_pressed(self):
+        """
+        Returns list of names of pressed buttons.
+        """
         for b in self._buffer_cache:
             fcntl.ioctl(self._button_file(b), self.EVIOCGKEY, self._buffer_cache[b])
 

ev3dev/ev3.py

@@ -109,19 +109,67 @@ def all_off():
 
 # ~autogen
 
-class Button(ButtonEVIO):
+class Button(object):
     """
     EV3 Buttons
     """
 
 # ~autogen button-property platforms.ev3.button>currentClass
 
-    on_up = None
-    on_down = None
-    on_left = None
-    on_right = None
-    on_enter = None
-    on_backspace = None
+    @staticmethod
+    def on_up(state):
+        """
+        This handler is called by `process()` whenever state of 'up' button
+        has changed since last `process()` call. `state` parameter is the new
+        state of the button.
+        """
+        pass
+
+    @staticmethod
+    def on_down(state):
+        """
+        This handler is called by `process()` whenever state of 'down' button
+        has changed since last `process()` call. `state` parameter is the new
+        state of the button.
+        """
+        pass
+
+    @staticmethod
+    def on_left(state):
+        """
+        This handler is called by `process()` whenever state of 'left' button
+        has changed since last `process()` call. `state` parameter is the new
+        state of the button.
+        """
+        pass
+
+    @staticmethod
+    def on_right(state):
+        """
+        This handler is called by `process()` whenever state of 'right' button
+        has changed since last `process()` call. `state` parameter is the new
+        state of the button.
+        """
+        pass
+
+    @staticmethod
+    def on_enter(state):
+        """
+        This handler is called by `process()` whenever state of 'enter' button
+        has changed since last `process()` call. `state` parameter is the new
+        state of the button.
+        """
+        pass
+
+    @staticmethod
+    def on_backspace(state):
+        """
+        This handler is called by `process()` whenever state of 'backspace' button
+        has changed since last `process()` call. `state` parameter is the new
+        state of the button.
+        """
+        pass
+
 
     _buttons = {
             'up': {'name': '/dev/input/by-path/platform-gpio-keys.0-event', 'value': 103},
@@ -134,26 +182,44 @@ class Button(ButtonEVIO):
 
     @property
     def up(self):
+        """
+        Check if 'up' button is pressed.
+        """
         return 'up' in self.buttons_pressed
 
     @property
     def down(self):
+        """
+        Check if 'down' button is pressed.
+        """
         return 'down' in self.buttons_pressed
 
     @property
     def left(self):
+        """
+        Check if 'left' button is pressed.
+        """
         return 'left' in self.buttons_pressed
 
     @property
     def right(self):
+        """
+        Check if 'right' button is pressed.
+        """
         return 'right' in self.buttons_pressed
 
     @property
     def enter(self):
+        """
+        Check if 'enter' button is pressed.
+        """
         return 'enter' in self.buttons_pressed
 
     @property
     def backspace(self):
+        """
+        Check if 'backspace' button is pressed.
+        """
         return 'backspace' in self.buttons_pressed
 
 

templates/button-property.liquid

@@ -1,12 +1,22 @@
 {% for instance in currentClass.instances %}
-    on_{{ instance.name }} = None{%
-endfor %}
+    @staticmethod
+    def on_{{ instance.name }}(state):
+        """
+        This handler is called by `process()` whenever state of '{{ instance.name }}' button
+        has changed since last `process()` call. `state` parameter is the new
+        state of the button.
+        """
+        pass
+{% endfor %}
 
     _buttons = {
 {% for instance in currentClass.instances %}            '{{ instance.name }}': {'name': '{{ currentClass.systemPath }}/{{ instance.systemName }}', 'value': {{ instance.systemValue }}},
 {% endfor %}        }
 {% for instance in currentClass.instances %}
     @property
     def {{ instance.name }}(self):
+        """
+        Check if '{{ instance.name }}' button is pressed.
+        """
         return '{{ instance.name }}' in self.buttons_pressed
 {% endfor %}