[wxWidgets.git] / interface / wizard.h

/////////////////////////////////////////////////////////////////////////////
// Name:        wizard.h
// Purpose:     documentation for wxWizardPage class
// Author:      wxWidgets team
// RCS-ID:      $Id$
// Licence:     wxWindows license
/////////////////////////////////////////////////////////////////////////////

/**
    @class wxWizardPage
    @wxheader{wizard.h}
    
    wxWizardPage is one of the screens in wxWizard: it must
    know what are the following and preceding pages (which may be @NULL for the
    first/last page). Except for this extra knowledge, wxWizardPage is just a
    panel, so the controls may be placed directly on it in the usual way.
    
    This class allows the programmer to decide the order of pages in the wizard
    dynamically (during run-time) and so provides maximal flexibility. Usually,
    however, the order of pages is known in advance in which case 
    wxWizardPageSimple class is enough and it is simpler
    to use.
    
    @library{wxadv}
    @category{miscwnd}
    
    @seealso
    wxWizard, @ref overview_samplewizard "wxWizard sample"
*/
class wxWizardPage : public wxPanel
{
public:
    /**
        Constructor accepts an optional bitmap which will be used for this page
        instead of the default one for this wizard (note that all bitmaps used should
        be of the same size). Notice that no other parameters are needed because the
        wizard will resize and reposition the page anyhow.
        
        @param parent 
        The parent wizard
        
        @param bitmap 
        The page-specific bitmap if different from the global one
    */
    wxWizardPage(wxWizard* parent,
                 const wxBitmap& bitmap = wxNullBitmap);

    /**
        This method is called by wxWizard to get the bitmap to display alongside the
        page. By default, @c m_bitmap member variable which was set in the 
        @ref wxwizardpage() constructor.
        
        If the bitmap was not explicitly set (i.e. if @c wxNullBitmap is returned),
        the default bitmap for the wizard should be used.
        
        The only cases when you would want to override this function is if the page
        bitmap depends dynamically on the user choices, i.e. almost never.
    */
    wxBitmap GetBitmap();

    /**
        Get the page which should be shown when the user chooses the @c "Next"
        button: if @NULL is returned, this button will be disabled. The last
        page of the wizard will usually return @NULL from here, but the others
        will not.
        
        @sa GetPrev()
    */
    wxWizardPage* GetNext();

    /**
        Get the page which should be shown when the user chooses the @c "Back"
        button: if @NULL is returned, this button will be disabled. The first
        page of the wizard will usually return @NULL from here, but the others
        will not.
        
        @sa GetNext()
    */
    wxWizardPage* GetPrev();
};


/**
    @class wxWizardEvent
    @wxheader{wizard.h}
    
    wxWizardEvent class represents an event generated by the
    wizard: this event is first sent to the page itself and,
    if not processed there, goes up the window hierarchy as usual.
    
    @library{wxadv}
    @category{events}
    
    @seealso
    wxWizard, @ref overview_samplewizard "wxWizard sample"
*/
class wxWizardEvent : public wxNotifyEvent
{
public:
    /**
        Constructor. It is not normally used by the user code as the objects of this
        type are constructed by wxWizard.
    */
    wxWizardEvent(wxEventType type = wxEVT_@NULL, int id = -1,
                  bool direction = @true);

    /**
        Return the direction in which the page is changing: for @c
        EVT_WIZARD_PAGE_CHANGING, return @true if we're going forward or
        @false otherwise and for @c EVT_WIZARD_PAGE_CHANGED return @true if
        we came from the previous page and @false if we returned from the next
        one.
    */
    bool GetDirection();

    /**
        Returns the wxWizardPage which was active when this
        event was generated.
    */
    wxWizardPage* GetPage();
};


/**
    @class wxWizardPageSimple
    @wxheader{wizard.h}
    
    wxWizardPageSimple is the simplest possible 
    wxWizardPage implementation: it just returns the
    pointers given to its constructor from GetNext() and GetPrev() functions.
    
    This makes it very easy to use the objects of this class in the wizards where
    the pages order is known statically - on the other hand, if this is not the
    case you must derive your own class from wxWizardPage 
    instead.
    
    @library{wxadv}
    @category{miscwnd}
    
    @seealso
    wxWizard, @ref overview_samplewizard "wxWizard sample"
*/
class wxWizardPageSimple : public wxWizardPage
{
public:
    /**
        Constructor takes the previous and next pages. They may be modified later by
        SetPrev() or 
        SetNext().
    */
    wxWizardPageSimple(wxWizard* parent = @NULL,
                       wxWizardPage* prev = @NULL,
                       wxWizardPage* next = @NULL,
                       const wxBitmap& bitmap = wxNullBitmap);

    /**
        A convenience function to make the pages follow each other.
        
        Example:
    */
    static void Chain(wxWizardPageSimple* first,
                      wxWizardPageSimple* second);

    /**
        Sets the next page.
    */
    void SetNext(wxWizardPage* next);

    /**
        Sets the previous page.
    */
    void SetPrev(wxWizardPage* prev);
};


/**
    @class wxWizard
    @wxheader{wizard.h}
    
    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 
    wxWizard::Create function. Then you should add all pages you
    want the wizard to show and call wxWizard::RunWizard.
    Finally, don't forget to call @c wizard-Destroy(), otherwise your application
    will hang on exit due to an undestroyed window.
    
    You can supply a bitmap to display on the left of the wizard, either for all
    pages
    or for individual pages. If you need to have the bitmap resize to the height of
    the wizard,
    call wxWizard::SetBitmapPlacement and if necessary,
    wxWizard::SetBitmapBackgroundColour and wxWizard::SetMinimumBitmapWidth.
    
    To make wizard pages scroll when the display is too small to fit the whole
    dialog, you can switch
    layout adaptation on globally with wxDialog::EnableLayoutAdaptation or
    per dialog with wxDialog::SetLayoutAdaptationMode. For more
    about layout adaptation, see @ref overview_autoscrollingdialogs "Automatic
    scrolling dialogs".
    
    @library{wxadv}
    @category{cmndlg}
    
    @seealso
    wxWizardEvent, wxWizardPage, @ref overview_samplewizard "wxWizard sample"
*/
class wxWizard : public wxDialog
{
public:
    //@{
    /**
        Constructor which really creates the wizard -- if you use this constructor, you
        shouldn't call Create().
        
        Notice that unlike almost all other wxWidgets classes, there is no @e 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 
        GetPageAreaSizer() function.
        
        @param parent 
        The parent window, may be @NULL.
        
        @param id 
        The id of the dialog, will usually be just -1.
        
        @param title 
        The title of the dialog.
        
        @param bitmap 
        The default bitmap used in the left side of the wizard. See
        also GetBitmap.
        
        @param pos 
        The position of the dialog, it will be centered on the screen
        by default.
        
        @param style 
        Window style is passed to wxDialog.
    */
    wxWizard();
        wxWizard(wxWindow* parent, int id = -1,
                 const wxString& title = wxEmptyString,
                 const wxBitmap& bitmap = wxNullBitmap,
                 const wxPoint& pos = wxDefaultPosition,
                 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 @e 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 
        GetPageAreaSizer() function.
        
        @param parent 
        The parent window, may be @NULL.
        
        @param id 
        The id of the dialog, will usually be just -1.
        
        @param title 
        The title of the dialog.
        
        @param bitmap 
        The default bitmap used in the left side of the wizard. See
        also GetBitmap.
        
        @param pos 
        The position of the dialog, it will be centered on the screen
        by default.
        
        @param style 
        Window style is passed to wxDialog.
    */
    bool Create(wxWindow* parent, int id = -1,
                const wxString& title = wxEmptyString,
                const wxBitmap& bitmap = wxNullBitmap,
                const wxPoint& pos = wxDefaultPosition,
                long style = wxDEFAULT_DIALOG_STYLE);

    /**
        This method is obsolete, use
        GetPageAreaSizer() instead.
        
        Sets the page size to be big enough for all the pages accessible via the
        given @e 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 @e Fit separately for the others.
    */
    void FitToPage(const wxWizardPage* firstPage);

    /**
        Returns the bitmap used for the wizard.
    */
    const wxBitmap GetBitmap();

    /**
        Returns the colour that should be used to fill the area not taken up by the
        wizard or page bitmap,
        if a non-zero bitmap placement flag has been set.
        
        See also SetBitmapPlacement().
    */
    const wxColour GetBitmapBackgroundColour();

    /**
        Returns the flags indicating how the wizard or page bitmap should be expanded
        and positioned to fit the
        page height. By default, placement is 0 (no expansion is done).
        
        See also SetBitmapPlacement() for the possible values.
    */
    int GetBitmapPlacement();

    /**
        Get the current page while the wizard is running. @NULL is returned if 
        RunWizard() is not being executed now.
    */
    wxWizardPage* GetCurrentPage();

    /**
        Returns the minimum width for the bitmap that will be constructed to contain
        the actual wizard or page bitmap
        if a non-zero bitmap placement flag has been set.
        
        See also SetBitmapPlacement().
    */
    int GetMinimumBitmapWidth();

    /**
        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 
        wxWizardPage::GetNext to
        any page inserted into the sizer. Third,
        the minimal size specified using SetPageSize() and 
        FitToPage(). 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 wxSizer::SetMinSize to enlarge it
        beyond the minimal size. If @c 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 wxSizer::SetMinSize.
        
        Adding pages to the page area sizer affects the default border width around page
        area that can be altered with SetBorder().
    */
    virtual wxSizer* GetPageAreaSizer();

    /**
        Returns the size available for the pages.
    */
    wxSize GetPageSize();

    /**
        Return @true if this page is not the last one in the wizard. The base
        class version implements this by calling 
        @ref wxWizardPage::getnext page-GetNext but this could be undesirable if,
        for example, the pages are created on demand only.
        
        @sa HasPrevPage()
    */
    virtual bool HasNextPage(wxWizardPage * page);

    /**
        Returns @true if this page is not the last one in the wizard. The base
        class version implements this by calling 
        @ref wxWizardPage::getprev page-GetPrev but this could be undesirable if,
        for example, the pages are created on demand only.
        
        @sa HasNextPage()
    */
    virtual bool HasPrevPage(wxWizardPage * page);

    /**
        Executes the wizard starting from the given page, returning @true if it was
        successfully finished or @false if user cancelled it. The @e firstPage 
        can not be @NULL.
    */
    bool RunWizard(wxWizardPage* firstPage);

    /**
        Sets the bitmap used for the wizard.
    */
    void SetBitmap(const wxBitmap& bitmap);

    /**
        Sets the colour that should be used to fill the area not taken up by the wizard
        or page bitmap,
        if a non-zero bitmap placement flag has been set.
        
        See also SetBitmapPlacement().
    */
    void SetBitmapBackgroundColour(const wxColour& colour);

    /**
        Sets the flags indicating how the wizard or page bitmap should be expanded and
        positioned to fit the
        page height. By default, placement is 0 (no expansion is done). @e placement is
        a bitlist with the
        following possible values:
        
        @b wxWIZARD_VALIGN_TOP
        
        
        Aligns the bitmap at the top.
        
        @b wxWIZARD_VALIGN_CENTRE
        
        
        Centres the bitmap vertically.
        
        @b wxWIZARD_VALIGN_BOTTOM
        
        
        Aligns the bitmap at the bottom.
        
        @b wxWIZARD_HALIGN_LEFT
        
        
        Left-aligns the bitmap.
        
        @b wxWIZARD_HALIGN_CENTRE
        
        
        Centres the bitmap horizontally.
        
        @b wxWIZARD_HALIGN_RIGHT
        
        
        Right-aligns the bitmap.
        
        @b wxWIZARD_TILE
        
        
        See also SetMinimumBitmapWidth().
    */
    void SetBitmapPlacement(int placement);

    /**
        Sets width of border around page area. Default is zero. For backward
        compatibility, if there are no pages in
        GetPageAreaSizer(), 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.
    */
    void SetBorder(int border);

    /**
        Sets the minimum width for the bitmap that will be constructed to contain the
        actual wizard or page bitmap
        if a non-zero bitmap placement flag has been set. If this is not set when using
        bitmap placement, the initial
        layout may be incorrect.
        
        See also SetBitmapPlacement().
    */
    void SetMinimumBitmapWidth(int width);

    /**
        This method is obsolete, use
        GetPageAreaSizer() 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 
        wxSizer::CalcMin in a loop to calculate the maximum
        of minimal sizes of the pages and pass it to SetPageSize().
    */
    void SetPageSize(const wxSize& sizePage);
};
Commit	Line	Data
23324ae1 FM	1	/////////////////////////////////////////////////////////////////////////////
	2	// Name: wizard.h
	3	// Purpose: documentation for wxWizardPage class
	4	// Author: wxWidgets team
	5	// RCS-ID: $Id$
	6	// Licence: wxWindows license
	7	/////////////////////////////////////////////////////////////////////////////
	8
	9	/**
	10	@class wxWizardPage
	11	@wxheader{wizard.h}
	12
	13	wxWizardPage is one of the screens in wxWizard: it must
	14	know what are the following and preceding pages (which may be @NULL for the
	15	first/last page). Except for this extra knowledge, wxWizardPage is just a
	16	panel, so the controls may be placed directly on it in the usual way.
	17
	18	This class allows the programmer to decide the order of pages in the wizard
	19	dynamically (during run-time) and so provides maximal flexibility. Usually,
	20	however, the order of pages is known in advance in which case
	21	wxWizardPageSimple class is enough and it is simpler
	22	to use.
	23
	24	@library{wxadv}
	25	@category{miscwnd}
	26
	27	@seealso
	28	wxWizard, @ref overview_samplewizard "wxWizard sample"
	29	*/
	30	class wxWizardPage : public wxPanel
	31	{
	32	public:
	33	/**
	34	Constructor accepts an optional bitmap which will be used for this page
	35	instead of the default one for this wizard (note that all bitmaps used should
	36	be of the same size). Notice that no other parameters are needed because the
	37	wizard will resize and reposition the page anyhow.
	38
	39	@param parent
	40	The parent wizard
	41
	42	@param bitmap
	43	The page-specific bitmap if different from the global one
	44	*/
	45	wxWizardPage(wxWizard* parent,
	46	const wxBitmap& bitmap = wxNullBitmap);
	47
	48	/**
	49	This method is called by wxWizard to get the bitmap to display alongside the
	50	page. By default, @c m_bitmap member variable which was set in the
	51	@ref wxwizardpage() constructor.
	52
	53	If the bitmap was not explicitly set (i.e. if @c wxNullBitmap is returned),
	54	the default bitmap for the wizard should be used.
	55
	56	The only cases when you would want to override this function is if the page
	57	bitmap depends dynamically on the user choices, i.e. almost never.
	58	*/
	59	wxBitmap GetBitmap();
	60
	61	/**
	62	Get the page which should be shown when the user chooses the @c "Next"
	63	button: if @NULL is returned, this button will be disabled. The last
	64	page of the wizard will usually return @NULL from here, but the others
65	will not.
66
67	@sa GetPrev()
68	*/
69	wxWizardPage* GetNext();
70
71	/**
72	Get the page which should be shown when the user chooses the @c "Back"
73	button: if @NULL is returned, this button will be disabled. The first
74	page of the wizard will usually return @NULL from here, but the others
75	will not.
76
77	@sa GetNext()
78	*/
79	wxWizardPage* GetPrev();
80	};
81
82
83	/**
84	@class wxWizardEvent
85	@wxheader{wizard.h}
86
87	wxWizardEvent class represents an event generated by the
88	wizard: this event is first sent to the page itself and,
89	if not processed there, goes up the window hierarchy as usual.
90
91	@library{wxadv}
92	@category{events}
93
94	@seealso
95	wxWizard, @ref overview_samplewizard "wxWizard sample"
96	*/
97	class wxWizardEvent : public wxNotifyEvent
98	{
99	public:
100	/**
101	Constructor. It is not normally used by the user code as the objects of this
102	type are constructed by wxWizard.
103	*/
104	wxWizardEvent(wxEventType type = wxEVT_@NULL, int id = -1,
105	bool direction = @true);
106
107	/**
108	Return the direction in which the page is changing: for @c
109	EVT_WIZARD_PAGE_CHANGING, return @true if we're going forward or
110	@false otherwise and for @c EVT_WIZARD_PAGE_CHANGED return @true if
111	we came from the previous page and @false if we returned from the next
112	one.
113	*/
114	bool GetDirection();
115
116	/**
117	Returns the wxWizardPage which was active when this
118	event was generated.
119	*/
120	wxWizardPage* GetPage();
121	};
122
123
124	/**
125	@class wxWizardPageSimple
126	@wxheader{wizard.h}
127
128	wxWizardPageSimple is the simplest possible
129	wxWizardPage implementation: it just returns the
130	pointers given to its constructor from GetNext() and GetPrev() functions.
131
132	This makes it very easy to use the objects of this class in the wizards where
133	the pages order is known statically - on the other hand, if this is not the
134	case you must derive your own class from wxWizardPage
135	instead.
136
137	@library{wxadv}
138	@category{miscwnd}
139
140	@seealso
141	wxWizard, @ref overview_samplewizard "wxWizard sample"
142	*/
143	class wxWizardPageSimple : public wxWizardPage
144	{
145	public:
146	/**
147	Constructor takes the previous and next pages. They may be modified later by
148	SetPrev() or
149	SetNext().
150	*/
151	wxWizardPageSimple(wxWizard* parent = @NULL,
152	wxWizardPage* prev = @NULL,
153	wxWizardPage* next = @NULL,
154	const wxBitmap& bitmap = wxNullBitmap);
155
156	/**
157	A convenience function to make the pages follow each other.
158
159	Example:
160	*/
161	static void Chain(wxWizardPageSimple* first,
162	wxWizardPageSimple* second);
163
164	/**
165	Sets the next page.
166	*/
167	void SetNext(wxWizardPage* next);
168
169	/**
170	Sets the previous page.
171	*/
172	void SetPrev(wxWizardPage* prev);
173	};
174
175
176	/**
177	@class wxWizard
178	@wxheader{wizard.h}
179
180	wxWizard is the central class for implementing 'wizard-like' dialogs. These
181	dialogs are mostly familiar to Windows users and are nothing other than a
182	sequence of 'pages', each displayed inside a dialog which has the
183	buttons to navigate to the next (and previous) pages.
184
185	The wizards are typically used to decompose a complex dialog into several
186	simple steps and are mainly useful to the novice users, hence it is important
187	to keep them as simple as possible.
188
189	To show a wizard dialog, you must first create an instance of the wxWizard class
190	using either the non-default constructor or a default one followed by call to
191	the
192	wxWizard::Create function. Then you should add all pages you
193	want the wizard to show and call wxWizard::RunWizard.
194	Finally, don't forget to call @c wizard-Destroy(), otherwise your application
195	will hang on exit due to an undestroyed window.
196
197	You can supply a bitmap to display on the left of the wizard, either for all
198	pages
199	or for individual pages. If you need to have the bitmap resize to the height of
200	the wizard,
201	call wxWizard::SetBitmapPlacement and if necessary,
202	wxWizard::SetBitmapBackgroundColour and wxWizard::SetMinimumBitmapWidth.
203
204	To make wizard pages scroll when the display is too small to fit the whole
205	dialog, you can switch
206	layout adaptation on globally with wxDialog::EnableLayoutAdaptation or
207	per dialog with wxDialog::SetLayoutAdaptationMode. For more
208	about layout adaptation, see @ref overview_autoscrollingdialogs "Automatic
209	scrolling dialogs".
210
211	@library{wxadv}
212	@category{cmndlg}
213
214	@seealso
215	wxWizardEvent, wxWizardPage, @ref overview_samplewizard "wxWizard sample"
216	*/
217	class wxWizard : public wxDialog
218	{
219	public:
220	//@{
221	/**
222	Constructor which really creates the wizard -- if you use this constructor, you
223	shouldn't call Create().
224
225	Notice that unlike almost all other wxWidgets classes, there is no @e size
226	parameter in the wxWizard constructor because the wizard will have a predefined
227	default size by default. If you want to change this, you should use the
228	GetPageAreaSizer() function.
229
230	@param parent
231	The parent window, may be @NULL.
232
233	@param id
234	The id of the dialog, will usually be just -1.
235
236	@param title
237	The title of the dialog.
238
239	@param bitmap
240	The default bitmap used in the left side of the wizard. See
241	also GetBitmap.
242
243	@param pos
244	The position of the dialog, it will be centered on the screen
245	by default.
246
247	@param style
248	Window style is passed to wxDialog.
249	*/
250	wxWizard();
251	wxWizard(wxWindow* parent, int id = -1,
252	const wxString& title = wxEmptyString,
253	const wxBitmap& bitmap = wxNullBitmap,
254	const wxPoint& pos = wxDefaultPosition,
255	long style = wxDEFAULT_DIALOG_STYLE);
256	//@}
257
258	/**
259	Creates the wizard dialog. Must be called if the default constructor had been
260	used to create the object.
261
262	Notice that unlike almost all other wxWidgets classes, there is no @e size
263	parameter in the wxWizard constructor because the wizard will have a predefined
264	default size by default. If you want to change this, you should use the
265	GetPageAreaSizer() function.
266
267	@param parent
268	The parent window, may be @NULL.
269
270	@param id
271	The id of the dialog, will usually be just -1.
272
273	@param title
274	The title of the dialog.
275
276	@param bitmap
277	The default bitmap used in the left side of the wizard. See
278	also GetBitmap.
279
280	@param pos
281	The position of the dialog, it will be centered on the screen
282	by default.
283
284	@param style
285	Window style is passed to wxDialog.
286	*/
287	bool Create(wxWindow* parent, int id = -1,
288	const wxString& title = wxEmptyString,
289	const wxBitmap& bitmap = wxNullBitmap,
290	const wxPoint& pos = wxDefaultPosition,
291	long style = wxDEFAULT_DIALOG_STYLE);
292
293	/**
294	This method is obsolete, use
295	GetPageAreaSizer() instead.
296
297	Sets the page size to be big enough for all the pages accessible via the
298	given @e firstPage, i.e. this page, its next page and so on.
299
300	This method may be called more than once and it will only change the page size
301	if the size required by the new page is bigger than the previously set one.
302	This is useful if the decision about which pages to show is taken during
303	run-time, as in this case, the wizard won't be able to get to all pages starting
304	from a single one and you should call @e Fit separately for the others.
305	*/
306	void FitToPage(const wxWizardPage* firstPage);
307
308	/**
309	Returns the bitmap used for the wizard.
310	*/
311	const wxBitmap GetBitmap();
312
313	/**
314	Returns the colour that should be used to fill the area not taken up by the
315	wizard or page bitmap,
316	if a non-zero bitmap placement flag has been set.
317
318	See also SetBitmapPlacement().
319	*/
320	const wxColour GetBitmapBackgroundColour();
321
322	/**
323	Returns the flags indicating how the wizard or page bitmap should be expanded
324	and positioned to fit the
325	page height. By default, placement is 0 (no expansion is done).
326
327	See also SetBitmapPlacement() for the possible values.
328	*/
329	int GetBitmapPlacement();
330
331	/**
332	Get the current page while the wizard is running. @NULL is returned if
333	RunWizard() is not being executed now.
334	*/
335	wxWizardPage* GetCurrentPage();
336
337	/**
338	Returns the minimum width for the bitmap that will be constructed to contain
339	the actual wizard or page bitmap
340	if a non-zero bitmap placement flag has been set.
341
342	See also SetBitmapPlacement().
343	*/
344	int GetMinimumBitmapWidth();
345
346	/**
347	Returns pointer to page area sizer. The wizard is laid out using sizers and
348	the page area sizer is the place-holder for the pages. All pages are resized
349	before
350	being shown to match the wizard page area.
351
352	Page area sizer has a minimal size that is the maximum of several values. First,
353	all pages (or other objects) added to the sizer. Second, all pages reachable
354	by repeatedly applying
355	wxWizardPage::GetNext to
356	any page inserted into the sizer. Third,
357	the minimal size specified using SetPageSize() and
358	FitToPage(). Fourth, the total wizard height may
359	be increased to accommodate the bitmap height. Fifth and finally, wizards are
360	never smaller than some built-in minimal size to avoid wizards that are too
361	small.
362
363	The caller can use wxSizer::SetMinSize to enlarge it
364	beyond the minimal size. If @c wxRESIZE_BORDER was passed to constructor, user
365	can resize wizard and consequently the page area (but not make it smaller than
366	the
367	minimal size).
368
369	It is recommended to add the first page to the page area sizer. For simple
370	wizards,
371	this will enlarge the wizard to fit the biggest page. For non-linear wizards,
372	the first page of every separate chain should be added. Caller-specified size
373	can be accomplished using wxSizer::SetMinSize.
374
375	Adding pages to the page area sizer affects the default border width around page
376	area that can be altered with SetBorder().
377	*/
378	virtual wxSizer* GetPageAreaSizer();
379
380	/**
381	Returns the size available for the pages.
382	*/
383	wxSize GetPageSize();
384
385	/**
386	Return @true if this page is not the last one in the wizard. The base
387	class version implements this by calling
388	@ref wxWizardPage::getnext page-GetNext but this could be undesirable if,
389	for example, the pages are created on demand only.
390
391	@sa HasPrevPage()
392	*/
393	virtual bool HasNextPage(wxWizardPage * page);
394
395	/**
396	Returns @true if this page is not the last one in the wizard. The base
397	class version implements this by calling
398	@ref wxWizardPage::getprev page-GetPrev but this could be undesirable if,
399	for example, the pages are created on demand only.
400
401	@sa HasNextPage()
402	*/
403	virtual bool HasPrevPage(wxWizardPage * page);
404
405	/**
406	Executes the wizard starting from the given page, returning @true if it was
407	successfully finished or @false if user cancelled it. The @e firstPage
408	can not be @NULL.
409	*/
410	bool RunWizard(wxWizardPage* firstPage);
411
412	/**
413	Sets the bitmap used for the wizard.
414	*/
415	void SetBitmap(const wxBitmap& bitmap);
416
417	/**
418	Sets the colour that should be used to fill the area not taken up by the wizard
419	or page bitmap,
420	if a non-zero bitmap placement flag has been set.
421
422	See also SetBitmapPlacement().
423	*/
424	void SetBitmapBackgroundColour(const wxColour& colour);
425
426	/**
427	Sets the flags indicating how the wizard or page bitmap should be expanded and
428	positioned to fit the
429	page height. By default, placement is 0 (no expansion is done). @e placement is
430	a bitlist with the
431	following possible values:
432
433	@b wxWIZARD_VALIGN_TOP
434
435
436	Aligns the bitmap at the top.
437
438	@b wxWIZARD_VALIGN_CENTRE
439
440
441	Centres the bitmap vertically.
442
443	@b wxWIZARD_VALIGN_BOTTOM
444
445
446	Aligns the bitmap at the bottom.
447
448	@b wxWIZARD_HALIGN_LEFT
449
450
451	Left-aligns the bitmap.
452
453	@b wxWIZARD_HALIGN_CENTRE
454
455
456	Centres the bitmap horizontally.
457
458	@b wxWIZARD_HALIGN_RIGHT
459
460
461	Right-aligns the bitmap.
462
463	@b wxWIZARD_TILE
464
465
466
467	See also SetMinimumBitmapWidth().
468	*/
469	void SetBitmapPlacement(int placement);
470
471	/**
472	Sets width of border around page area. Default is zero. For backward
473	compatibility, if there are no pages in
474	GetPageAreaSizer(), the default is 5 pixels.
475
476	If there is a five point border around all controls in a page and the border
477	around
478	page area is left as zero, a five point white space along all dialog borders
479	will be added to the control border in order to space page controls ten points
480	from the dialog
481	border and non-page controls.
482	*/
483	void SetBorder(int border);
484
485	/**
486	Sets the minimum width for the bitmap that will be constructed to contain the
487	actual wizard or page bitmap
488	if a non-zero bitmap placement flag has been set. If this is not set when using
489	bitmap placement, the initial
490	layout may be incorrect.
491
492	See also SetBitmapPlacement().
493	*/
494	void SetMinimumBitmapWidth(int width);
495
496	/**
497	This method is obsolete, use
498	GetPageAreaSizer() instead.
499
500	Sets the minimal size to be made available for the wizard pages. The wizard
501	will take into account the size of the bitmap (if any) itself. Also, the
502	wizard will never be smaller than the default size.
503
504	The recommended way to use this function is to lay out all wizard pages using
505	the sizers (even though the wizard is not resizeable) and then use
506	wxSizer::CalcMin in a loop to calculate the maximum
507	of minimal sizes of the pages and pass it to SetPageSize().
508	*/
509	void SetPageSize(const wxSize& sizePage);
510	};