X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/f3289ffb1f7733a10f3e82a977678b5994acbc36..b19b28c8fca9815949753ed0c68097efe8943b18:/interface/wx/statbox.h

diff --git a/interface/wx/statbox.h b/interface/wx/statbox.h
index 250ba09fcc..d2845e4a87 100644
--- a/interface/wx/statbox.h
+++ b/interface/wx/statbox.h
@@ -12,18 +12,35 @@
     A static box is a rectangle drawn around other windows to denote
     a logical grouping of items.
 
-    Please note that a static box should @b not be used as the parent for the
-    controls it contains, instead they should be @b siblings of each other.
-    Although using a static box as a parent might work in some ports of wxWidgets,
-    it would result in a crash under, for example, wxGTK, and thus it's explicitely
-    disallowed (an assertion will fail if you try to add children to a wxStaticBox).
-
-    Also, please note that because of this, the order in which you create new
-    controls is important. Create your wxStaticBox control @b before any
-    siblings that are to appear inside the wxStaticBox in order to preserve the
-    correct Z-order of controls.
-    
-    You may want to use wxStaticBoxSizer instead of wxStaticBox to avoid this problem.
+    Note that while the previous versions required that windows appearing
+    inside a static box be created as its siblings (i.e. use the same parent as
+    the static box itself), since wxWidgets 2.9.1 it is also possible to create
+    them as children of wxStaticBox itself and you are actually encouraged to
+    do it like this if compatibility with the previous versions is not
+    important.
+
+    So the new recommended way to create static box is:
+    @code
+        void MyFrame::CreateControls()
+        {
+            wxPanel *panel = new wxPanel(this);
+            wxStaticBox *box = new wxStaticBox(panel, wxID_ANY, "StaticBox");
+
+            new wxStaticText(box, wxID_ANY "This window is a child of the staticbox");
+            ...
+        }
+    @endcode
+
+    While the compatible -- and now deprecated -- way is
+    @code
+            wxStaticBox *box = new wxStaticBox(panel, wxID_ANY, "StaticBox");
+
+            new wxStaticText(panel, wxID_ANY "This window is a child of the panel");
+            ...
+    @endcode
+
+    Also note that there is a specialized wxSizer class (wxStaticBoxSizer) which can
+    be used as an easier way to pack items into a static box.
 
     @library{wxcore}
     @category{ctrl}