[Pysdl-devel] rect class, design help

[Pete S. <psh...@me...>]

ok, i'm finishing up the rectangle class. as i finish up, i'd
like to get some quick help thinking some of the design through.

i'll start off with the quicker ones. my current thoughts
are at the end of each consideration in << >>
everyone please go ahead and doublecheck my logic


--- should rects return nonzero if only one of width or
height is 0? with a zero width or height, SDL isn't going
to do anything during blits or fills. on the other hand,
there is some size info still in there, this may be helpful
in some cases.
<<rect will return nonzero only if both width and height
are nonzero>>


--- operator math? i've been trying to think of clean and
useful cases to add operator math to the rectangle. (+-*%).
it could be useful for "rect += (10, 40)" to move a
rectangle. but there is effort needed to define all
the cases with clean and consistent usage
<<not planning for this (at least in first release). if
someone really wants this stuff, please compile a list
of all the operators you'd like to use, as well as what
types of arguments they can take and what the results
should be>>


--- when changing rectangle attributes, should the rect
automatically try to maintain non-negative values?
SDL is not happy with negative sized rectangles. so it
would be nice to try to avoid them alltogether. nonetheless
when a rect goes behind the scenes and changes your all your
numbers, things can get a bit confusing. there are a couple
ways to handle this. here's the test case... say we have a
rectangle with values "rect(10, 10, 100, 100)". this rectangle
spans from column 10 to 110 (width=100). let's say the user
changes the left edge to 200, "rect.left = 200". we have a
couple ways of handling this. the main plan with these rect
attributes is that changing one edge doesn't effect any of
the others (therefore, the right edge shouldn't move).
without any special handling, the resulting rectangle is
"rect(200, 10, -90, 100)". now we can either leave it like
this, or automatically flip the reverse width, to give us
rect(110, 10, 90, 100)". Now this is technically probably
what we'll end up wanting, but we just set the left edge to
200, and it comes back as 110. would this end up too confusing?
>>> rect.left = 200
>>> print rect.left
110
maybe i'm putting too much worry into this? the other last
minute option is to set the width to 0 when one of the edges
crosses over the other?
<<i'm currently planning to have the rect automatically fix
negative sizes. yes, there's potential for confusion, but i
can't think of a good case where one would actually want to
keep the negative value. plus all of the rects method results
become undefined when fed rects with negative sizes. so best
to take the extra step to avoid them>>


(whew, last one, and probably most important. send feedback!)

--- what should the return values/modification behavior be
for all of the rectangle methods. in the standard python
modules, the usual rule is, if a method changes the values
of "self", then it returns none. otherwise the method returns
a new object with the result of the changes, the original goes
unchanged. (a potential third option is to change the original
and return a reference to the original). ok, since this is
the most important one i want to make sure everyone understands
the full effects of this. for the method rect.clip, we have
three main strategies.
rect.clip can just change the rectangle it is working on ("self")
    and return nothing.
rect.clip can create a new rectangle with the results and return
    that.
rect.clip can modify "self" and return a reference to itself.
ok, the three options may not sound to different, here are the
CONS for each approach
"Only Change Self": with this approach, everytime you want
    to change something about a rect, it takes a separate
    line. some things can require a couple steps, and it
    makes it impossible to send values to functions with
    'on the fly' changes'. think of the list methods, like
    list.sort(), etc.
"Create New Rect": the drawback to this style, if you want to
    simply change the values of a rectangle, you need to make
    an extra assignment. "rect = rect.clip()"
"Change and return self": the problem here is it becomes very
    ambiguous, and goes against the 'unwritten' python standards.
    it makes a compromise between the other two styles.
<<my (unfinal) decision is for all methods to not change
themselves, but return a new rectangle with the results. this
gives the user undoubtedly the most flexibility, the only drawback
being you must reassign a rectangle to its method to change it
in place>>

anyways, don't be afraid to send in your opinions that are different
that what i've got here. i'm opened minded about all this, and would
love some help discussing some of these options all the way through.
(ie, it just struck me i haven't thought at all about needs for GUI)

the good news is it's really easy for me to switch between any
of these styles, but it'd be nice to nail it all down before 
a first release. (hard to change after that for other reasons :])