docs/latex/wx/wizard.tex

   1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2 %% Name:        wizard.tex
   3 %% Purpose:     wxWizard class documentation
   4 %% Author:      Vadim Zeitlin
   5 %% Modified by:
   6 %% Created:     02.04.00
   7 %% RCS-ID:      $Id$
   8 %% Copyright:   (c) Vadim Zeitlin
   9 %% License:     wxWindows license
  10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  11
  12 \section{\class{wxWizard}}\label{wxwizard}
  13
  14 wxWizard is the central class for implementing `wizard-like' dialogs. These
  15 dialogs are mostly familiar to Windows users and are nothing else but a
  16 sequence of `pages' each of them displayed inside a dialog which has the
  17 buttons to pas to the next (and previous) pages.
  18
  19 The wizards are typically used to decompose a complex dialog into several
  20 simple steps and are mainly useful to the novice users, hence it is important
  21 to keep them as simple as possible.
  22
  23 To show a wizard dialog, you must first create an object of wxWizard class
  24 using \helpref{Create}{wxwizardcreate} function. Then you should add all pages
  25 you want the wizard to show and call \helpref{RunWizard}{wxwizardrunwizard}.
  26 Finally, don't forget to call {\tt wizard->Destroy()}.
  27
  28 \wxheading{Derived from}
  29
  30 \helpref{wxDialog}{wxdialog}\\
  31 \helpref{wxPanel}{wxpanel}\\
  32 \helpref{wxWindow}{wxwindow}\\
  33 \helpref{wxEvtHandler}{wxevthandler}\\
  34 \helpref{wxObject}{wxobject}
  35
  36 \wxheading{Include files}
  37
  38 <wx/wizard.h>
  39
  40 \wxheading{Event table macros}
  41
  42 To process input from a wizard dialog, use these event handler macros to
  43 direct input to member functions that take a
  44 \helpref{wxWizardEvent}{wxwizardevent} argument. For some events,
  45 \helpref{Veto()}{wxnotifyeventveto} can be called to prevent the event from
  46 happening.
  47
  48 \twocolwidtha{7cm}
  49 \begin{twocollist}\itemsep=2pt
  50 \twocolitem{{\bf EVT\_WIZARD\_PAGE\_CHANGED(id, func)}}{The page has been just
  51 changed (this event can not be vetoed).}
  52 \twocolitem{{\bf EVT\_WIZARD\_PAGE\_CHANGING(id, func)}}{The page is being
  53 changed (this event can be vetoed).}
  54 \twocolitem{{\bf EVT\_WIZARD\_CANCEL(id, func)}}{The user attempted to cancel
  55 the wizard (this event may also be vetoed).}
  56 \end{twocollist}%
  57
  58 \wxheading{See also}
  59
  60 \helpref{wxWizardEvent}{wxwizardevent}, \helpref{wxWizardPage}{wxwizardpage}, \helpref{wxWizard sample}{samplewizard}
  61
  62 \latexignore{\rtfignore{\wxheading{Members}}}
  63
  64 \membersection{wxWizard::Create}\label{wxwizardcreate}
  65
  66 \func{static wxWizard*}{Create}{\param{wxWindow* }{parent}, \param{int }{id = -1}, \param{const wxString\& }{title = wxEmptyString}, \param{const wxBitmap\& }{bitmap = wxNullBitmap}, \param{const wxPoint\& }{pos = wxDefaultPosition}}
  67
  68 Creates the wizard dialog. The returned pointer should not be deleted
  69 directly, you should rather call {\tt Destroy()} on it and wxWindows will
  70 delete it itself.
  71
  72 Notice that unlike almost all other wxWindows classes, there is no {\it size}
  73 parameter in wxWizard constructor because the wizard will have a predefined
  74 default size by default. If you want to change this, you should use the
  75 \helpref{SetPageSize}{wxwizardsetpagesize} function.
  76
  77 \wxheading{Parameters}
  78
  79 \docparam{parent}{The parent window, may be NULL.}
  80
  81 \docparam{id}{The id of the dialog, will usually be just $-1$.}
  82
  83 \docparam{title}{The title of the dialog.}
  84
  85 \docparam{bitmap}{The default bitmap used in the left side of the wizard. See
  86 also \helpref{GetBitmap}{wxwizardpagegetbitmap}.}
  87
  88 \docparam{pos}{The position of the dialog, it will be centered on the screen
  89 by default.}
  90
  91 \membersection{wxWizard::RunWizard}\label{wxwizardrunwizard}
  92
  93 \func{bool}{RunWizard}{\param{wxWizardPage* }{firstPage}}
  94
  95 Executes the wizard starting from the given page, returns {\tt TRUE} if it was
  96 successfully finished or {\tt FALSE} if user cancelled it. The {\it firstPage}
  97 can not be {\tt NULL}.
  98
  99 \membersection{wxWizard::GetCurrentPage}\label{wxwizardgetcurrentpage}
 100
 101 \constfunc{wxWizardPage*}{GetCurrentPage}{\void}
 102
 103 Get the current page while the wizard is running. {\tt NULL} is returned if
 104 \helpref{RunWizard()}{wxwizardrunwizard} is not being executed now.
 105
 106 \membersection{wxWizard::GetPageSize}\label{wxwizardgetpagesize}
 107
 108 \constfunc{wxSize}{GetPageSize}{\void}
 109
 110 Returns the size available for the pages.
 111
 112 \membersection{wxWizard::SetPageSize}\label{wxwizardsetpagesize}
 113
 114 \func{void}{SetPageSize}{\param{const wxSize\& }{sizePage}}
 115
 116 Sets the minimal size to be made available for the wizard pages. The wizard
 117 will take into account the size of the bitmap (if any) itself. Also, the
 118 wizard will never be smaller than the default size.
 119
 120 The recommended way to use this function is to layout all wizard pages using
 121 the sizers (even though the wizard is not resizeable) and then use
 122 \helpref{wxSizer::CalcMin}{wxsizercalcmin} in a loop to calculate the maximum
 123 of minimal sizes of the pages and pass it to SetPageSize().
 124