Merge lp:~mcfletch/simplegc/tutorial-skeleton into lp:simplegc

[Mike C. Fletcher]

Attempt to make the hello world tutorial easier to maintain, as well as making each iterative version much shorter (basically just a single function, an import, and an if __name__ block). Not yet completed (e.g. the 3 subsequent scripts are not described yet), so not yet replacing the original tutorial.

=== modified file 'docs/dev.widget.rst'
--- docs/dev.widget.rst	2012-08-16 11:38:47 +0000
+++ docs/dev.widget.rst	2012-08-18 21:38:22 +0000
@@ -175,7 +175,8 @@
 
 We can utilise events in our widget by defining an `on_[name]()` method. The
 method must be prefixed with "on\_" to ensure the event can be set through the
-config() method automatically and to ensure the EventSlot object will work.
+config() method automatically and to ensure the :py:class:`sgc.locals.EventSlot` 
+object will work.
 
 .. literalinclude:: ../example/custom_widget.py
     :linenos:

=== added file 'docs/tutorial.helloworld.rst'
--- docs/tutorial.helloworld.rst	1970-01-01 00:00:00 +0000
+++ docs/tutorial.helloworld.rst	2012-08-18 21:38:22 +0000
@@ -0,0 +1,68 @@
+Getting Started
+---------------
+
+Simple Game Code (SGC) attempts to follow Pygame's conventions 
+and usage, so your SGC code will tend to look much like any 
+Pygame module. 
+
+Imports
++++++++
+
+Your SGC script will need many symbols from both Pygame and 
+SGC.
+
+.. literalinclude:: ../example/hellobase.py
+   :end-before: main
+
+Overall Strategy
+++++++++++++++++
+
+Your script needs to do the following to work with SGC:
+
+ * Initialize :py:mod:`pygame` and :py:mod:`pygame.font`
+ * Create a :py:class:`sgc.surface.Screen` instance
+ * Create a :py:class:`pygame.time.Clock` instance to track inter-frame timings
+ * Create some SGC widgets
+ * Start a loop that:
+ 
+   * Gets the current time 
+   * Processes pending Pygame events with SGC :py:func:`sgc.event`
+   * Redraws/refreshes the screen
+
+.. literalinclude:: ../example/hellobase.py
+    :pyobject: main
+
+Processing Events
++++++++++++++++++
+
+SGC needs to process all events that come from Pygame.  The easiest way to do this 
+is to insert :py:func:`sgc.event` into your standard Pygame-style event processing 
+loop:
+
+.. literalinclude:: ../example/hellobase.py
+    :pyobject: process_events
+
+Updating the Screen
++++++++++++++++++++
+
+SGC also needs to be able to draw its widgets onto the screen on each frame.  To 
+do this it needs to know how long has passed since the last frame (to allow for 
+updating animated frames and the like).
+
+.. literalinclude:: ../example/hellobase.py
+    :pyobject: draw_screen
+
+Putting it All Together
+++++++++++++++++++++++++
+
+Our code so far just creates a blank Screen and updates it 
+every frame.  We'll save it into a file named ``hellobase.py``
+and use it throughout the rest of this tutorial:
+
+.. literalinclude:: ../example/hellobase.py
+    :language: python
+    :linenos:
+
+The file is available as ``example/hellobase.py`` in the 
+source distribution.  We'll use it in the next sections where 
+we will define functions to render some widgets.

=== modified file 'docs/tutorial.rst'
--- docs/tutorial.rst	2012-06-20 10:55:59 +0000
+++ docs/tutorial.rst	2012-08-18 21:38:22 +0000
@@ -16,5 +16,6 @@
     :maxdepth: 1
 
     tutorial.get_started
+    tutorial.helloworld
     tutorial.events
     tutorial.theming

=== added file 'example/hellobase.py'
--- example/hellobase.py	1970-01-01 00:00:00 +0000
+++ example/hellobase.py	2012-08-18 21:38:22 +0000
@@ -0,0 +1,49 @@
+#! /usr/bin/env python
+import sgc
+from sgc.locals import *
+
+import pygame
+from pygame.locals import *
+
+def main(create_widgets):
+    """Mainloop for the hello world tutorial code"""
+    # Initialize the pygame modules we need
+    pygame.display.init()
+    pygame.font.init()
+
+    # Create a drawing surface
+    screen = sgc.surface.Screen((640,480))
+
+    # Create a clock to update the screen with current time
+    clock = pygame.time.Clock()
+    # Create our SGC widgets
+    create_widgets( screen )
+
+    while True:
+        # get duration to update widgets
+        time = clock.tick(30)
+        process_events()
+        draw_screen(screen, time)
+
+def process_events():
+    """Process waiting events from Pygame using SGC"""
+    for event in pygame.event.get():
+        # Tell SGC to process its events
+        sgc.event(event)
+        # Now check for non-GUI events you'd like to handle...
+        if event.type == QUIT:
+            exit()
+
+def draw_screen(screen, time):
+    """Draw the current state of the screen
+    
+    screen -- :py:class:`sgc.surface.Screen` instance
+    time -- time-delta as provided by Clock.tick()
+    """
+    screen.fill((0,0,0))
+    # tell SGC to draw its widgets
+    sgc.update(time)
+    pygame.display.flip()
+
+if __name__ == "__main__":
+    main(lambda screen: None)

=== added file 'example/helloworld-01.py'
--- example/helloworld-01.py	1970-01-01 00:00:00 +0000
+++ example/helloworld-01.py	2012-08-18 21:38:22 +0000
@@ -0,0 +1,9 @@
+from hellobase import *
+
+def create_widgets(screen):
+    """Create a simple button"""
+    btn = sgc.Button(label="Does Nothing", pos=('50%','50%'))
+    btn.add(0)
+
+if __name__ == "__main__":
+    main(create_widgets)

=== added file 'example/helloworld-02.py'
--- example/helloworld-02.py	1970-01-01 00:00:00 +0000
+++ example/helloworld-02.py	2012-08-18 21:38:22 +0000
@@ -0,0 +1,10 @@
+from hellobase import *
+
+def create_widgets(screen):
+    """Create a button, align it to the bottom-right corner of the screen"""
+    btn = sgc.Button(label="Bottom Right", pos=(0,0))
+    btn.rect.bottomright = screen.rect.bottomright
+    btn.add(0)
+
+if __name__ == "__main__":
+    main(create_widgets)

=== added file 'example/helloworld-03.py'
--- example/helloworld-03.py	1970-01-01 00:00:00 +0000
+++ example/helloworld-03.py	2012-08-18 21:38:22 +0000
@@ -0,0 +1,10 @@
+from hellobase import *
+
+def create_widgets(screen):
+    """Create a button, align it to the bottom-right corner of the screen"""
+    btn = sgc.Button(label="Exit", on_click=lambda *args: exit())
+    btn.rect.bottomright = screen.rect.bottomright
+    btn.add(0)
+
+if __name__ == "__main__":
+    main(create_widgets)

=== modified file 'sgc/locals.py'
--- sgc/locals.py	2012-08-06 09:57:04 +0000
+++ sgc/locals.py	2012-08-18 21:38:22 +0000
@@ -17,25 +17,33 @@
 class EventSlot(object):
     """
     Event slots object. Allows dynamic allocation of events.
-
     """
 
     __slots__ = ("_funcs",)
 
     def __init__(self, widget, event, funcs=()):
         """
-        Args:
+        Arguments
+        
           widget: The widget you want to bind this event slot to.
           event: ``str`` The attribute you want to bind to (e.g. 'on_click').
           funcs: A sequence of functions you want to include by default.
 
         """
-        assert event.startswith("on_") and hasattr(widget, event), \
-            "Invalid event"
+        if not event.startswith("on_"):
+            raise ValueError( "Expected an event name starting with 'on_', got %r"%(
+                event,
+            ))
+        if not hasattr( widget, event ):
+            raise TypeError( "Event %r does not exist in %s widget"%(
+                event, widget.__class__,
+            ))
         self._funcs = list(funcs)
         setattr(widget, event, types.MethodType(self, widget, widget.__class__))
 
     def __call__(self, widget):
+        """Callback all registered functions for this event
+        """
         for f in self._funcs:
             f(widget)