[Libreoffice-commits] .: Branch 'feature/layout' - README.layout

[Ricardo Cruz]

 README.layout |  115 +++++++++++++++++++++++++++++++++++-----------------------
 1 file changed, 70 insertions(+), 45 deletions(-)

New commits:
commit dff60d3279fa486d12c7b346f272a949f65ff1f2
Author: Ricardo Cruz <rpmcruz at alunos.dcc.fc.up.pt>
Date:   Thu Dec 16 17:16:11 2010 +0000

    Update README.layout information with a TODO and some code description.

diff --git a/README.layout b/README.layout
index b346e41..e10deab 100644
--- a/README.layout
+++ b/README.layout
@@ -1,46 +1,71 @@
+~ TODO ~
+
+* XML parser & factory
+* Property introspection
+    * XML parser support for properties
+* UI editor
+* Polishing: more containers? write a strategy
+  plan for porting dialogs, etc
+* Announcement: try to get people to
+  do some dialog porting.
+
+
+
+~ HACKING HOWTO ~
+
+Some information about the vcl layout code. Useful for both
+people who want to hack on it, or with it.
+
+
+align.hxx, box.hxx, notebook.hxx, buttonbox.hxx, table.hxx
+
+ The stars of the show.
+
+ They need testing: ie. Table I haven't tested at all. :D
+
+ The API is similar to that of GTK for familiarity value.
+
+ Their methods accept either Window or Layout widgets for
+ comfort. e.g.
+    Box::Pack (Window *, bool expand, ...);
+    Box::Pack (Layout *, bool expand, ...);
+    Box::Pack (Window *, Layout *, bool expand, ...);
+
+ The latter is due to ambiguity: just pass the same
+ pointer twice.
+ We probably want to only accept a generic Widget class,
+ and the user can just wrap their widget as in:
+    box->Pack (Widget (window), true);
+ We already do that internally.
+
+~~~~~~~~~~
+
+ldialog.hxx
+
+ Probably better to use this one as your top-level.
+
+ The default size will be one enough to show all its
+ children.
+
+ To overload the default size (ie. to use a bigger size),
+ lookup LDialog::SetDefaultSize().
+
+~~~~~~~~~~
+
+layout.hxx
+
+ Containers must implement this interface. A container
+ doesn't have to be a sub-class of Window: a pure
+ Layout sub-class works fine.
+
+ Non-container widgets may optionally implement this interface.
+
+ If the size of a widget may have changed (ie. the
+ label of the PushButton was changed, or a child
+ was added to a container), you should call
+ Layout::QueueResize().
+
+ This is a static method: no need to implement the Layout
+ class to take advantage of it.
+ The method will queue and defer geometry recalculations.
 
-> 1) that's still rather primitive and broken stuff. It needs
-> quite a few hours of productive time. I probably should
-> have just ported the toolkit; I have been pretty much
-> working on it from scratch.
-> 
-> 2) I initially went with Window::SetParent() calling a virtual
-> Window::ChildAdded() handler (and a ChildRemoved()) for
-> the containers benefit.
-> 
->   But now, you're supposed to call e.g. Box::PackChild(), and
-> that method is then responsible for calling Window::SetParent().
-> You must specify some dummy parent Window to your widget at
-> construction, which is wasteful, but there was a big problem with
-> the previous approach:
->   internal widgets: when you extend a widget, you probably
-> don't want to deal with those. For instance, TabControl does
-> a SetParent() every time the tab is changed, which creates
-> all kinds of havoc.
->   Also, you may not want a container to be associated with
-> a Window necessarily. But I am not sure how important that
-> is.
-> 
-> 3) I was now playing with the QueueResize() method and
-> LDialog (an extension of Dialog). I think we probably want
-> to have a couple of flags: needRecal and needAlloc, as
-> well as a cached requisition of type Size.
->   When you call QueueResize(), needRecalc is set to true.
-> LDialog, on timeout, does a breadth-first iteration through its
-> children to find which widgets/containers need their size to be
-> recalculated. Once it hits a needRecalc node, it checks the new
-> size against the cached valued: if they differ needAlloc is set to
-> true, and it now calculates the size of the parent recursively until
-> the extent of the damage is fully identified. All nodes that are
-> children of that top node must then be removed from the
-> iteration...
-> 
->   SizeRequest() (or GetPosSizePixel()) should return the previous
-> calculation if needRecalc is false...
-> 
->   The toolkit code also worked I guess: though it seems to be
-> pretty flickering ATM. But it does unnecessary size calculations,
-> and probably size allocations too (otherwise, it wouldn't flicker).
-> 
->   I will try to pin-down the algorithm later today, so that we have
-> finally a solid foundation for this thing.