From 7a3a8c18922d035370653bf6269af40002a3c08b Mon Sep 17 00:00:00 2001
From: Matthias Melcher <fltk@matthiasm.com>
Date: Thu, 27 Dec 2007 11:02:27 +0000
Subject: STR 1815: Added begin() and end() information to the Basics chapter.
 Hope you'll like it

git-svn-id: file:///fltk/svn/fltk/branches/branch-1.1@6007 ea41ed52-d2ee-0310-a9c1-e6b18d33e121
---
 documentation/basics.html | 23 +++++++++++++++++++++--
 1 file changed, 21 insertions(+), 2 deletions(-)

(limited to 'documentation/basics.html')

diff --git a/documentation/basics.html b/documentation/basics.html
index 522e7d845..efb8d6926 100644
--- a/documentation/basics.html
+++ b/documentation/basics.html
@@ -45,7 +45,8 @@ window. All following widgets will automatically be children of this window.</P>
 Fl_Window *window = new <A href="Fl_Window.html#Fl_Window">Fl_Window</A>(300,180);
 </PRE></UL>
 
-<P>Then we create a box with the &quot;Hello, World!&quot; string in it.</P>
+<P>Then we create a box with the &quot;Hello, World!&quot; string in it. FLTK automatically adds
+the new box to <tt>window</tt>, the current grouping widget.</P>
 
 <UL><PRE>
 Fl_Box *box = new <A href="Fl_Box.html#Fl_Box">Fl_Box</A>(20,40,260,100,&quot;Hello, World!&quot;);
@@ -60,7 +61,7 @@ box-&gt;<A href=Fl_Widget.html#Fl_Widget.labelfont>labelfont</A>(FL_BOLD+FL_ITAL
 box-&gt;<A href=Fl_Widget.html#Fl_Widget.labeltype>labeltype</A>(FL_SHADOW_LABEL);
 </PRE></UL>
 
-<P>We tell FLTK that we will not add any more widgets to the window.</P>
+<P>We tell FLTK that we will not add any more widgets to <tt>window</tt>.</P>
 
 <UL><PRE>
 window-&gt;<A href=Fl_Group.html#Fl_Group.end>end</A>();
@@ -105,6 +106,24 @@ defaults to <tt>NULL</tt>. The label string must be in static
 storage such as a string constant because FLTK does not make a
 copy of it - it just uses the pointer.</P>
 
+<H3>Creating Widget hierarchies</H3>
+
+<P>Widgets are commonly ordered into functional groups, which 
+in turn may be grouped again, creating a hierarchy of widgets. 
+FLTK makes it easy to fill groups by automatically adding all widgets 
+that are created between a <tt>myGroup-&gt;begin()</tt> and 
+<tt>myGroup-&gt;end()</tt>. In this example, <tt>myGroup</tt>  
+would be the <i>current</i> group.</P>
+
+<P>Newly created groups and their derived widgets implicitly call
+<tt>begin()</tt> in the constructor, effectively adding all 
+subsequently created widgets to itself until <tt>end()</tt> 
+is called.</P>
+
+<P>Setting the current group to <tt>NULL</tt> will stop automatic
+hierarchies. New widgets can now be added manually using 
+<tt>Fl_Group::add(...)</tt> and <tt>Fl_Group::insert(...)</tt>.</P>
+
 <H3>Get/Set Methods</H3>
 
 <P><tt>box-&gt;box(FL_UP_BOX)</tt> sets the type of box the
-- 
cgit v1.2.3