8795498cd9
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@32309 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
275 lines
11 KiB
TeX
275 lines
11 KiB
TeX
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%% Name: wizard.tex
|
|
%% Purpose: wxWizard class documentation
|
|
%% Author: Vadim Zeitlin
|
|
%% Modified by: Robert Vazan (sizers)
|
|
%% Created: 02.04.00
|
|
%% RCS-ID: $Id$
|
|
%% Copyright: (c) Vadim Zeitlin
|
|
%% License: wxWindows license
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
|
|
\section{\class{wxWizard}}\label{wxwizard}
|
|
|
|
wxWizard is the central class for implementing `wizard-like' dialogs. These
|
|
dialogs are mostly familiar to Windows users and are nothing other than a
|
|
sequence of `pages', each displayed inside a dialog which has the
|
|
buttons to navigate to the next (and previous) pages.
|
|
|
|
The wizards are typically used to decompose a complex dialog into several
|
|
simple steps and are mainly useful to the novice users, hence it is important
|
|
to keep them as simple as possible.
|
|
|
|
To show a wizard dialog, you must first create an instance of the wxWizard class
|
|
using either the non-default constructor or a default one followed by call to the
|
|
\helpref{Create}{wxwizardcreate} function. Then you should add all pages you
|
|
want the wizard to show and call \helpref{RunWizard}{wxwizardrunwizard}.
|
|
Finally, don't forget to call {\tt wizard->Destroy()}.
|
|
|
|
\wxheading{Derived from}
|
|
|
|
\helpref{wxDialog}{wxdialog}\\
|
|
\helpref{wxPanel}{wxpanel}\\
|
|
\helpref{wxWindow}{wxwindow}\\
|
|
\helpref{wxEvtHandler}{wxevthandler}\\
|
|
\helpref{wxObject}{wxobject}
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/wizard.h>
|
|
|
|
\wxheading{Event table macros}
|
|
|
|
To process input from a wizard dialog, use these event handler macros to
|
|
direct input to member functions that take a
|
|
\helpref{wxWizardEvent}{wxwizardevent} argument. For some events,
|
|
\helpref{Veto()}{wxnotifyeventveto} can be called to prevent the event from
|
|
happening.
|
|
|
|
\twocolwidtha{7cm}
|
|
\begin{twocollist}\itemsep=2pt
|
|
\twocolitem{{\bf EVT\_WIZARD\_PAGE\_CHANGED(id, func)}}{The page has just been
|
|
changed (this event cannot be vetoed).}
|
|
\twocolitem{{\bf EVT\_WIZARD\_PAGE\_CHANGING(id, func)}}{The page is being
|
|
changed (this event can be vetoed).}
|
|
\twocolitem{{\bf EVT\_WIZARD\_CANCEL(id, func)}}{The user attempted to cancel
|
|
the wizard (this event may also be vetoed).}
|
|
\twocolitem{{\bf EVT\_WIZARD\_HELP(id, func)}}{The wizard help button was pressed.}
|
|
\twocolitem{{\bf EVT\_WIZARD\_FINISHED(id, func)}}{The wizard finished button was pressed.}
|
|
\end{twocollist}
|
|
|
|
\wxheading{Extended styles}
|
|
|
|
Use the \helpref{wxWindow::SetExtraStyle}{wxwindowsetextrastyle} function to set the following
|
|
style. You will need to use two-step construction (use the default constructor, call {\bf SetExtraStyle}, then call {\bf Create}).
|
|
|
|
\twocolwidtha{5cm}%
|
|
\begin{twocollist}\itemsep=0pt
|
|
\twocolitem{\windowstyle{wxWIZARD\_EX\_HELPBUTTON}}{Shows a Help button using wxID\_HELP.}
|
|
\end{twocollist}
|
|
|
|
See also \helpref{wxDialog}{wxdialog} for other extended styles.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxWizardEvent}{wxwizardevent}, \helpref{wxWizardPage}{wxwizardpage}, \helpref{wxWizard sample}{samplewizard}
|
|
|
|
\latexignore{\rtfignore{\wxheading{Members}}}
|
|
|
|
\membersection{wxWizard::wxWizard}\label{wxwizardctor}
|
|
|
|
\func{}{wxWizard}{\void}
|
|
|
|
Default constructor. Use this if you wish to derive from wxWizard and then call
|
|
\helpref{Create}{wxwizardcreate}, for example if you wish to set an extra style
|
|
with \helpref{wxWindow::SetExtraStyle}{wxwindowsetextrastyle} between the two
|
|
calls.
|
|
|
|
\func{}{wxWizard}{\param{wxWindow* }{parent}, \param{int }{id = -1}, \param{const wxString\& }{title = wxEmptyString}, \param{const wxBitmap\& }{bitmap = wxNullBitmap}, \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{long }{style = wxDEFAULT\_DIALOG\_STYLE}}
|
|
|
|
Constructor which really creates the wizard -- if you use this constructor, you
|
|
shouldn't call \helpref{Create}{wxwizardcreate}.
|
|
|
|
Notice that unlike almost all other wxWidgets classes, there is no {\it size}
|
|
parameter in the wxWizard constructor because the wizard will have a predefined
|
|
default size by default. If you want to change this, you should use the
|
|
\helpref{GetPageAreaSizer}{wxwizardgetpageareasizer} function.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{parent}{The parent window, may be NULL.}
|
|
|
|
\docparam{id}{The id of the dialog, will usually be just $-1$.}
|
|
|
|
\docparam{title}{The title of the dialog.}
|
|
|
|
\docparam{bitmap}{The default bitmap used in the left side of the wizard. See
|
|
also \helpref{GetBitmap}{wxwizardpagegetbitmap}.}
|
|
|
|
\docparam{pos}{The position of the dialog, it will be centered on the screen
|
|
by default.}
|
|
|
|
\docparam{style}{Window style is passed to wxDialog.}
|
|
|
|
|
|
\membersection{wxWizard::Create}\label{wxwizardcreate}
|
|
|
|
\func{bool}{Create}{\param{wxWindow* }{parent}, \param{int }{id = -1}, \param{const wxString\& }{title = wxEmptyString}, \param{const wxBitmap\& }{bitmap = wxNullBitmap}, \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{long }{style = wxDEFAULT\_DIALOG\_STYLE}}
|
|
|
|
Creates the wizard dialog. Must be called if the default constructor had been
|
|
used to create the object.
|
|
|
|
Notice that unlike almost all other wxWidgets classes, there is no {\it size}
|
|
parameter in the wxWizard constructor because the wizard will have a predefined
|
|
default size by default. If you want to change this, you should use the
|
|
\helpref{GetPageAreaSizer}{wxwizardgetpageareasizer} function.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{parent}{The parent window, may be NULL.}
|
|
|
|
\docparam{id}{The id of the dialog, will usually be just $-1$.}
|
|
|
|
\docparam{title}{The title of the dialog.}
|
|
|
|
\docparam{bitmap}{The default bitmap used in the left side of the wizard. See
|
|
also \helpref{GetBitmap}{wxwizardpagegetbitmap}.}
|
|
|
|
\docparam{pos}{The position of the dialog, it will be centered on the screen
|
|
by default.}
|
|
|
|
\docparam{style}{Window style is passed to wxDialog.}
|
|
|
|
|
|
\membersection{wxWizard::FitToPage}\label{wxwizardfittopage}
|
|
|
|
\func{void}{FitToPage}{\param{const wxWizardPage* }{firstPage}}
|
|
|
|
This method is obsolete, use
|
|
\helpref{GetPageAreaSizer}{wxwizardgetpageareasizer} instead.
|
|
|
|
Sets the page size to be big enough for all the pages accessible via the
|
|
given {\it firstPage}, i.e. this page, its next page and so on.
|
|
|
|
This method may be called more than once and it will only change the page size
|
|
if the size required by the new page is bigger than the previously set one.
|
|
This is useful if the decision about which pages to show is taken during
|
|
run-time, as in this case, the wizard won't be able to get to all pages starting
|
|
from a single one and you should call {\it Fit} separately for the others.
|
|
|
|
|
|
\membersection{wxWizard::GetCurrentPage}\label{wxwizardgetcurrentpage}
|
|
|
|
\constfunc{wxWizardPage*}{GetCurrentPage}{\void}
|
|
|
|
Get the current page while the wizard is running. {\tt NULL} is returned if
|
|
\helpref{RunWizard()}{wxwizardrunwizard} is not being executed now.
|
|
|
|
|
|
\membersection{wxWizard::GetPageAreaSizer}\label{wxwizardgetpageareasizer}
|
|
|
|
\constfunc{virtual wxSizer*}{GetPageAreaSizer}{\void}
|
|
|
|
Returns pointer to page area sizer. The wizard is laid out using sizers and
|
|
the page area sizer is the place-holder for the pages. All pages are resized before
|
|
being shown to match the wizard page area.
|
|
|
|
Page area sizer has a minimal size that is the maximum of several values. First,
|
|
all pages (or other objects) added to the sizer. Second, all pages reachable
|
|
by repeatedly applying
|
|
\helpref{wxWizardPage::GetNext}{wxwizardpagegetnext} to
|
|
any page inserted into the sizer. Third,
|
|
the minimal size specified using \helpref{SetPageSize}{wxwizardsetpagesize} and
|
|
\helpref{FitToPage}{wxwizardfittopage}. Fourth, the total wizard height may
|
|
be increased to accommodate the bitmap height. Fifth and finally, wizards are
|
|
never smaller than some built-in minimal size to avoid wizards that are too small.
|
|
|
|
The caller can use \helpref{wxSizer::SetMinSize}{wxsizersetminsize} to enlarge it
|
|
beyond the minimal size. If {\tt wxRESIZE\_BORDER} was passed to constructor, user
|
|
can resize wizard and consequently the page area (but not make it smaller than the
|
|
minimal size).
|
|
|
|
It is recommended to add the first page to the page area sizer. For simple wizards,
|
|
this will enlarge the wizard to fit the biggest page. For non-linear wizards,
|
|
the first page of every separate chain should be added. Caller-specified size
|
|
can be accomplished using \helpref{wxSizer::SetMinSize}{wxsizersetminsize}.
|
|
|
|
Adding pages to the page area sizer affects the default border width around page
|
|
area that can be altered with \helpref{SetBorder}{wxwizardsetborder}.
|
|
|
|
|
|
\membersection{wxWizard::GetPageSize}\label{wxwizardgetpagesize}
|
|
|
|
\constfunc{wxSize}{GetPageSize}{\void}
|
|
|
|
Returns the size available for the pages.
|
|
|
|
|
|
\membersection{wxWizard::HasNextPage}\label{wxwizardhasnextpage}
|
|
|
|
\func{virtual bool}{HasNextPage}{\param{wxWizardPage *}{page}}
|
|
|
|
Return {\tt true} if this page is not the last one in the wizard. The base
|
|
class version implements this by calling
|
|
\helpref{page->GetNext}{wxwizardpagegetnext} but this could be undesirable if,
|
|
for example, the pages are created on demand only.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{HasPrevPage}{wxwizardhasprevpage}
|
|
|
|
|
|
\membersection{wxWizard::HasPrevPage}\label{wxwizardhasprevpage}
|
|
|
|
\func{virtual bool}{HasPrevPage}{\param{wxWizardPage *}{page}}
|
|
|
|
Returns {\tt true} if this page is not the last one in the wizard. The base
|
|
class version implements this by calling
|
|
\helpref{page->GetPrev}{wxwizardpagegetprev} but this could be undesirable if,
|
|
for example, the pages are created on demand only.
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{HasNextPage}{wxwizardhasnextpage}
|
|
|
|
|
|
\membersection{wxWizard::RunWizard}\label{wxwizardrunwizard}
|
|
|
|
\func{bool}{RunWizard}{\param{wxWizardPage* }{firstPage}}
|
|
|
|
Executes the wizard starting from the given page, returning {\tt true} if it was
|
|
successfully finished or {\tt false} if user cancelled it. The {\it firstPage}
|
|
can not be {\tt NULL}.
|
|
|
|
|
|
\membersection{wxWizard::SetPageSize}\label{wxwizardsetpagesize}
|
|
|
|
\func{void}{SetPageSize}{\param{const wxSize\& }{sizePage}}
|
|
|
|
This method is obsolete, use
|
|
\helpref{GetPageAreaSizer}{wxwizardgetpageareasizer} instead.
|
|
|
|
Sets the minimal size to be made available for the wizard pages. The wizard
|
|
will take into account the size of the bitmap (if any) itself. Also, the
|
|
wizard will never be smaller than the default size.
|
|
|
|
The recommended way to use this function is to lay out all wizard pages using
|
|
the sizers (even though the wizard is not resizeable) and then use
|
|
\helpref{wxSizer::CalcMin}{wxsizercalcmin} in a loop to calculate the maximum
|
|
of minimal sizes of the pages and pass it to SetPageSize().
|
|
|
|
|
|
\membersection{wxWizard::SetBorder}\label{wxwizardsetborder}
|
|
|
|
\func{void}{SetBorder}{\param{int }{border}}
|
|
|
|
Sets width of border around page area. Default is zero. For backward
|
|
compatibility, if there are no pages in
|
|
\helpref{GetPageAreaSizer}{wxwizardgetpageareasizer}, the default is $5$ pixels.
|
|
|
|
If there is a five point border around all controls in a page and the border around
|
|
page area is left as zero, a five point white space along all dialog borders
|
|
will be added to the control border in order to space page controls ten points from the dialog
|
|
border and non-page controls.
|
|
|