| 1 | /////////////////////////////////////////////////////////////////////////////// |
| 2 | // Name: wizard.h |
| 3 | // Purpose: wxWizard class: a GUI control presenting the user with a |
| 4 | // sequence of dialogs which allows to simply perform some task |
| 5 | // Author: Vadim Zeitlin (partly based on work by Ron Kuris and Kevin B. |
| 6 | // Smith) |
| 7 | // Modified by: Robert Cavanaugh |
| 8 | // Added capability to use .WXR resource files in Wizard pages |
| 9 | // Added wxWIZARD_HELP event |
| 10 | // Created: 15.08.99 |
| 11 | // RCS-ID: $Id$ |
| 12 | // Copyright: (c) 1999 Vadim Zeitlin <zeitlin@dptmaths.ens-cachan.fr> |
| 13 | // Licence: wxWindows license |
| 14 | /////////////////////////////////////////////////////////////////////////////// |
| 15 | |
| 16 | #ifndef _WX_WIZARD_H_ |
| 17 | #define _WX_WIZARD_H_ |
| 18 | |
| 19 | #if wxUSE_WIZARDDLG |
| 20 | |
| 21 | // ---------------------------------------------------------------------------- |
| 22 | // headers and other simple declarations |
| 23 | // ---------------------------------------------------------------------------- |
| 24 | |
| 25 | #ifndef WX_PRECOMP |
| 26 | #include "wx/dialog.h" // the base class |
| 27 | #include "wx/panel.h" // ditto |
| 28 | |
| 29 | #include "wx/event.h" // wxEVT_XXX constants |
| 30 | #endif // WX_PRECOMP |
| 31 | |
| 32 | // Extended style to specify a help button |
| 33 | #define wxWIZARD_EX_HELPBUTTON 0x00000010 |
| 34 | |
| 35 | // forward declarations |
| 36 | class WXDLLEXPORT wxWizard; |
| 37 | |
| 38 | // ---------------------------------------------------------------------------- |
| 39 | // wxWizardPage is one of the wizards screen: it must know what are the |
| 40 | // following and preceding pages (which may be NULL for the first/last page). |
| 41 | // |
| 42 | // Other than GetNext/Prev() functions, wxWizardPage is just a panel and may be |
| 43 | // used as such (i.e. controls may be placed directly on it &c). |
| 44 | // ---------------------------------------------------------------------------- |
| 45 | |
| 46 | class WXDLLEXPORT wxWizardPage : public wxPanel |
| 47 | { |
| 48 | public: |
| 49 | // ctor accepts an optional bitmap which will be used for this page instead |
| 50 | // of the default one for this wizard (should be of the same size). Notice |
| 51 | // that no other parameters are needed because the wizard will resize and |
| 52 | // reposition the page anyhow |
| 53 | wxWizardPage(wxWizard *parent, |
| 54 | const wxBitmap& bitmap = wxNullBitmap, |
| 55 | const wxChar* resource = NULL); |
| 56 | |
| 57 | // these functions are used by the wizard to show another page when the |
| 58 | // user chooses "Back" or "Next" button |
| 59 | virtual wxWizardPage *GetPrev() const = 0; |
| 60 | virtual wxWizardPage *GetNext() const = 0; |
| 61 | |
| 62 | // default GetBitmap() will just return m_bitmap which is ok in 99% of |
| 63 | // cases - override this method if you want to create the bitmap to be used |
| 64 | // dynamically or to do something even more fancy. It's ok to return |
| 65 | // wxNullBitmap from here - the default one will be used then. |
| 66 | virtual wxBitmap GetBitmap() const { return m_bitmap; } |
| 67 | |
| 68 | protected: |
| 69 | wxBitmap m_bitmap; |
| 70 | |
| 71 | private: |
| 72 | DECLARE_ABSTRACT_CLASS(wxWizardPage) |
| 73 | }; |
| 74 | |
| 75 | // ---------------------------------------------------------------------------- |
| 76 | // wxWizardPageSimple just returns the pointers given to the ctor and is useful |
| 77 | // to create a simple wizard where the order of pages never changes. |
| 78 | // |
| 79 | // OTOH, it is also possible to dynamicly decide which page to return (i.e. |
| 80 | // depending on the user's choices) as the wizard sample shows - in order to do |
| 81 | // this, you must derive from wxWizardPage directly. |
| 82 | // ---------------------------------------------------------------------------- |
| 83 | |
| 84 | class WXDLLEXPORT wxWizardPageSimple : public wxWizardPage |
| 85 | { |
| 86 | public: |
| 87 | // ctor takes the previous and next pages |
| 88 | wxWizardPageSimple(wxWizard *parent = NULL, // let it be default ctor too |
| 89 | wxWizardPage *prev = (wxWizardPage *)NULL, |
| 90 | wxWizardPage *next = (wxWizardPage *)NULL, |
| 91 | const wxBitmap& bitmap = wxNullBitmap, |
| 92 | const wxChar* resource = NULL) |
| 93 | : wxWizardPage(parent, bitmap, resource) |
| 94 | { |
| 95 | m_prev = prev; |
| 96 | m_next = next; |
| 97 | } |
| 98 | |
| 99 | // the pointers may be also set later - but before starting the wizard |
| 100 | void SetPrev(wxWizardPage *prev) { m_prev = prev; } |
| 101 | void SetNext(wxWizardPage *next) { m_next = next; } |
| 102 | |
| 103 | // a convenience function to make the pages follow each other |
| 104 | static void Chain(wxWizardPageSimple *first, wxWizardPageSimple *second) |
| 105 | { |
| 106 | wxCHECK_RET( first && second, |
| 107 | wxT("NULL passed to wxWizardPageSimple::Chain") ); |
| 108 | |
| 109 | first->SetNext(second); |
| 110 | second->SetPrev(first); |
| 111 | } |
| 112 | |
| 113 | // base class pure virtuals |
| 114 | virtual wxWizardPage *GetPrev() const; |
| 115 | virtual wxWizardPage *GetNext() const; |
| 116 | |
| 117 | private: |
| 118 | // pointers are private, the derived classes shouldn't mess with them - |
| 119 | // just derive from wxWizardPage directly to implement different behaviour |
| 120 | wxWizardPage *m_prev, |
| 121 | *m_next; |
| 122 | |
| 123 | DECLARE_DYNAMIC_CLASS(wxWizardPageSimple) |
| 124 | }; |
| 125 | |
| 126 | // ---------------------------------------------------------------------------- |
| 127 | // wxWizard |
| 128 | // ---------------------------------------------------------------------------- |
| 129 | |
| 130 | class WXDLLEXPORT wxWizardBase : public wxDialog |
| 131 | { |
| 132 | public: |
| 133 | // create the wizard control |
| 134 | static wxWizard *Create(wxWindow *parent, |
| 135 | int id = -1, |
| 136 | const wxString& title = wxEmptyString, |
| 137 | const wxBitmap& bitmap = wxNullBitmap, |
| 138 | const wxPoint& pos = wxDefaultPosition, |
| 139 | const wxSize& size = wxDefaultSize); |
| 140 | |
| 141 | // executes the wizard starting from the given page, returns TRUE if it was |
| 142 | // successfully finished, FALSE if user cancelled it |
| 143 | virtual bool RunWizard(wxWizardPage *firstPage) = 0; |
| 144 | |
| 145 | // get the current page (NULL if RunWizard() isn't running) |
| 146 | virtual wxWizardPage *GetCurrentPage() const = 0; |
| 147 | |
| 148 | // set the min size which should be available for the pages: a |
| 149 | // wizard will take into account the size of the bitmap (if any) |
| 150 | // itself and will never be less than some predefined fixed size |
| 151 | virtual void SetPageSize(const wxSize& size) = 0; |
| 152 | |
| 153 | // get the size available for the page: the wizards are not resizeable, so |
| 154 | // this size doesn't change |
| 155 | virtual wxSize GetPageSize() const = 0; |
| 156 | }; |
| 157 | |
| 158 | // include the real class declaration |
| 159 | #include "wx/generic/wizard.h" |
| 160 | |
| 161 | // ---------------------------------------------------------------------------- |
| 162 | // wxWizardEvent class represents an event generated by the wizard: this event |
| 163 | // is first sent to the page itself and, if not processed there, goes up the |
| 164 | // window hierarchy as usual |
| 165 | // ---------------------------------------------------------------------------- |
| 166 | |
| 167 | class WXDLLEXPORT wxWizardEvent : public wxNotifyEvent |
| 168 | { |
| 169 | public: |
| 170 | wxWizardEvent(wxEventType type = wxEVT_NULL, |
| 171 | int id = -1, |
| 172 | bool direction = TRUE, |
| 173 | wxWizardPage* page = NULL); |
| 174 | |
| 175 | // for EVT_WIZARD_PAGE_CHANGING, return TRUE if we're going forward or |
| 176 | // FALSE otherwise and for EVT_WIZARD_PAGE_CHANGED return TRUE if we came |
| 177 | // from the previous page and FALSE if we returned from the next one |
| 178 | // (this function doesn't make sense for CANCEL events) |
| 179 | bool GetDirection() const { return m_direction; } |
| 180 | |
| 181 | wxWizardPage* GetPage() const { return m_page; } |
| 182 | |
| 183 | private: |
| 184 | bool m_direction; |
| 185 | wxWizardPage* m_page; |
| 186 | |
| 187 | DECLARE_DYNAMIC_CLASS(wxWizardEvent) |
| 188 | }; |
| 189 | |
| 190 | // ---------------------------------------------------------------------------- |
| 191 | // macros for handling wxWizardEvents |
| 192 | // ---------------------------------------------------------------------------- |
| 193 | |
| 194 | BEGIN_DECLARE_EVENT_TYPES() |
| 195 | DECLARE_EVENT_TYPE(wxEVT_WIZARD_PAGE_CHANGED, 900) |
| 196 | DECLARE_EVENT_TYPE(wxEVT_WIZARD_PAGE_CHANGING, 901) |
| 197 | DECLARE_EVENT_TYPE(wxEVT_WIZARD_CANCEL, 902) |
| 198 | DECLARE_EVENT_TYPE(wxEVT_WIZARD_HELP, 903) |
| 199 | END_DECLARE_EVENT_TYPES() |
| 200 | |
| 201 | typedef void (wxEvtHandler::*wxWizardEventFunction)(wxWizardEvent&); |
| 202 | |
| 203 | // notifies that the page has just been changed (can't be vetoed) |
| 204 | #define EVT_WIZARD_PAGE_CHANGED(id, fn) DECLARE_EVENT_TABLE_ENTRY(wxEVT_WIZARD_PAGE_CHANGED, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxWizardEventFunction) & fn, (wxObject *)NULL), |
| 205 | |
| 206 | // the user pressed "<Back" or "Next>" button and the page is going to be |
| 207 | // changed - unless the event handler vetoes the event |
| 208 | #define EVT_WIZARD_PAGE_CHANGING(id, fn) DECLARE_EVENT_TABLE_ENTRY(wxEVT_WIZARD_PAGE_CHANGING, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxWizardEventFunction) & fn, (wxObject *)NULL), |
| 209 | |
| 210 | // the user pressed "Cancel" button and the wizard is going to be dismissed - |
| 211 | // unless the event handler vetoes the event |
| 212 | #define EVT_WIZARD_CANCEL(id, fn) DECLARE_EVENT_TABLE_ENTRY(wxEVT_WIZARD_CANCEL, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxWizardEventFunction) & fn, (wxObject *)NULL), |
| 213 | |
| 214 | // the user pressed "Help" button |
| 215 | #define EVT_WIZARD_HELP(id, fn) DECLARE_EVENT_TABLE_ENTRY(wxEVT_WIZARD_HELP, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxWizardEventFunction) & fn, (wxObject *)NULL), |
| 216 | |
| 217 | #endif // wxUSE_WIZARDDLG |
| 218 | |
| 219 | #endif // _WX_WIZARD_H_ |