Author: EvanCofsky
Date: 2008-04-19 13:11:10 -0400 (Sat, 19 Apr 2008)
New Revision: 1242
Modified:
trunk/pysoy/src/widgets/Widget.pym
Log:
Ticket #894: Documented soy.widgets.Widget.
Also mentioned the coordinate plane, aspect/margin, and the C methods.
Modified: trunk/pysoy/src/widgets/Widget.pym
===================================================================
--- trunk/pysoy/src/widgets/Widget.pym 2008-04-19 02:38:05 UTC (rev 1241)
+++ trunk/pysoy/src/widgets/Widget.pym 2008-04-19 17:11:10 UTC (rev 1242)
@@ -18,22 +18,123 @@
# $Id$
cdef class Widget :
- '''Widget Class
+ """
+ Widgets are two-dimensional surfaces contained in a
+ L{soy.window.Window} or in a L{Container}. The size of each
+ L{Widget} is calculated from the size of its parent using the
+ L{margin}, and if not M{aspect > 0} the L{aspect}.
- A Widget is a 2d section/layer in a soy.window.Window. This is the base
- class which all widgets inherit, it has no render functionality.
-
- It accepts some placement arguments as well as an aspect argument.
- Aspect must be a positive value (Negative values disables it).
-
- Classes that inherit soy.Widget:
- -soy.Widget.Projector
- -soy.Widget.Canvas
- -soy.Widget.StackX
- -soy.Widget.StackY
- -soy.Widget.StackZ
- '''
+ Optional properties available on constructor:
+ @type parent : L{soy.window.Window} or L{Container}
+ @param parent : If None: this L{widget} is inactive
+ If not None: The two-dimensial surface
+ containing this
+ L{Widget}.
+
+ @type margin : tuple(int, int, int, int)
+ @param margin : The amount of space to leave inside
+ the bounding edges of L{parent} for
+ the bounding edges of this L{Widget}.
+ In order, the numbers are the margins
+ for the top, right, bottom, and left
+ from the corresponding edges of
+ L{parent}.
+
+ @type aspect : float
+ @param aspect : If <= 0: not used
+ If > 0: the ratio of wdith and height
+ constraining this L{Widget}.
+
+ Widget Sizing
+ =============
+
+ Margin and Aspect
+ -----------------
+
+ The L{Widget} is first constrained to the margin inside
+ the parent's borders. Then, L{aspect} calculations are
+ applied to reduce the dimension that is longer than the
+ aspect ratio would allow.
+
+ Units and Origin
+ ----------------
+
+ 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.
+
+ Parents
+ =======
+
+ Behavior of L{Widget} sizing is slightly different depending
+ on whether the parent is a L{soy.window.Window} or a
+ L{Container}. L{__cinit__} will initialize the L{Widget}
+ differently. The Parent cannot be changed after
+ initialization.
+
+ Top-Level Widgets
+ -----------------
+
+ L{Widget} instances placed directly into a
+ L{soy.window.Window} are X{Top Level} L{Widget}s. The size of
+ these is managed by the containing L{Window}. All L{Widget}s
+ contained in a L{Window} are added to the _widgets list of the
+ L{Window}, even L{Widgets} not directly parenting that
+ L{Window}. When the L{Window} changes size, however, it only
+ resizes the Top Level L{Widget}s directly. Other L{Widget}s
+ are managed by their L{Container}s.
+
+ Type Methods
+ ============
+
+ The methods of the extension type L{Widget} manage the size
+ and aspect ratio constraints inside the L{parent} surface.
+
+ __cinit__
+ ---------
+
+ This initializes the C C{struct} of L{Widget}. If
+ L{parent} is None, this just initializes the L{margin} and
+ L{aspect}.
+
+ If L{parent} is specified, this will also add a reference
+ to the new L{Widget} to the L{Widget} list of the
+ L{soy.window.Window} of L{parent}. This new L{Widget} is
+ then sized using the _resize method.
+
+ __dealloc__
+ -----------
+
+ If this L{Widget} has a L{Window}, this is removed from
+ the L{Window}'s L{Widget} list.
+
+ If this L{Widget} has a parent, it is removed from the
+ parent's _widgets.
+
+ _setMargin
+ ----------
+
+ This handles interpreting the L{margin} property. If the
+ margin was set, this returns 1. Otherwise, it returns 0.
+
+ _render
+ -------
+
+ This is called by the parent when this widget should
+ render its appearance. In L{Widget} itself, this does
+ nothing. Subclasses should implement this.
+
+ _resize
+ -------
+
+ This handles the margin and aspect calculations to set the
+ position and size of this widget. It is called by the
+ parent when the parent changes size, and by __cinit__ to
+ set the initial size and position.
+ """
+
############################################################################
#
# Python functions
@@ -162,30 +263,58 @@
#
property margin :
- '''Widget's margin
+ """
+ The four margins of the widget from the edges of it's parent.
+ Values are for the top, right, bottom, and left, like the I{CSS}
+ C{margin:}.
- These are the four margins of the widget respective to it's parent.
- Values are for the top, right, bottom, and left (as with CSS margin:)
+ C{margin} can be interpreted in four ways depending on its length.
+ It is always an C{int} or a sequence of C{int}. It is used to set
+ the top, right, bottom, and left margins.
+
+ 1. If margin evaluates to False, all four margins are set to
+ zero.
+
+ 2. A single C{int} or a one-item sequence sets all four
+ margins to the passed margin.
- Defaults to (0, 0, 0, 0)
- '''
+ 3. A two-item sequence sets the top and bottom margins to the
+ first item, and the left and right margins to the second.
+
+ 4. A three-item sequence sets the top, horizontal, and bottom
+ margins. The top margin is set to the first item, the
+ left and right margins are set to the second, and the
+ bottom margin is set to the third.
+
+ 5. A four-item sequence sets the four margins independently
+ in order of Top, Right, Bottom, and Left.
+
+ Defaults to M{margin = (0, 0, 0, 0)}, filling the parent
+ completely.
+ """
+
def __get__(self) :
return (self._marginTop, self._marginRight,
self._marginBottom, self._marginLeft)
+
def __set__(self, margin) :
if not self._setMargin(margin) :
raise TypeError('margin must be a (int, int, int, int)')
+
def __del__(self) :
self._setMargin(None)
-
property aspect :
- '''Widget's aspect ratio
+ """
+ Aspect ratio of L{Widget} constraining the size within the
+ L{margin}. If not M{aspect > 0.0}, this will be used by
+ L{_resize} to set the size of this widget within the L{margin} so
+ that M{width / height = aspect}. If M{aspect = 0}, the L{Widget}
+ is sized to fill L{margin} completely.
- This is the ratio of width:height which, if set, will be maintained.
+ Defaults to M{aspect = 0.0}, filling the L{margin} completely.
+ """
- Defaults to disabled (0.0)
- '''
def __get__(self) :
return self._aspect
def __set__(self, aspect) :
@@ -197,20 +326,23 @@
property position :
- '''Widget's position
+ """
+ The position of the L{Widget} relative to its L{Window}. This is
+ calculated internally in L{_resize} by using the L{margin} and
+ L{aspect} properties. This is a C{tuple(int, int)}.
+ """
- This is the position of the widget reletive to the window.
- Use the parent, margin, and aspect properties to change this value.
- '''
def __get__(self) :
return (self._xpos, self._ypos)
property size :
- '''Widget's size
+ """
+ Dimensions of L{Widget} in pixels. This is calculated internally
+ in L{_resize} by using the L{margin} and L{aspect} properties. It
+ is a C{tuple(int, int)}.
- This is the pixel size of the widget. It cannot be set.
- '''
+ """
def __get__(self) :
return (self._width, self._height)
_______________________________________________
PySoy-SVN mailing list
PySoy-SVN@pysoy.org
http://www.pysoy.org/mailman/listinfo/pysoy-svn
