The new documentation looks really good, John... a few comments:
(in BlocksWidgetsEventsCollections...)
- You explain the block-widget relationship in terms of
model-view-controller, but you don't mention who the controller is.
Philosophically, I think of the content/domain model (the collection or
item in your diagram) as the model and the Block as the controller, but
that's a specific interesting point about our architecture: the block
has controller- and model-like characteristics. I think this is an
important thing to make clearer here, since it's novel.
(in IntroductionToBlocks...)
- The first paragraph seems rushed, and introduces a slew of new
classnames without much supporting info. I don't know whether a picture
would help here, or just more verbiage, but it seems like that section
would be clearer if the paragraph were broken into several that each
introduced a concept: The UI is a hierarchy of blocks with
parentBlock/childrenBlocks relationships; most blocks are subclasses of
RectangularChild, which own a chunk of two-dimensional space for their
children; BoxContainer is a RectangularChild that adds sizing/layout
behavior; and MainViewRoot's the root of the hierarchy, and it's found
at startup time.
- The BranchPointBlock introduction starts with the way we use it to
host the entire UI; developers are more likely to encounter its other
uses (between sidebar & summary, or summary and detail view) first, then
maybe note at the end that we use it to host the UI.
- The BranchPointBlock's use of a delegate doesn't seem like part of the
MVC paradigm, I think it's more accurately the Delegate design pattern.
- When I was new, I found the name 'render' confusing: I'm used to
thinking of it as the drawing process, not the process of building up a
structure that'll later be used for drawing. If other folks were also
confused by this too, it might bear explanation.
- The MainView's Children section could really benefit from that simple
block diagram that we draw on the whiteboard every time we start talking
about the UI :-)
- I don't think the comment about ContextMenus & ContextMenuItems being
"flawed" adds anything at this point in the reader's education.
(in BlockEvents...)
- This document seems out of order... I think the dispatch mechanisms
discussion could come last... but maybe this document is still a
work-in-progress (I see that the first two paragraphs have a lot of the
same text...)
...Bryan
John Anderson wrote:
Hi:
I have drafts of 3 sections of the CPIA documentation ready for review
and I'd appreciate your feedback:
http://wiki.osafoundation.org/bin/view/Projects/BlocksWidgetsEventsCollections
http://wiki.osafoundation.org/bin/view/Projects/IntroductionToBlocks
http://wiki.osafoundation.org/bin/view/Projects/BlockEvents
I'll have more sections ready for review soon.
Thanks,
John
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
Open Source Applications Foundation "Dev" mailing list
http://lists.osafoundation.org/mailman/listinfo/dev
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
Open Source Applications Foundation "Dev" mailing list
http://lists.osafoundation.org/mailman/listinfo/dev
