[reportlab-users] Widgets as Flowables...

[Andy Robinson]

> Undoing features?? ;-) As an aside, I've browsed the Graphics Guide
> again and I found very sloppy and vague usage of the term "Drawing",
> where it is often unclear if it means the Drawing class or just the
> "idea" or concept of a drawing.

You are right.  It is a long time since we put real time into that.
We did identify some volunteers to help with docco, and maybe that's
the manual that needs it most.  Somebody has to sit down and "write
the whole thing" making sure it is coherent and tells a story, not
just (far too occasionally) fixing things.

> 
> I've also seen examples of widgets returning a Drawing instance in
> their demo() method, which I guess is not the way it should be (un-
> less, of course, that was the proclaimed idea behind the demo method).

It is exactly the idea of the Demo method.  It returns a drawing, so
the thing which crawls through the code can get drawings and draw
them alongside the docco.  If we knew the size of a widget we 
could dispense with this (making a drwaing ourselves) and if
we could draw widgets directly then we could take a raw initialised
widget (having optional getDemos() method if you wanted to show 
special things).  

It's a combination of "first try at widgets" and "first try at literate 
programming" and both could be improved, especially where they meet.

> What I really miss is a collection of stories explaining the intended
> functionality, but then, this is a different school again... ;-)

That IS a good point and we should be able to handle that, especially
if we start to package up Diagra for commercial use.  Essentially
we'd have a Diagra user's guide showing people how to make and
deploy charts non-graphically, and a "programmers' guide" which
taught Python programmers how to write or change widget collections;
the latter would be a rewrite of the existing "Graphics Guide".

I really do believe the "literate programming" idea can apply to this,
but we were not O-O enough.  That's a separate essay, and may depend on
us being able to handle reStructuredText...

- Andy