X-Git-Url: http://git.tdb.fi/?a=blobdiff_plain;f=source%2Flayout.h;h=379b468bf3f46efe30b37de4165081f8731e8d83;hb=2b70e8801c43875ed3f4135bdd0141265cff0312;hp=540c5ee4d90bacfe9b233e824ad181b81a21aeeb;hpb=01eaaef90f4c56cd4669d2f621e3061a938753eb;p=libs%2Fgltk.git

diff --git a/source/layout.h b/source/layout.h
index 540c5ee..379b468 100644
--- a/source/layout.h
+++ b/source/layout.h
@@ -12,6 +12,42 @@ namespace GLtk {
 class Container;
 class Widget;
 
+/**
+Positions Widgets inside a Container.
+
+A layout operates on constraints, which are used to form a linear program that
+is then solved to obtain positions and dimensions that fulfill the constraints.
+There are three kinds of constraints available: ordering, alignment and
+dimension matching.
+
+Ordering constraints specify that the widgets should be placed next to other
+along X or Y axis.  These operate on one axis at a time, so a widget could be
+"right of" another even if they are separated by hundreds of pixels vertically.
+The widgets will be separated by a spacing value, which is settable on a per-
+layout basis.
+
+Alignment constraints make the corresponding edges of two widgets be on the
+same line.  These are incompatible with ordering constraints, so only one or
+the other should be used between any pair of widgets for the same axis.
+
+Dimension matching constraints force the two widgets to have the same dimension
+along the relevant axis.
+
+In addition to constraints, there are some other properties that can be set on
+widgets to determine how they are laid out.  Gravity affects which edge of the
+container the widget should be placed at.  This is a relatively weak hint and
+will be overridden by many other things.  Margins can also be specified to
+prevent widgets from getting too close to the container's edges.
+
+Usually widgets are made as small as their content allows.  Setting the expand
+flag for a widget causes it to use as much space as possible.  If multiple co-
+dependent widgets have the expand flag set, the results are currently
+undefined.
+
+Since specifiyng constraints manually can be quite tedious, there are some
+derived Layout classes that implement common positioning patterns.  See
+MixedRows and Grid.
+*/
 class Layout
 {
 private: