[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}
7c913512	12
23324ae1 FM	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.
7c913512	17
23324ae1 FM	18	This class allows the programmer to decide the order of pages in the wizard
23324ae1 FM	19	dynamically (during run-time) and so provides maximal flexibility. Usually,
7c913512	20	however, the order of pages is known in advance in which case
23324ae1 FM	21	wxWizardPageSimple class is enough and it is simpler
23324ae1 FM	22	to use.
7c913512	23
23324ae1 FM	24	@library{wxadv}
23324ae1 FM	25	@category{miscwnd}
7c913512	26
23324ae1 FM	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
7c913512	39	@param parent
23324ae1 FM	40	The parent wizard
23324ae1 FM	41
7c913512	42	@param bitmap
23324ae1 FM	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
7c913512	50	page. By default, @c m_bitmap member variable which was set in the
23324ae1 FM	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}
7c913512	86
23324ae1 FM	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.
7c913512	90
23324ae1 FM	91	@library{wxadv}
23324ae1 FM	92	@category{events}
7c913512	93
23324ae1 FM	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}
7c913512 FM	127
7c913512 FM	128	wxWizardPageSimple is the simplest possible
23324ae1 FM	129	wxWizardPage implementation: it just returns the
23324ae1 FM	130	pointers given to its constructor from GetNext() and GetPrev() functions.
7c913512	131
23324ae1 FM	132	This makes it very easy to use the objects of this class in the wizards where
23324ae1 FM	133	the pages order is known statically - on the other hand, if this is not the
7c913512	134	case you must derive your own class from wxWizardPage
23324ae1	135	instead.
7c913512	136
23324ae1 FM	137	@library{wxadv}
23324ae1 FM	138	@category{miscwnd}
7c913512	139
23324ae1 FM	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
7c913512	148	SetPrev() or
23324ae1 FM	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}
7c913512	179
23324ae1 FM	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.
7c913512	184
23324ae1 FM	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.
7c913512	188
23324ae1 FM	189	To show a wizard dialog, you must first create an instance of the wxWizard class
23324ae1 FM	190	using either the non-default constructor or a default one followed by call to
7c913512	191	the
23324ae1 FM	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.
7c913512	196
23324ae1 FM	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.
7c913512	203
23324ae1 FM	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".
7c913512	210
23324ae1 FM	211	@library{wxadv}
23324ae1 FM	212	@category{cmndlg}
7c913512	213
23324ae1 FM	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
7c913512	225	Notice that unlike almost all other wxWidgets classes, there is no @e size
23324ae1	226	parameter in the wxWizard constructor because the wizard will have a predefined
7c913512	227	default size by default. If you want to change this, you should use the
23324ae1 FM	228	GetPageAreaSizer() function.
23324ae1 FM	229
7c913512	230	@param parent
23324ae1 FM	231	The parent window, may be @NULL.
23324ae1 FM	232
7c913512	233	@param id
23324ae1 FM	234	The id of the dialog, will usually be just -1.
23324ae1 FM	235
7c913512	236	@param title
23324ae1 FM	237	The title of the dialog.
23324ae1 FM	238
7c913512	239	@param bitmap
23324ae1 FM	240	The default bitmap used in the left side of the wizard. See
	241	also GetBitmap.
	242
7c913512	243	@param pos
23324ae1 FM	244	The position of the dialog, it will be centered on the screen
	245	by default.
	246
7c913512	247	@param style
23324ae1 FM	248	Window style is passed to wxDialog.
	249	*/
	250	wxWizard();
7c913512 FM	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);
23324ae1 FM	256	//@}
	257
	258	/**
	259	Creates the wizard dialog. Must be called if the default constructor had been
	260	used to create the object.
	261
7c913512	262	Notice that unlike almost all other wxWidgets classes, there is no @e size
23324ae1	263	parameter in the wxWizard constructor because the wizard will have a predefined
7c913512	264	default size by default. If you want to change this, you should use the
23324ae1 FM	265	GetPageAreaSizer() function.
23324ae1 FM	266
7c913512	267	@param parent
23324ae1 FM	268	The parent window, may be @NULL.
23324ae1 FM	269
7c913512	270	@param id
23324ae1 FM	271	The id of the dialog, will usually be just -1.
23324ae1 FM	272
7c913512	273	@param title
23324ae1 FM	274	The title of the dialog.
23324ae1 FM	275
7c913512	276	@param bitmap
23324ae1 FM	277	The default bitmap used in the left side of the wizard. See
	278	also GetBitmap.
	279
7c913512	280	@param pos
23324ae1 FM	281	The position of the dialog, it will be centered on the screen
	282	by default.
	283
7c913512	284	@param style
23324ae1 FM	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	/**
7c913512	332	Get the current page while the wizard is running. @NULL is returned if
23324ae1 FM	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
7c913512	354	by repeatedly applying
23324ae1 FM	355	wxWizardPage::GetNext to
23324ae1 FM	356	any page inserted into the sizer. Third,
7c913512	357	the minimal size specified using SetPageSize() and
23324ae1 FM	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
7c913512	387	class version implements this by calling
23324ae1 FM	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
7c913512	397	class version implements this by calling
23324ae1 FM	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
7c913512	407	successfully finished or @false if user cancelled it. The @e firstPage
23324ae1 FM	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
7c913512	505	the sizers (even though the wizard is not resizeable) and then use
23324ae1 FM	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	};