--- a/getan/states.py	Fri Apr 05 19:01:54 2013 +0200
+++ b/getan/states.py	Fri Apr 05 19:14:03 2013 +0200
@@ -21,6 +21,18 @@
 logger = logging.getLogger()
 
 class State(object):
+    """ Represents a State of Getan
+
+    A State can be used to handle user input. The user input handling is done in
+    three phases. First it is possible to filter keys that shouldn't be passed
+    to a widget in input_filter. Afterwards it is possible to redirect a key to
+    a specific widget in keypress. In the third phase it is possible to act on
+    user input which isn't handled by a widget yet. The corresponing method is
+    handle_input.
+
+    Normally handle_input should be used to act on user input and change a
+    state.
+    """
 
     messages = {
     }
@@ -30,6 +42,25 @@
         self.view = view
         self.config = controller.get_config()
 
+    def input_filter(self, input, raw):
+        """Filters input that should not be passed to widget elements
+
+        By default no input is filtered and input is returned unchanged.
+        """
+        return input
+
+    def keypress(self, size, key):
+        """Redirects user input to the current view"""
+        self.view.keypress(size, key)
+
+    def handle_input(self, input):
+        """A derived State must implement handle_input"""
+        raise NotImplementedError()
+
+    def set_next_state(self, state):
+        """Sets the next state"""
+        self.controller.set_state(state)
+
     def msg(self, key):
         return self.messages[key]