X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/8fe057828547c22ed7a55350bac2514a80ec4706..80d2803f703d1b238f42725504f08266ef02defe:/docs/latex/wx/boxsizer.tex?ds=sidebyside

diff --git a/docs/latex/wx/boxsizer.tex b/docs/latex/wx/boxsizer.tex
index c58931c47c..2db19fd414 100644
--- a/docs/latex/wx/boxsizer.tex
+++ b/docs/latex/wx/boxsizer.tex
@@ -1,43 +1,120 @@
-%
-% automatically generated by HelpGen from
-% include\wx\sizer.h at 13/Aug/99 22:27:59
-%
-
-
 \section{\class{wxBoxSizer}}\label{wxboxsizer}
 
-
-
-wxBoxSizer
-
-
-\wxheading{Derived from}
-
-\helpref{wxSizer}{wxsizer}
-
-\wxheading{Data structures}
-
+The basic idea behind a box sizer is that windows will most often be laid out in rather
+simple basic geomerty, typically in a row or a column or several hierachies of either.
+
+As an example, we will construct a dialog that will contain a text field at the top and
+two buttons at the bottom. This can be seen as a top-hierarchy column with the text at
+the top and buttons at the bottom and a low-hierchary row with an OK button to the left
+and a Cancel button to the right. In many cases (particulary dialogs under Unix and
+normal frames) the main window will be resizable by the user and this change of size
+will have to get propagated to its children. In our case, we want the text area to grow
+with the dialog, whereas the button shall have a fixed size. In addition, there will be
+a thin border around all controls to make the dialog look nice and - to make matter worse -
+the buttons shall be centred as the width of the dialog changes.
+
+It is the unique feature of a box sizer, that it can grow in both directions (height and
+width) but can distribute its growth in the main direction (horizontal for a row) {\it unevenly} 
+among its children. In our example case, the vertical sizer is supposed to propagate all its
+height changes to only the text area, not to the button area. This is determined by the {\it option} parameter
+when adding a window (or another sizer) to a sizer. It is interpreted
+as a weight factor, i.e. it can be zero, indicating that the window may not be resized
+at all, or above zero. If several windows have a value above zero, the value is interpreted
+relative to the sum of all weight factors of the sizer, so when adding two windows with
+a value of 1, they will both get resized equally much and each half as much as the sizer
+owning them. Then what do we do when a column sizer changes its width? This behaviour is
+controlled by {\it flags} (the second parameter of the Add() function): Zero or no flag
+indicates that the window will preserve it is original size, wxGROW flag (same as wxEXPAND)
+forces the window to grow with the sizer, and wxSHAPED flag tells the window to change it is
+size proportionally, preserving original aspect ratio.  When wxGROW flag is not used,
+the item can be aligned within available space.  wxALIGN\_LEFT, wxALIGN\_TOP, wxALIGN\_RIGHT,
+wxALIGN\_BOTTOM, wxALIGN\_CENTER\_HORIZONTAL and wxALIGN\_CENTER\_VERTICAL do what they say.
+wxALIGN\_CENTRE (same as wxALIGN\_CENTER) is defined as (wxALIGN\_CENTER\_HORIZONTAL |
+wxALIGN\_CENTER\_VERTICAL).  Default alignment is wxALIGN\_LEFT | wxALIGN\_TOP.
+
+As mentioned above, any window belonging to a sizer may have border, and it can be specified
+which of the four sides may have this border, using the wxTOP, wxLEFT, wxRIGHT and wxBOTTOM
+constants or wxALL for all directions (and you may also use wxNORTH, wxWEST etc instead). These
+flags can be used in combination with the alignment flags above as the second parameter of the
+Add() method using the binary or operator |. The sizer of the border also must be made known,
+and it is the third parameter in the Add() method. This means, that the entire behaviour of
+a sizer and its children can be controlled by the three parameters of the Add() method.
+
+\begin{verbatim}
+// we want to get a dialog that is stretchable because it
+// has a text ctrl at the top and two buttons at the bottom
+
+MyDialog::MyDialog(wxFrame *parent, wxWindowID id, const wxString &title ) :
+  wxDialog( parent, id, title, wxDefaultPosition, wxDefaultSize, wxDIALOG_STYLE | wxRESIZE_BORDER )
+{
+  wxBoxSizer *topsizer = new wxBoxSizer( wxVERTICAL );
+
+  // create text ctrl with minimal size 100x60
+  topsizer->Add(
+    new wxTextCtrl( this, -1, "My text.", wxDefaultPosition, wxSize(100,60), wxTE_MULTILINE),
+    1,            // make vertically stretchable
+    wxEXPAND |    // make horizontally stretchable
+    wxALL,        //   and make border all around
+    10 );         // set border width to 10
+
+
+  wxBoxSizer *button_sizer = new wxBoxSizer( wxHORIZONTAL );
+  button_sizer->Add(
+     new wxButton( this, wxID_OK, "OK" ),
+     0,           // make horizontally unstretchable
+     wxALL,       // make border all around (implicit top alignment)
+     10 );        // set border width to 10
+  button_sizer->Add(
+     new wxButton( this, wxID_CANCEL, "Cancel" ),
+     0,           // make horizontally unstretchable
+     wxALL,       // make border all around (implicit top alignment)
+     10 );        // set border width to 10
+
+  topsizer->Add(
+     button_sizer,
+     0,                // make vertically unstretchable
+     wxALIGN_CENTER ); // no border and centre horizontally
+
+  SetAutoLayout( TRUE );     // tell dialog to use sizer
+  SetSizer( topsizer );      // actually set the sizer
+
+  topsizer->Fit( this );            // set size to minimum size as calculated by the sizer
+  topsizer->SetSizeHints( this );   // set size hints to honour mininum size
 }
+\end{verbatim}
 
-\latexignore{\rtfignore{\wxheading{Members}}}
+\wxheading{Derived from}
 
+\helpref{wxSizer}{wxsizer}\\
+\helpref{wxObject}{wxobject}
 
 \membersection{wxBoxSizer::wxBoxSizer}\label{wxboxsizerwxboxsizer}
 
 \func{}{wxBoxSizer}{\param{int }{orient}}
 
+Constructor for a wxBoxSizer. {\it orient} may be either of wxVERTICAL
+or wxHORIZONTAL for creating either a column sizer or a row sizer.
 
 \membersection{wxBoxSizer::RecalcSizes}\label{wxboxsizerrecalcsizes}
 
 \func{void}{RecalcSizes}{\void}
 
+Implements the calculation of a box sizer's dimensions and then sets
+the size of its its children (calling \helpref{wxWindow::SetSize}{wxwindowsetsize} 
+if the child is a window). It is used internally only and must not be called
+by the user. Documented for information.
 
 \membersection{wxBoxSizer::CalcMin}\label{wxboxsizercalcmin}
 
 \func{wxSize}{CalcMin}{\void}
 
+Implements the calculation of a box sizer's minimal. It is used internally
+only and must not be called by the user. Documented for information.
 
 \membersection{wxBoxSizer::GetOrientation}\label{wxboxsizergetorientation}
 
 \func{int}{GetOrientation}{\void}
 
+Returns the orientation of the box sizer, either wxVERTICAL
+or wxHORIZONTAL.
+
