Add wxSizerFlags docs to wxSizer, wxSizerItem and wxSizer overview.

Mention that wxSizerFlags is PRELIMINARY.


git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@30613 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

docs/latex/wx/sizer.tex

@@ -62,8 +62,12 @@ The destructor.
 
 \membersection{wxSizer::Add}\label{wxsizeradd}
 
+\func{wxSizerItem*}{Add}{\param{wxWindow* }{window}, \param{const wxSizerFlags\& }{flags}}
+
 \func{wxSizerItem*}{Add}{\param{wxWindow* }{window}, \param{int }{proportion = 0},\param{int }{flag = 0}, \param{int }{border = 0}, \param{wxObject* }{userData = NULL}}
 
+\func{wxSizerItem*}{Add}{\param{wxSizer* }{sizer}, \param{const wxSizerFlags\& }{flags}}
+
 \func{wxSizerItem*}{Add}{\param{wxSizer* }{sizer}, \param{int }{proportion = 0}, \param{int }{flag = 0}, \param{int }{border = 0}, \param{wxObject* }{userData = NULL}}
 
 \func{wxSizerItem*}{Add}{\param{int }{width}, \param{int }{height}, \param{int }{proportion = 0}, \param{int }{flag = 0}, \param{int }{border = 0}, \param{wxObject* }{userData = NULL}}
@@ -142,6 +146,8 @@ the sizer, adjusted for the border if any.}
 item, for use in derived classes when sizing information is more
 complex than the {\it proportion} and {\it flag} will allow for.}
 
+\docparam{flags}{A \helpref{wxSizerFlags}{wxsizerflags} object that 
+enables you to specify most of the above parameters more conveniently.}
 
 \membersection{wxSizer::AddSpacer}\label{wxsizeraddspacer}
 
@@ -254,8 +260,12 @@ size of all the children and their borders or the minimal size set by
 
 \membersection{wxSizer::Insert}\label{wxsizerinsert}
 
+\func{wxSizerItem*}{Insert}{\param{size\_t }{index}, \param{wxWindow* }{window}, \param{const wxSizerFlags\& }{flags}}
+
 \func{wxSizerItem*}{Insert}{\param{size\_t }{index}, \param{wxWindow* }{window}, \param{int }{proportion = 0},\param{int }{flag = 0}, \param{int }{border = 0}, \param{wxObject* }{userData = NULL}}
 
+\func{wxSizerItem*}{Insert}{\param{size\_t }{index}, \param{wxSizer* }{sizer}, \param{const wxSizerFlags\& }{flags}}
+
 \func{wxSizerItem*}{Insert}{\param{size\_t }{index}, \param{wxSizer* }{sizer}, \param{int }{proportion = 0}, \param{int }{flag = 0}, \param{int }{border = 0}, \param{wxObject* }{userData = NULL}}
 
 \func{wxSizerItem*}{Insert}{\param{size\_t }{index}, \param{int }{width}, \param{int }{height}, \param{int }{proportion = 0}, \param{int }{flag = 0}, \param{int }{border = 0}, \param{wxObject* }{userData = NULL}}
@@ -294,8 +304,12 @@ the current dimension.
 
 \membersection{wxSizer::Prepend}\label{wxsizerprepend}
 
+\func{wxSizerItem*}{Prepend}{\param{wxWindow* }{window}, \param{const wxSizerFlags\& }{flags}}
+
 \func{wxSizerItem*}{Prepend}{\param{wxWindow* }{window}, \param{int }{proportion = 0}, \param{int }{flag = 0}, \param{int }{border = 0}, \param{wxObject* }{userData = NULL}}
 
+\func{wxSizerItem*}{Prepend}{\param{wxSizer* }{sizer}, \param{const wxSizerFlags\& }{flags}}
+
 \func{wxSizerItem*}{Prepend}{\param{wxSizer* }{sizer}, \param{int }{proportion = 0}, \param{int }{flag = 0}, \param{int }{border = 0}, \param{wxObject* }{userData = NULL}}
 
 \func{wxSizerItem*}{Prepend}{\param{int }{width}, \param{int }{height}, \param{int }{proportion = 0}, \param{int }{flag = 0}, \param{int }{border= 0}, \param{wxObject* }{userData = NULL}}
@@ -430,6 +444,8 @@ are the only two sizer classes that can size rows/columns independently.
 
 \section{\class{wxSizerFlags}}\label{wxsizerflags}
 
+PRELIMINARY.
+
 Normally, when you add something to a sizer via \helpref{wxSizer::Add}{wxsizeradd}, you have to specify a lot of flags and parameters.  This can be unwieldy.
 
 This is where wxSizerFlags comes in.  Instead of a bunch of flags and other stuff, you can use wxSizerFlags, which is a convenient class for doing so.

docs/latex/wx/sizeritem.tex

@@ -26,11 +26,15 @@ wxSizerItem, but derived sizer classes will.
 Construct a sizer item for tracking a spacer.
 
 
+\func{}{wxSizerItem}{\param{wxWindow* }{window}, \param{const wxSizerFlags\& }{flags}}
+
 \func{}{wxSizerItem}{\param{wxWindow* }{window}, \param{int }{proportion}, \param{int }{flag}, \param{int }{border}, \param{wxObject* }{userData}}
 
 Construct a sizer item for tracking a window.
 
 
+\func{}{wxSizerItem}{\param{wxSizer* }{window}, \param{const wxSizerFlags\& }{flags}}
+
 \func{}{wxSizerItem}{\param{wxSizer* }{sizer}, \param{int }{proportion}, \param{int }{flag}, \param{int }{border}, \param{wxObject* }{userData}}
 
 Construct a sizer item for tracking a subsizer.

docs/latex/wx/tsizer.tex

@@ -265,6 +265,50 @@ MyDialog::MyDialog(wxFrame *parent, wxWindowID id, const wxString &title )
 }
 \end{verbatim}
 
+Note that the new way of specifying flags to wxSizer is via \helpref{wxSizerFlags}{wxsizerflags}.  This class greatly eases the burden of passing flags to a wxSizer.
+
+Here's how you'd do the previous example with wxSizerFlags:
+
+\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,
+                   wxDEFAULT_DIALOG_STYLE | wxRESIZE_BORDER)
+{
+  wxBoxSizer *topsizer = new wxBoxSizer( wxVERTICAL );
+
+  // create text ctrl with minimal size 100x60 that is horizontally and 
+  // vertically stretchable with a border width of 10
+  topsizer->Add(
+    new wxTextCtrl( this, -1, "My text.", wxDefaultPosition, wxSize(100,60), wxTE_MULTILINE),
+    wxSizerFlags(1).Align().Expand().Border(wxALL, 10));
+
+  wxBoxSizer *button_sizer = new wxBoxSizer( wxHORIZONTAL );
+
+  //create two buttons that are horizontally unstretchable, 
+  // with an all-around border with a width of 10 and implicit top alignment
+  button_sizer->Add(
+     new wxButton( this, wxID_OK, "OK" ),
+     wxSizerFlags(0).Align().Border(wxALL, 10));       
+
+  button_sizer->Add(
+     new wxButton( this, wxID_CANCEL, "Cancel" ),
+     wxSizerFlags(0).Align().Border(wxALL, 10));    
+
+  //create a sizer with no border and centered horizontally
+  topsizer->Add(
+     button_sizer,
+     wxSizerFlags(0).Center() ); 
+
+  SetSizer( topsizer );      // use the sizer for layout
+
+  topsizer->SetSizeHints( this );   // set size hints to honour minimum size
+}
+\end{verbatim}
+
+
 \subsection{Programming with wxGridSizer}\label{gridsizerprogramming}
 
 \helpref{wxGridSizer}{wxgridsizer} is a sizer which lays out its children in a two-dimensional