Commits

Devin Jeanpierre committed 63bdbe5 Draft

Fixed some docstrings

Comments (0)

Files changed (1)

pygame_display.py

         """
         Enable mouse tracking.
 
-        After calling this function get_input will include mouse
-        click events along with keystrokes.
+        After calling this function, the screen will also grab mouse events
+        from the Pygame event list, and provide equivalent events to urwid.
         """
         self._listening_events += MOUSE_EVENTS
 
     def start(self):
         """
         Initialize the screen and input mode.
+
+        Ensures that the screen has a surface to draw to.
         """
         
         super(BaseSurfaceScreen, self).start()
     def set_terminal_properties(self, colors=None, bright_is_bold=None,
         has_underline=None):
         """
-        colors -- number of colors terminal supports (1, 16, 88 or 256)
-            or None to leave unchanged
-        bright_is_bold -- set to True if this terminal uses the bold 
-            setting to create bright colors (numbers 8-15), set to False
-            if this Terminal can create bright colors without bold or
-            None to leave unchanged
-        has_underline -- set to True if this terminal can use the
-            underline setting, False if it cannot or None to leave
-            unchanged
+        Do nothing (Pygame is not a terminal, and has 24-bit color support.)
         """
         pass # XXX: I don't think we need to care, do we?
 
     def set_input_timeouts(self, max_wait=None, complete_wait=0.1, 
         resize_wait=0.1):
         """
-        Set the get_input timeout values.  All values have a granularity
-        of 0.1s, ie. any value between 0.15 and 0.05 will be treated as
-        0.1 and any value less than 0.05 will be treated as 0.  The
-        maximum timeout value for this module is 25.5 seconds.
-    
-        max_wait -- amount of time in seconds to wait for input when
-            there is no input pending, wait forever if None
-        complete_wait -- amount of time in seconds to wait when
-            get_input detects an incomplete escape sequence at the
-            end of the available input
-        resize_wait -- amount of time in seconds to wait for more input
-            after receiving two screen resize requests in a row to
-            stop urwid from consuming 100% cpu during a gradual
-            window resize operation
+        Do nothing (Pygame screens do not block.)
         """
         
         pass # XXX: so far I've kept timeouts nonexistent, do they matter?
         pass
     
     def get_input(self, raw_keys=False):
-        """Return pending input as a list.
+        """
+        Fetch input from the pygame event buffer and translate to a keylist.
 
-        raw_keys -- return raw keycodes as well as translated versions
+        The following two lines are equivalent::
 
-        This function will immediately return all the input since the
-        last time it was called.  If there is no input pending it will
-        wait before returning an empty list.  The wait time may be
-        configured with the set_input_timeouts function.
-
-        If raw_keys is False (default) this function will return a list
-        of keys pressed.  If raw_keys is True this function will return
-        a ( keys pressed, raw keycodes ) tuple instead.
-        
-        Examples of keys returned
-        -------------------------
-        ASCII printable characters:  " ", "a", "0", "A", "-", "/" 
-        ASCII control characters:  "tab", "enter"
-        Escape sequences:  "up", "page up", "home", "insert", "f1"
-        Key combinations:  "shift f1", "meta a", "ctrl b"
-        Window events:  "window resize"
-        
-        When a narrow encoding is not enabled
-        "Extended ASCII" characters:  "\\xa1", "\\xb2", "\\xfe"
-
-        When a wide encoding is enabled
-        Double-byte characters:  "\\xa1\\xea", "\\xb2\\xd4"
-
-        When utf8 encoding is enabled
-        Unicode characters: u"\\u00a5", u'\\u253c"
-
-        Examples of mouse events returned
-        ---------------------------------
-        Mouse button press: ('mouse press', 1, 15, 13), 
-                            ('meta mouse press', 2, 17, 23)
-        Mouse button release: ('mouse release', 0, 18, 13),
-                              ('ctrl mouse release', 0, 17, 23)
+            screen.get_input(True)
+            screen.translate_pygame_events(pygame.event.get())
         """
+        assert self._started
         keys, raws = self.translate_pygame_events(pygame.event.get())
         return (keys, raws) if raw_keys else keys
 
     def translate_pygame_events(self, events):
-        assert self._started
+        """Convert a list of pygame events to an urwid keylist.
+
+        This method is particularly useful in combination with
+        MainLoop.process_input()
+        """
         keys = []
         raws = []
         
         return (self._width, self._height)
 
     def draw_screen(self, (cols, rows), r ):
-        """Paint screen with rendered canvas."""
+        """Paint to the target surface with rendered canvas."""
         # TODO: r.cursor
         assert self._started
         
         self._listening_events += (pygame.VIDEORESIZE,)
 
     def start(self):
+        """Initialize pygame and open a pygame window for drawing to."""
         resolution = compute_resolution(
             self._resolution,
             self._font_size,
         super(Screen, self).start()
 
     def stop(self):
+        """Deinitialize pygame and close the window.
+
+        This does not prevent start() from being called again to reopen a
+        window.
+        """
         super(Screen, self).stop()
         pygame.display.quit()