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: [PATCH] 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
---
 CHANGES                   |  2 +-
 documentation/basics.html | 23 +++++++++++++++++++++--
 2 files changed, 22 insertions(+), 3 deletions(-)

diff --git a/CHANGES b/CHANGES
index f63162e37..2a949d80f 100644
--- a/CHANGES
+++ b/CHANGES
@@ -4,7 +4,7 @@ CHANGES IN FLTK 1.1.8
 	  STR #1457, STR #1458, STR #1460, STR #1481, STR #1578,
 	  STR #1639, STR #1645, STR #1644, STR #1792, STR #1793,
 	  STR #1742, STR #1777, STR #1794, STR #1827, STR #1843,
-	  STR #1796)
+	  STR #1796, STR #1815)
 	- Fixed 16 bit PNM image support (STR #1847)
 	- Fixed exposure event on zero size windows (STR #1824)
 	- Fixed overlay offset for OS X Quartz (STR #1729)
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