Author: EvanCofsky
Date: 2008-04-19 16:00:51 -0400 (Sat, 19 Apr 2008)
New Revision: 1243
Modified:
trunk/pysoy/src/widgets/Canvas.pym
trunk/pysoy/src/widgets/Container.pym
trunk/pysoy/src/widgets/Projector.pym
trunk/pysoy/src/widgets/StackX.pym
trunk/pysoy/src/widgets/StackY.pym
trunk/pysoy/src/widgets/StackZ.pym
trunk/pysoy/src/widgets/Widget.pym
Log:
Ticket #894: Widget subclass documentation, coordinate documentation
fix.
It turns out that the 2-dimensional coordinates are in the GL
coordinate system and not hardware coordinates.
Added more documentation for all of the Widget subclasses. I think I
still need to make a pass at the properties, though.
Modified: trunk/pysoy/src/widgets/Canvas.pym
===================================================================
--- trunk/pysoy/src/widgets/Canvas.pym 2008-04-19 17:11:10 UTC (rev 1242)
+++ trunk/pysoy/src/widgets/Canvas.pym 2008-04-19 20:00:51 UTC (rev 1243)
@@ -18,21 +18,26 @@
# $Id$
cdef class Canvas (Widget) :
- ''' PySoy's Canvas
-
- This widget control adds a texture on top of a Projector.
- It can be stacked together with soy.textures.Font, to create display text
on the Projector.
-
- It accepts a texture and some placement arguments. It's parent should be
another widget,
- (probably a soy.Window). Aspect must be a positive value (Negative values
disables it).
-
- soy.Canvas can be used to display an image, or as a HUD, or even as a 2D
background, depending on
- the stack of Widgets. For example to display an image on top of the
projector, but also display a 2d
- background the Stack could be Canvas,Projector,Canvas.
-
- See also Widget,Projector,Window
- '''
+ """
+ Renders a L{Texture} on a L{Projector}. The order this is added to
+ the container along with the L{Projector} determines the order the
+ L{Canvas} is rendered relative to the L{Scene} in the L{Window}.
+ Since L{Texture}s can be any sort of bitmap, including text, images,
+ and video, adding a L{Canvas} to a L{Window} containing a video or
+ image before adding a L{Projector} will create a background. The
+ L{Canvas} will be rendered, then the L{Projector} will render the
+ scene, overwriting the L{Canvas} where scene elements overlap.
+
+ Adding a L{Canvas} after a L{Projector} with a L{Print} can also be
+ used to create a heads-up display. The L{Projector} renders the
+ scene, then the L{Canvas} renders the L{Print} texture on top of the
+ L{Scene}, overwriting the overlapping scene regions.
+
+ Even more effects can be created by combining L{Canvas}es with the
+ different L{Container} subclasses.
+ """
+
############################################################################
#
# Python functions
@@ -107,10 +112,10 @@
#
property texture :
- '''Canvas texture
+ """Canvas texture
This is the texture to render on the canvas. Default is None.
- '''
+ """
def __get__(self) :
if self._texture :
return self._texture
Modified: trunk/pysoy/src/widgets/Container.pym
===================================================================
--- trunk/pysoy/src/widgets/Container.pym 2008-04-19 17:11:10 UTC (rev
1242)
+++ trunk/pysoy/src/widgets/Container.pym 2008-04-19 20:00:51 UTC (rev
1243)
@@ -18,12 +18,42 @@
# $Id: Container.pxi 1038 2008-03-05 00:36:38Z ArcRiley $
cdef class Container (Widget) :
- '''PySoy widgets.Container Class
+ """
+ L{Widget} class providing the base L{Container}. L{Widget}
+ instances may be added to a L{Window} instance, or to a L{Container}
+ subclass. L{Container} itself is an abstract class and can't be
+ instantiated directly.
- Container is the base class for any widget that 'contains' other
- widgets. This is NOT meant to be used directly.
- '''
+ L{Container} classes manage the positioning of the widgets they
+ contain. They also propogate the C{_render} method calls to their
+ contained L{Widgets}.
+ Type Methods
+ ============
+
+ __cinit__
+ ---------
+
+ This initializes the internal list of L{Widgets} as a new
+ L{soy._internals.Children}.
+
+ _resize
+ -------
+
+ This method should be overridden in subclasses to calculate the
+ new sizes and positions of the child L{Widgets} within the
+ region described by the passed position and size. NOTE: The _x
+ and _y parameters passed are always relative to the origin of
+ the top-level L{Window} containing the L{Widget}, and not to the
+ containing L{Widget}.
+
+ _render
+ -------
+
+ This should be overridden if necessary to pass the _render call
+ along to child L{Widget}s.
+ """
+
############################################################################
#
# Python functions
Modified: trunk/pysoy/src/widgets/Projector.pym
===================================================================
--- trunk/pysoy/src/widgets/Projector.pym 2008-04-19 17:11:10 UTC (rev
1242)
+++ trunk/pysoy/src/widgets/Projector.pym 2008-04-19 20:00:51 UTC (rev
1243)
@@ -18,17 +18,12 @@
# $Id$
cdef class Projector (Widget) :
- '''soy.widgets.Projector
+ """
+ Displays the output of a L{soy.bodies.Camera}. This uses its
+ position and size to set up the GL Viewport and the L{Camera}
+ parameters to set the gluPerspective parameters.
+ """
- Creates a suitable container for display of the output of a camera. The
- result can be placed on to soy.Screen for example and can
- be viewed.
-
- It accepts a soy.Camera, as well as other placement arguments.
-
- See also soy.Widget, soy.Camera, soy.Screen
- '''
-
############################################################################
#
# Python functions
@@ -72,11 +67,11 @@
#
property camera :
- '''Projection Camera
-
- This is the camera currently attached to the projector widget. It may be
- changed to a different soy.bodies.Camera or None to disable projection.
- '''
+ """The L{soy.bodies.Camera} attached to this L{Projector}. This
+ can be changed to different cameras which have different
+ perspective parameters. This L{Projector} can also be disabled by
+ setting this to C{None} or deleting it.
+ """
def __get__(self) :
return self._camera
def __set__(self, value) :
Modified: trunk/pysoy/src/widgets/StackX.pym
===================================================================
--- trunk/pysoy/src/widgets/StackX.pym 2008-04-19 17:11:10 UTC (rev 1242)
+++ trunk/pysoy/src/widgets/StackX.pym 2008-04-19 20:00:51 UTC (rev 1243)
@@ -18,11 +18,12 @@
# $Id$
cdef class StackX (Container) :
- '''PySoy widgets.StackX Class
+ """
+ Provides horizontal packing for L{Widget}s. Children are packed
+ from left to right. Each child is given equal horizontal space and
+ the full vertical space of the L{StackX}.
+ """
- This stacking widget packs children horizontally without overlap.
- '''
-
############################################################################
#
# C functions
Modified: trunk/pysoy/src/widgets/StackY.pym
===================================================================
--- trunk/pysoy/src/widgets/StackY.pym 2008-04-19 17:11:10 UTC (rev 1242)
+++ trunk/pysoy/src/widgets/StackY.pym 2008-04-19 20:00:51 UTC (rev 1243)
@@ -18,11 +18,12 @@
# $Id$
cdef class StackY (Container) :
- '''PySoy widgets.StackY Class
+ """
+ Provides vertical packing for L{Widget}s. Children are packed from
+ top to bottom. Each child is given equal vertical space and the
+ full horizontal space of the L{StackX}.
+ """
- This stacking widget packs children vertically without overlap.
- '''
-
############################################################################
#
# C functions
Modified: trunk/pysoy/src/widgets/StackZ.pym
===================================================================
--- trunk/pysoy/src/widgets/StackZ.pym 2008-04-19 17:11:10 UTC (rev 1242)
+++ trunk/pysoy/src/widgets/StackZ.pym 2008-04-19 20:00:51 UTC (rev 1243)
@@ -18,12 +18,14 @@
# $Id$
cdef class StackZ (Container) :
- '''PySoy widgets.StackZ Class
+ """
+ Provides stacking of L{Widget} from front to back as layers. This
+ is identical to the way L{Window} stacks top-level L{Widget}s.
+ Fundamentally this is an implicit Z-order stack from first added to
+ last. Clipping and masking are not handled explicitly, rather,
+ closer children are drawn after farther children.
+ """
- This stacking widget overlaps children as "layers". This behavior is
- identical to how a soy.Window stacks top-level widgets. Z widget indexing.
- '''
-
############################################################################
#
# C functions
Modified: trunk/pysoy/src/widgets/Widget.pym
===================================================================
--- trunk/pysoy/src/widgets/Widget.pym 2008-04-19 17:11:10 UTC (rev 1242)
+++ trunk/pysoy/src/widgets/Widget.pym 2008-04-19 20:00:51 UTC (rev 1243)
@@ -61,9 +61,9 @@
----------------
L{Widget} coordinates are physical pixels from the
- L{Window} origin. Unlike GL coordinate space, and very
- much like the hardware corrdinate plane, they increase
- from the Origin at (0, 0) down and to the right.
+ L{Window} origin in the GL coordinate space. The origin
+ is located at the bottom left corner of the L{Window}, and
+ increase up and to the right.
Parents
=======
_______________________________________________
PySoy-SVN mailing list
PySoy-SVN@pysoy.org
http://www.pysoy.org/mailman/listinfo/pysoy-svn
