Added project files for STC; fixed wxStringList memory leaks; small doc changes;

[wxWidgets.git] / docs / latex / wx / sizer.tex

diff --git a/docs/latex/wx/sizer.tex b/docs/latex/wx/sizer.tex
index eeb1bfd70c9ae8e425bcf49410a79ee0ed253cc3..f0dcb27bcb5a34f863cd5bca7bad2b9d90c84a3a 100644 (file)
--- a/docs/latex/wx/sizer.tex
+++ b/docs/latex/wx/sizer.tex
@@ -1,95 +1,196 @@
-%
-% automatically generated by HelpGen from
-% include\wx\sizer.h at 13/Aug/99 22:27:59
-%
-
-

 \section{\class{wxSizer}}\label{wxsizer}
 
 \section{\class{wxSizer}}\label{wxsizer}
 

-
-
-wxSizer
-
+wxSizer is the abstract base class used for laying out subwindows in a window. You
+cannot use wxSizer directly; instead, you'll have to use \helpref{wxBoxSizer}{wxboxsizer},
+\helpref{wxStaticBoxSizer}{wxstaticboxsizer} or \helpref{wxNotebookSizer}{wxnotebooksizer}.
+
+The layout algorithm used by sizers in wxWindows is closely related to layout
+in other GUI toolkits, such as Java's AWT, the GTK toolkit or the Qt toolkit. It is
+based upon the idea of the individual subwindows reporting their minimal required
+size and their ability to get stretched if the size of the parent window has changed.
+This will most often mean, that the programmer does not set the original size of
+a dialog in the beginning, rather the dialog will assigned a sizer and this sizer
+will be queried about the recommended size. The sizer in turn will query its
+children, which can be normal windows, empty space or other sizers, so that
+a hierarchy of sizers can be constructed. Note that wxSizer does not derive from wxWindow
+and thus do not interfere with tab ordering and requires very little resources compared
+to a real window on screen.
+
+What makes sizers so well fitted for use in wxWindows is the fact that every control
+reports its own minimal size and the algorithm can handle differences in font sizes
+or different window (dialog item) sizes on different platforms without problems. If e.g.
+the standard font as well as the overall design of Motif widgets requires more space than
+on Windows, the intial dialog size will automatically be bigger on Motif than on Windows.
+
+\pythonnote{If you wish to create a sizer class in wxPython you should
+derive the class from {\tt wxPySizer} in order to get Python-aware
+capabilities for the various virtual methods.}

 
 \wxheading{Derived from}
 
 \helpref{wxObject}{wxobject}
 
 
 \wxheading{Derived from}
 
 \helpref{wxObject}{wxobject}
 

-\wxheading{Data structures}
-

 \latexignore{\rtfignore{\wxheading{Members}}}
 
 \latexignore{\rtfignore{\wxheading{Members}}}
 

-

 \membersection{wxSizer::wxSizer}\label{wxsizerwxsizer}
 
 \func{}{wxSizer}{\void}
 
 \membersection{wxSizer::wxSizer}\label{wxsizerwxsizer}
 
 \func{}{wxSizer}{\void}
 

+The constructor. Note that wxSizer is an abstract base class and may not
+be instantiated.

 
 \membersection{wxSizer::\destruct{wxSizer}}\label{wxsizerdtor}
 
 \func{}{\destruct{wxSizer}}{\void}
 
 
 \membersection{wxSizer::\destruct{wxSizer}}\label{wxsizerdtor}
 
 \func{}{\destruct{wxSizer}}{\void}
 

+The destructor.

 
 \membersection{wxSizer::Add}\label{wxsizeradd}
 
 
 \membersection{wxSizer::Add}\label{wxsizeradd}
 

-\func{void}{Add}{\param{wxWindow* }{window}, \param{int }{option = 0}, \param{int }{flag = 0}, \param{int }{border = 0}}
+\func{void}{Add}{\param{wxWindow* }{window}, \param{int }{option = 0},\param{int }{flag = 0}, \param{int }{border = 0}, \param{wxObject* }{userData = NULL}}

 
 

+\func{void}{Add}{\param{wxSizer* }{sizer}, \param{int }{option = 0}, \param{int }{flag = 0}, \param{int }{border = 0}, \param{wxObject* }{userData = NULL}}

 
 

-\membersection{wxSizer::Add}\label{wxsizeradd}
+\func{void}{Add}{\param{int }{width}, \param{int }{height}, \param{int }{option = 0}, \param{int }{flag = 0}, \param{int }{border = 0}, \param{wxObject* }{userData = NULL}}

 
 

-\func{void}{Add}{\param{wxSizer* }{sizer}, \param{int }{option = 0}, \param{int }{flag = 0}, \param{int }{border = 0}}
+Adds the {\it window} to the sizer. As wxSizer itself is an abstract class, the parameters
+have no meaning in the wxSizer class itself, but as there currently is only one class
+deriving directly from wxSizer and this class does not override these methods, the meaning
+of the paramters is described here:

 
 

+\docparam{window}{The window to be added to the sizer. Its initial size (either set explicitly by the
+user or calculated internally when using wxDefaultSize) is interpreted as the minimal and in many
+cases also the initial size. This is particularly useful in connection with \helpref{SetSizeHint}{wxsizersetsizehints}.}

 
 

-\membersection{wxSizer::Add}\label{wxsizeradd}
+\docparam{sizer}{The (child-)sizer to be added to the sizer. This allows placing a child sizer in a
+sizer and thus to create hierarchies of sizers (typically a vertical box as the top sizer and several
+horizontal boxes on the level beneath).}
+
+\docparam{width and height}{The dimension of a spacer to be added to the sizer. Adding spacers to sizers
+gives more flexilibilty in the design of dialogs; imagine for example a horizontal box with two buttons at the
+bottom of a dialog: you might want to insert a space between the two buttons and make that space stretchable
+using the {\it option} flag and the result will be that the left button will be aligned with the left
+side of the dialog and the right button with the right side - the space in between will shrink and grow with
+the dialog.}
+
+\docparam{option}{Although the meaning of this parameter is undefined in wxSizer, it is used in wxBoxSizer
+to indicate if a child of a sizer can change its size in the main orientation of the wxBoxSizer - where
+0 stands for not changable and a value of more than zero in interpreted relative to the value of other
+children of the same wxBoxSizer. You might, e.g., have a horizontal wxBoxSizer with three children, two
+of which are supposed to change their size with the sizer, then the two stretchable windows would get a
+value of 1 each to make them grow and shrink equally with the sizer's horizontal dimension.}
+
+\docparam{flag}{This parameter can be used to set a number of flags which can be combined using
+the binary OR operator |. Two main behaviours are defined using these flags: One is the border
+around a window: the {\it border} parameter determines the border width whereas the flags given here
+determine where the border may be (wxTOP, wxBOTTOM, wxLEFT, wxRIGHT or wxALL). The other flags
+determine the child window's behaviour if the size of the sizer changes, but - in contrast to
+the {\it option} flag - not in the main orientation, but the respectively other orientation. So
+if you created a wxBoxSizer with the wxVERTICAL option, these flags will be relevant if the
+sizer changes its horizontal size. A child may get resized to completely fill out the new size (using
+either wxGROW or wxEXPAND), may get proportionally resized (wxSHAPED), may get centered (wxALIGN\_CENTER
+or wxALIGN\_CENTRE) or may get aligned to either side (wxALIGN\_LEFT and wxALIGN\_TOP are set to 0
+and thus represent the default, wxALIGN\_RIGHT and wxALIGN\_BOTTOM have their obvious meaning).
+With proportional resize, a child may also be centered in the main orientation using
+wxALIGN\_CENTER\_VERTICAL (same as wxALIGN\_CENTRE\_VERTICAL) and wxALIGN\_CENTER\_HORIZONTAL
+(same as wxALIGN\_CENTRE\_HORIZONTAL) flags.}

 
 

-\func{void}{Add}{\param{int }{width}, \param{int }{height}, \param{int }{option = 0}, \param{int }{flag = 0}, \param{int }{border = 0}}
+\docparam{border}{Determines the border width, if the {\it flag} parameter is set to any border.}

 
 

+\docparam{userData}{Allows an extra object to be attached to the sizer
+item, for use in derived classes when sizing information is more
+complex than what {\it option} and {\it flag} will allow for.}
+
+\membersection{wxSizer::Prepend}\label{wxsizerprepend}
+
+\func{void}{Prepend}{\param{wxWindow* }{window}, \param{int }{option = 0}, \param{int }{flag = 0}, \param{int }{border = 0}, \param{wxObject* }{userData = NULL}}
+
+\func{void}{Prepend}{\param{wxSizer* }{sizer}, \param{int }{option = 0}, \param{int }{flag = 0}, \param{int }{border = 0}, \param{wxObject* }{userData = NULL}}
+
+\func{void}{Prepend}{\param{int }{width}, \param{int }{height}, \param{int }{option = 0}, \param{int }{flag = 0}, \param{int }{border= 0}, \param{wxObject* }{userData = NULL}}
+
+Same as \helpref{wxSizer::Add}{wxsizeradd}, but prepends the items to the beginning of the
+list of items (windows, subsizers or spaces) owned by this sizer.
+
+\membersection{wxSizer::Remove}\label{wxsizerremove}
+
+\func{bool}{Remove}{\param{wxWindow* }{window}}
+
+\func{bool}{Remove}{\param{wxSizer* }{sizer}}
+
+\func{bool}{Remove}{\param{int }{nth}}
+
+Removes a child from the sizer. {\it window} is the window to be removed, {\it sizer} the
+equivalent sizer and {\it nth} is the position of the child in the sizer, typically 0 for
+the first item. This method does not cause any layout or resizing to take place and does
+not delete the window itself. Call \helpref{wxSizer::Layout}{wxsizerlayout} for updating
+the layout "on screen" after removing a child fom the sizer.
+
+Returns TRUE if the child item was found and removed, FALSE otherwise.

 
 \membersection{wxSizer::SetDimension}\label{wxsizersetdimension}
 
 \func{void}{SetDimension}{\param{int }{x}, \param{int }{y}, \param{int }{width}, \param{int }{height}}
 
 
 \membersection{wxSizer::SetDimension}\label{wxsizersetdimension}
 
 \func{void}{SetDimension}{\param{int }{x}, \param{int }{y}, \param{int }{width}, \param{int }{height}}
 

+Call this to force the sizer to take the given dimension and thus force the items owned
+by the sizer to resize themselves according to the rules defined by the paramater in the
+\helpref{wxSizer::Add}{wxsizeradd} and \helpref{wxSizer::Prepend}{wxsizerprepend} methods.

 
 \membersection{wxSizer::GetSize}\label{wxsizergetsize}
 
 \func{wxSize}{GetSize}{\void}
 
 
 \membersection{wxSizer::GetSize}\label{wxsizergetsize}
 
 \func{wxSize}{GetSize}{\void}
 

+Returns the current size of the sizer.

 
 \membersection{wxSizer::GetPosition}\label{wxsizergetposition}
 
 \func{wxPoint}{GetPosition}{\void}
 
 
 \membersection{wxSizer::GetPosition}\label{wxsizergetposition}
 
 \func{wxPoint}{GetPosition}{\void}
 

+Returns the current position of the sizer.

 
 \membersection{wxSizer::GetMinSize}\label{wxsizergetminsize}
 
 \func{wxSize}{GetMinSize}{\void}
 
 
 \membersection{wxSizer::GetMinSize}\label{wxsizergetminsize}
 
 \func{wxSize}{GetMinSize}{\void}
 

+Returns the minimal size of the sizer.

 
 \membersection{wxSizer::RecalcSizes}\label{wxsizerrecalcsizes}
 
 \func{void}{RecalcSizes}{\void}
 
 
 \membersection{wxSizer::RecalcSizes}\label{wxsizerrecalcsizes}
 
 \func{void}{RecalcSizes}{\void}
 

+This method is abstract and has to be overwritten by any derived class.
+Here, the sizer will do the actual calculation of its children's positions
+and sizes.

 
 \membersection{wxSizer::CalcMin}\label{wxsizercalcmin}
 
 \func{wxSize}{CalcMin}{\void}
 
 
 \membersection{wxSizer::CalcMin}\label{wxsizercalcmin}
 
 \func{wxSize}{CalcMin}{\void}
 

+This method is abstract and has to be overwritten by any derived class.
+Here, the sizer will do the actual calculation of its children minimal sizes.

 
 \membersection{wxSizer::Layout}\label{wxsizerlayout}
 
 \func{void}{Layout}{\void}
 
 
 \membersection{wxSizer::Layout}\label{wxsizerlayout}
 
 \func{void}{Layout}{\void}
 

+Call this to force laying out the children anew, e.g. after having added a child
+to or removed a child (window, other sizer or space) from the sizer while keeping
+the current dimension.

 
 \membersection{wxSizer::Fit}\label{wxsizerfit}
 
 \func{void}{Fit}{\param{wxWindow* }{window}}
 
 
 \membersection{wxSizer::Fit}\label{wxsizerfit}
 
 \func{void}{Fit}{\param{wxWindow* }{window}}
 

+Tell the sizer to resize the {\it window} to match the sizer's minimal size. This
+is commonly done in the constructor of the window itself, see sample in the description
+of \helpref{wxBoxSizer}{wxboxsizer}.

 
 \membersection{wxSizer::SetSizeHints}\label{wxsizersetsizehints}
 
 \func{void}{SetSizeHints}{\param{wxWindow* }{window}}
 
 
 \membersection{wxSizer::SetSizeHints}\label{wxsizersetsizehints}
 
 \func{void}{SetSizeHints}{\param{wxWindow* }{window}}
 

+Tell the sizer to set the minimal size of the {\it window} to match the sizer's minimal size.
+This is commonly done in the constructor of the window itself, see sample in the description
+of \helpref{wxBoxSizer}{wxboxsizer} if the window is resizable (as many dialogs under Unix and
+frames on probably all platforms).

 
 

-\membersection{wxSizer::GetMinWindowSize}\label{wxsizergetminwindowsize}
-
-\func{wxSize}{GetMinWindowSize}{\param{wxWindow* }{window}
\ No newline at end of file