| 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 | wxWizardPage() { Init(); } |
| 50 | // common part of ctors: |
| 51 | void Init(); |
| 52 | |
| 53 | // ctor accepts an optional bitmap which will be used for this page instead |
| 54 | // of the default one for this wizard (should be of the same size). Notice |
| 55 | // that no other parameters are needed because the wizard will resize and |
| 56 | // reposition the page anyhow |
| 57 | wxWizardPage(wxWizard *parent, |
| 58 | const wxBitmap& bitmap = wxNullBitmap, |
| 59 | const wxChar* resource = NULL); |
| 60 | |
| 61 | bool Create(wxWizard *parent, |
| 62 | const wxBitmap& bitmap = wxNullBitmap, |
| 63 | const wxChar* resource = NULL); |
| 64 | |
| 65 | // these functions are used by the wizard to show another page when the |
| 66 | // user chooses "Back" or "Next" button |
| 67 | virtual wxWizardPage *GetPrev() const = 0; |
| 68 | virtual wxWizardPage *GetNext() const = 0; |
| 69 | |
| 70 | // default GetBitmap() will just return m_bitmap which is ok in 99% of |
| 71 | // cases - override this method if you want to create the bitmap to be used |
| 72 | // dynamically or to do something even more fancy. It's ok to return |
| 73 | // wxNullBitmap from here - the default one will be used then. |
| 74 | virtual wxBitmap GetBitmap() const { return m_bitmap; } |
| 75 | |
| 76 | protected: |
| 77 | wxBitmap m_bitmap; |
| 78 | |
| 79 | private: |
| 80 | DECLARE_ABSTRACT_CLASS(wxWizardPage) |
| 81 | }; |
| 82 | |
| 83 | // ---------------------------------------------------------------------------- |
| 84 | // wxWizardPageSimple just returns the pointers given to the ctor and is useful |
| 85 | // to create a simple wizard where the order of pages never changes. |
| 86 | // |
| 87 | // OTOH, it is also possible to dynamicly decide which page to return (i.e. |
| 88 | // depending on the user's choices) as the wizard sample shows - in order to do |
| 89 | // this, you must derive from wxWizardPage directly. |
| 90 | // ---------------------------------------------------------------------------- |
| 91 | |
| 92 | class WXDLLEXPORT wxWizardPageSimple : public wxWizardPage |
| 93 | { |
| 94 | public: |
| 95 | wxWizardPageSimple() { Init(); } |
| 96 | // common part of ctors: |
| 97 | void Init() |
| 98 | { |
| 99 | m_prev = m_next = NULL; |
| 100 | } |
| 101 | |
| 102 | // ctor takes the previous and next pages |
| 103 | wxWizardPageSimple(wxWizard *parent, |
| 104 | wxWizardPage *prev = (wxWizardPage *)NULL, |
| 105 | wxWizardPage *next = (wxWizardPage *)NULL, |
| 106 | const wxBitmap& bitmap = wxNullBitmap, |
| 107 | const wxChar* resource = NULL) |
| 108 | { |
| 109 | Create(parent, prev, next, bitmap, resource); |
| 110 | } |
| 111 | |
| 112 | bool Create(wxWizard *parent = NULL, // let it be default ctor too |
| 113 | wxWizardPage *prev = (wxWizardPage *)NULL, |
| 114 | wxWizardPage *next = (wxWizardPage *)NULL, |
| 115 | const wxBitmap& bitmap = wxNullBitmap, |
| 116 | const wxChar* resource = NULL) |
| 117 | { |
| 118 | m_prev = prev; |
| 119 | m_next = next; |
| 120 | return wxWizardPage::Create(parent, bitmap, resource); |
| 121 | } |
| 122 | |
| 123 | // the pointers may be also set later - but before starting the wizard |
| 124 | void SetPrev(wxWizardPage *prev) { m_prev = prev; } |
| 125 | void SetNext(wxWizardPage *next) { m_next = next; } |
| 126 | |
| 127 | // a convenience function to make the pages follow each other |
| 128 | static void Chain(wxWizardPageSimple *first, wxWizardPageSimple *second) |
| 129 | { |
| 130 | wxCHECK_RET( first && second, |
| 131 | wxT("NULL passed to wxWizardPageSimple::Chain") ); |
| 132 | |
| 133 | first->SetNext(second); |
| 134 | second->SetPrev(first); |
| 135 | } |
| 136 | |
| 137 | // base class pure virtuals |
| 138 | virtual wxWizardPage *GetPrev() const; |
| 139 | virtual wxWizardPage *GetNext() const; |
| 140 | |
| 141 | private: |
| 142 | // pointers are private, the derived classes shouldn't mess with them - |
| 143 | // just derive from wxWizardPage directly to implement different behaviour |
| 144 | wxWizardPage *m_prev, |
| 145 | *m_next; |
| 146 | |
| 147 | DECLARE_DYNAMIC_CLASS(wxWizardPageSimple) |
| 148 | }; |
| 149 | |
| 150 | // ---------------------------------------------------------------------------- |
| 151 | // wxWizard |
| 152 | // ---------------------------------------------------------------------------- |
| 153 | |
| 154 | class WXDLLEXPORT wxWizardBase : public wxDialog |
| 155 | { |
| 156 | public: |
| 157 | // create the wizard control |
| 158 | static wxWizard *Create(wxWindow *parent, |
| 159 | int id = -1, |
| 160 | const wxString& title = wxEmptyString, |
| 161 | const wxBitmap& bitmap = wxNullBitmap, |
| 162 | const wxPoint& pos = wxDefaultPosition, |
| 163 | const wxSize& size = wxDefaultSize); |
| 164 | |
| 165 | // executes the wizard starting from the given page, returns TRUE if it was |
| 166 | // successfully finished, FALSE if user cancelled it |
| 167 | virtual bool RunWizard(wxWizardPage *firstPage) = 0; |
| 168 | |
| 169 | // get the current page (NULL if RunWizard() isn't running) |
| 170 | virtual wxWizardPage *GetCurrentPage() const = 0; |
| 171 | |
| 172 | // set the min size which should be available for the pages: a |
| 173 | // wizard will take into account the size of the bitmap (if any) |
| 174 | // itself and will never be less than some predefined fixed size |
| 175 | virtual void SetPageSize(const wxSize& size) = 0; |
| 176 | |
| 177 | // get the size available for the page: the wizards are not resizeable, so |
| 178 | // this size doesn't change |
| 179 | virtual wxSize GetPageSize() const = 0; |
| 180 | |
| 181 | // set the best size for the wizard, i.e. make it big enough to contain all |
| 182 | // of the pages starting from the given one |
| 183 | // |
| 184 | // this function may be called several times and possible with different |
| 185 | // pages in which case it will only increase the page size if needed (this |
| 186 | // may be useful if not all pages are accessible from the first one by |
| 187 | // default) |
| 188 | virtual void FitToPage(const wxWizardPage *firstPage) = 0; |
| 189 | }; |
| 190 | |
| 191 | // include the real class declaration |
| 192 | #include "wx/generic/wizard.h" |
| 193 | |
| 194 | // ---------------------------------------------------------------------------- |
| 195 | // wxWizardEvent class represents an event generated by the wizard: this event |
| 196 | // is first sent to the page itself and, if not processed there, goes up the |
| 197 | // window hierarchy as usual |
| 198 | // ---------------------------------------------------------------------------- |
| 199 | |
| 200 | class WXDLLEXPORT wxWizardEvent : public wxNotifyEvent |
| 201 | { |
| 202 | public: |
| 203 | wxWizardEvent(wxEventType type = wxEVT_NULL, |
| 204 | int id = -1, |
| 205 | bool direction = TRUE, |
| 206 | wxWizardPage* page = NULL); |
| 207 | |
| 208 | // for EVT_WIZARD_PAGE_CHANGING, return TRUE if we're going forward or |
| 209 | // FALSE otherwise and for EVT_WIZARD_PAGE_CHANGED return TRUE if we came |
| 210 | // from the previous page and FALSE if we returned from the next one |
| 211 | // (this function doesn't make sense for CANCEL events) |
| 212 | bool GetDirection() const { return m_direction; } |
| 213 | |
| 214 | wxWizardPage* GetPage() const { return m_page; } |
| 215 | |
| 216 | private: |
| 217 | bool m_direction; |
| 218 | wxWizardPage* m_page; |
| 219 | |
| 220 | DECLARE_DYNAMIC_CLASS(wxWizardEvent) |
| 221 | }; |
| 222 | |
| 223 | // ---------------------------------------------------------------------------- |
| 224 | // macros for handling wxWizardEvents |
| 225 | // ---------------------------------------------------------------------------- |
| 226 | |
| 227 | BEGIN_DECLARE_EVENT_TYPES() |
| 228 | DECLARE_EVENT_TYPE(wxEVT_WIZARD_PAGE_CHANGED, 900) |
| 229 | DECLARE_EVENT_TYPE(wxEVT_WIZARD_PAGE_CHANGING, 901) |
| 230 | DECLARE_EVENT_TYPE(wxEVT_WIZARD_CANCEL, 902) |
| 231 | DECLARE_EVENT_TYPE(wxEVT_WIZARD_HELP, 903) |
| 232 | END_DECLARE_EVENT_TYPES() |
| 233 | |
| 234 | typedef void (wxEvtHandler::*wxWizardEventFunction)(wxWizardEvent&); |
| 235 | |
| 236 | // notifies that the page has just been changed (can't be vetoed) |
| 237 | #define EVT_WIZARD_PAGE_CHANGED(id, fn) DECLARE_EVENT_TABLE_ENTRY(wxEVT_WIZARD_PAGE_CHANGED, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxWizardEventFunction) & fn, (wxObject *)NULL), |
| 238 | |
| 239 | // the user pressed "<Back" or "Next>" button and the page is going to be |
| 240 | // changed - unless the event handler vetoes the event |
| 241 | #define EVT_WIZARD_PAGE_CHANGING(id, fn) DECLARE_EVENT_TABLE_ENTRY(wxEVT_WIZARD_PAGE_CHANGING, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxWizardEventFunction) & fn, (wxObject *)NULL), |
| 242 | |
| 243 | // the user pressed "Cancel" button and the wizard is going to be dismissed - |
| 244 | // unless the event handler vetoes the event |
| 245 | #define EVT_WIZARD_CANCEL(id, fn) DECLARE_EVENT_TABLE_ENTRY(wxEVT_WIZARD_CANCEL, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxWizardEventFunction) & fn, (wxObject *)NULL), |
| 246 | |
| 247 | // the user pressed "Help" button |
| 248 | #define EVT_WIZARD_HELP(id, fn) DECLARE_EVENT_TABLE_ENTRY(wxEVT_WIZARD_HELP, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxWizardEventFunction) & fn, (wxObject *)NULL), |
| 249 | |
| 250 | #endif // wxUSE_WIZARDDLG |
| 251 | |
| 252 | #endif // _WX_WIZARD_H_ |