Fix documentation of Fl_Tile (STR #3303).

Clarify that the resizable() box should be the first child to ensure
correct event delivery to children.



git-svn-id: file:///fltk/svn/fltk/branches/branch-1.3-porting@11727 ea41ed52-d2ee-0310-a9c1-e6b18d33e121

3 files changed, 23 insertions, 19 deletions

diff --git a/FL/Fl_Tile.H b/FL/Fl_Tile.H
index f794a9c62..c5a8e1703 100644
--- a/FL/Fl_Tile.H
+++ b/FL/Fl_Tile.H
@@ -3,7 +3,7 @@
 //
 // Tile header file for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2014 by Bill Spitzak and others.
+// Copyright 1998-2016 by Bill Spitzak and others.
 //
 // This library is free software. Distribution and use rights are outlined in
 // the file "COPYING" which should have been included with this file. If this
@@ -28,10 +28,10 @@
 
 class FL_EXPORT Fl_Tile : public Fl_Group {
 public:
-  int handle(int);
-  Fl_Tile(int X,int Y,int W,int H,const char*l=0);
-  void resize(int, int, int, int);
-  void position(int, int, int, int);
+  int handle(int event);
+  Fl_Tile(int X, int Y, int W, int H, const char *L=0);
+  void resize(int X, int Y, int W, int H);
+  void position(int oldx, int oldy, int newx, int newy);
 };
 
 #endif
diff --git a/src/Fl_Tile.cxx b/src/Fl_Tile.cxx
index be231fab0..1a533cabd 100644
--- a/src/Fl_Tile.cxx
+++ b/src/Fl_Tile.cxx
@@ -3,7 +3,7 @@
 //
 // Tile widget for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2014 by Bill Spitzak and others.
+// Copyright 1998-2016 by Bill Spitzak and others.
 //
 // This library is free software. Distribution and use rights are outlined in
 // the file "COPYING" which should have been included with this file. If this
@@ -58,8 +58,13 @@
   Fl_Tile widget is resized, the resizable() widget will keep its border
   distance to all borders the same (this is normal resize behavior), so
   that you can effectively set a border width that will never change.
+  To ensure correct event delivery to all child widgets the resizable()
+  widget must be the first child of the Fl_Tile widget group. Otherwise
+  some events (e.g. FL_MOVE and FL_ENTER) might be consumed by the resizable()
+  widget so that they are lost for widgets covered (overlapped) by the
+  resizable() widget.
 
-  <b>Note:</b>
+  \note
   You can still resize widgets \b inside the resizable() to zero width and/or
   height, i.e. box \b 2b above to zero width and box \b 3a to zero height.
 
@@ -69,10 +74,10 @@
   \code
     int dx = 20, dy = dx;
     Fl_Tile tile(50,50,300,300);
-    // ... create widgets inside tile (see test/tile.cxx) ...
-    // create resizable() box
+    // create resizable() box first
     Fl_Box r(tile.x()+dx,tile.y()+dy,tile.w()-2*dx,tile.h()-2*dy);
     tile.resizable(r);
+    // ... create widgets inside tile (see test/tile.cxx) ...
     tile.end();
   \endcode
 
@@ -289,8 +294,8 @@ int Fl_Tile::handle(int event) {
   \see class Fl_Group
 */
 
-Fl_Tile::Fl_Tile(int X,int Y,int W,int H,const char*l)
-: Fl_Group(X,Y,W,H,l)
+Fl_Tile::Fl_Tile(int X,int Y,int W,int H,const char*L)
+: Fl_Group(X,Y,W,H,L)
 {
 }
 
diff --git a/test/tile.cxx b/test/tile.cxx
index 614fd7c67..5bb8cf851 100644
--- a/test/tile.cxx
+++ b/test/tile.cxx
@@ -1,9 +1,9 @@
 //
 // "$Id$"
 //
-// Tile test program for the Fast Light Tool Kit (FLTK).
+// Fl_Tile test program for the Fast Light Tool Kit (FLTK).
 //
-// Copyright 1998-2014 by Bill Spitzak and others.
+// Copyright 1998-2016 by Bill Spitzak and others.
 //
 // This library is free software. Distribution and use rights are outlined in
 // the file "COPYING" which should have been included with this file.  If this
@@ -31,6 +31,11 @@ int main(int argc, char** argv) {
   int dx = 20, dy = dx; // border width of resizable() - see below
   Fl_Tile tile(0,0,300,300);
 
+  // create the symmetrical resize box with dx and dy pixels distance, resp.
+  // from the borders of the Fl_Tile widget before all other children
+  Fl_Box r(tile.x()+dx,tile.y()+dy,tile.w()-2*dx,tile.h()-2*dy);
+  tile.resizable(r);
+
   Fl_Box box0(0,0,150,150,"0");
   box0.box(FL_DOWN_BOX);
   box0.color(9);
@@ -75,12 +80,6 @@ int main(int argc, char** argv) {
   box3b.align(FL_ALIGN_CLIP);
   //tile3.end();
 
-  // create the symmetrical resize box with dx and dy pixels distance, resp.
-  // from the borders of the Fl_Tile widget
-  Fl_Box r(tile.x()+dx,tile.y()+dy,tile.w()-2*dx,tile.h()-2*dy);
-  tile.resizable(r);
-  // r.box(FL_BORDER_FRAME);
-
   tile.end();
   window.end();