| 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 | // Robert Vazan (sizers) |
| 11 | // Created: 15.08.99 |
| 12 | // RCS-ID: $Id$ |
| 13 | // Copyright: (c) 1999 Vadim Zeitlin <zeitlin@dptmaths.ens-cachan.fr> |
| 14 | // Licence: wxWindows licence |
| 15 | /////////////////////////////////////////////////////////////////////////////// |
| 16 | |
| 17 | #ifndef _WX_WIZARD_H_ |
| 18 | #define _WX_WIZARD_H_ |
| 19 | |
| 20 | #include "wx/defs.h" |
| 21 | |
| 22 | #if wxUSE_WIZARDDLG |
| 23 | |
| 24 | // ---------------------------------------------------------------------------- |
| 25 | // headers and other simple declarations |
| 26 | // ---------------------------------------------------------------------------- |
| 27 | |
| 28 | #include "wx/dialog.h" // the base class |
| 29 | #include "wx/panel.h" // ditto |
| 30 | #include "wx/event.h" // wxEVT_XXX constants |
| 31 | #include "wx/bitmap.h" |
| 32 | |
| 33 | // Extended style to specify a help button |
| 34 | #define wxWIZARD_EX_HELPBUTTON 0x00000010 |
| 35 | |
| 36 | // forward declarations |
| 37 | class WXDLLIMPEXP_ADV wxWizard; |
| 38 | |
| 39 | // ---------------------------------------------------------------------------- |
| 40 | // wxWizardPage is one of the wizards screen: it must know what are the |
| 41 | // following and preceding pages (which may be NULL for the first/last page). |
| 42 | // |
| 43 | // Other than GetNext/Prev() functions, wxWizardPage is just a panel and may be |
| 44 | // used as such (i.e. controls may be placed directly on it &c). |
| 45 | // ---------------------------------------------------------------------------- |
| 46 | |
| 47 | class WXDLLIMPEXP_ADV wxWizardPage : public wxPanel |
| 48 | { |
| 49 | public: |
| 50 | wxWizardPage() { Init(); } |
| 51 | |
| 52 | // ctor accepts an optional bitmap which will be used for this page instead |
| 53 | // of the default one for this wizard (should be of the same size). Notice |
| 54 | // that no other parameters are needed because the wizard will resize and |
| 55 | // reposition the page anyhow |
| 56 | wxWizardPage(wxWizard *parent, |
| 57 | const wxBitmap& bitmap = wxNullBitmap, |
| 58 | const wxChar* resource = NULL); |
| 59 | |
| 60 | bool Create(wxWizard *parent, |
| 61 | const wxBitmap& bitmap = wxNullBitmap, |
| 62 | const wxChar* resource = NULL); |
| 63 | |
| 64 | // these functions are used by the wizard to show another page when the |
| 65 | // user chooses "Back" or "Next" button |
| 66 | virtual wxWizardPage *GetPrev() const = 0; |
| 67 | virtual wxWizardPage *GetNext() const = 0; |
| 68 | |
| 69 | // default GetBitmap() will just return m_bitmap which is ok in 99% of |
| 70 | // cases - override this method if you want to create the bitmap to be used |
| 71 | // dynamically or to do something even more fancy. It's ok to return |
| 72 | // wxNullBitmap from here - the default one will be used then. |
| 73 | virtual wxBitmap GetBitmap() const { return m_bitmap; } |
| 74 | |
| 75 | #if wxUSE_VALIDATORS |
| 76 | // Override the base functions to allow a validator to be assigned to this page. |
| 77 | virtual bool TransferDataToWindow() |
| 78 | { |
| 79 | return GetValidator() ? GetValidator()->TransferToWindow() |
| 80 | : wxPanel::TransferDataToWindow(); |
| 81 | } |
| 82 | |
| 83 | virtual bool TransferDataFromWindow() |
| 84 | { |
| 85 | return GetValidator() ? GetValidator()->TransferFromWindow() |
| 86 | : wxPanel::TransferDataFromWindow(); |
| 87 | } |
| 88 | |
| 89 | virtual bool Validate() |
| 90 | { |
| 91 | return GetValidator() ? GetValidator()->Validate(this) |
| 92 | : wxPanel::Validate(); |
| 93 | } |
| 94 | #endif // wxUSE_VALIDATORS |
| 95 | |
| 96 | protected: |
| 97 | // common part of ctors: |
| 98 | void Init(); |
| 99 | |
| 100 | wxBitmap m_bitmap; |
| 101 | |
| 102 | private: |
| 103 | DECLARE_DYNAMIC_CLASS_NO_COPY(wxWizardPage) |
| 104 | }; |
| 105 | |
| 106 | // ---------------------------------------------------------------------------- |
| 107 | // wxWizardPageSimple just returns the pointers given to the ctor and is useful |
| 108 | // to create a simple wizard where the order of pages never changes. |
| 109 | // |
| 110 | // OTOH, it is also possible to dynamicly decide which page to return (i.e. |
| 111 | // depending on the user's choices) as the wizard sample shows - in order to do |
| 112 | // this, you must derive from wxWizardPage directly. |
| 113 | // ---------------------------------------------------------------------------- |
| 114 | |
| 115 | class WXDLLIMPEXP_ADV wxWizardPageSimple : public wxWizardPage |
| 116 | { |
| 117 | public: |
| 118 | wxWizardPageSimple() { Init(); } |
| 119 | |
| 120 | // ctor takes the previous and next pages |
| 121 | wxWizardPageSimple(wxWizard *parent, |
| 122 | wxWizardPage *prev = (wxWizardPage *)NULL, |
| 123 | wxWizardPage *next = (wxWizardPage *)NULL, |
| 124 | const wxBitmap& bitmap = wxNullBitmap, |
| 125 | const wxChar* resource = NULL) |
| 126 | { |
| 127 | Create(parent, prev, next, bitmap, resource); |
| 128 | } |
| 129 | |
| 130 | bool Create(wxWizard *parent = NULL, // let it be default ctor too |
| 131 | wxWizardPage *prev = (wxWizardPage *)NULL, |
| 132 | wxWizardPage *next = (wxWizardPage *)NULL, |
| 133 | const wxBitmap& bitmap = wxNullBitmap, |
| 134 | const wxChar* resource = NULL) |
| 135 | { |
| 136 | m_prev = prev; |
| 137 | m_next = next; |
| 138 | return wxWizardPage::Create(parent, bitmap, resource); |
| 139 | } |
| 140 | |
| 141 | // the pointers may be also set later - but before starting the wizard |
| 142 | void SetPrev(wxWizardPage *prev) { m_prev = prev; } |
| 143 | void SetNext(wxWizardPage *next) { m_next = next; } |
| 144 | |
| 145 | // a convenience function to make the pages follow each other |
| 146 | static void Chain(wxWizardPageSimple *first, wxWizardPageSimple *second) |
| 147 | { |
| 148 | wxCHECK_RET( first && second, |
| 149 | wxT("NULL passed to wxWizardPageSimple::Chain") ); |
| 150 | |
| 151 | first->SetNext(second); |
| 152 | second->SetPrev(first); |
| 153 | } |
| 154 | |
| 155 | // base class pure virtuals |
| 156 | virtual wxWizardPage *GetPrev() const; |
| 157 | virtual wxWizardPage *GetNext() const; |
| 158 | |
| 159 | private: |
| 160 | // common part of ctors: |
| 161 | void Init() |
| 162 | { |
| 163 | m_prev = m_next = NULL; |
| 164 | } |
| 165 | |
| 166 | // pointers are private, the derived classes shouldn't mess with them - |
| 167 | // just derive from wxWizardPage directly to implement different behaviour |
| 168 | wxWizardPage *m_prev, |
| 169 | *m_next; |
| 170 | |
| 171 | DECLARE_DYNAMIC_CLASS_NO_COPY(wxWizardPageSimple) |
| 172 | }; |
| 173 | |
| 174 | // ---------------------------------------------------------------------------- |
| 175 | // wxWizard |
| 176 | // ---------------------------------------------------------------------------- |
| 177 | |
| 178 | class WXDLLIMPEXP_ADV wxWizardBase : public wxDialog |
| 179 | { |
| 180 | public: |
| 181 | /* |
| 182 | The derived class (i.e. the real wxWizard) has a ctor and Create() |
| 183 | function taking the following arguments: |
| 184 | |
| 185 | wxWizard(wxWindow *parent, |
| 186 | int id = wxID_ANY, |
| 187 | const wxString& title = wxEmptyString, |
| 188 | const wxBitmap& bitmap = wxNullBitmap, |
| 189 | const wxPoint& pos = wxDefaultPosition, |
| 190 | long style = wxDEFAULT_DIALOG_STYLE); |
| 191 | */ |
| 192 | wxWizardBase() { } |
| 193 | |
| 194 | // executes the wizard starting from the given page, returns true if it was |
| 195 | // successfully finished, false if user cancelled it |
| 196 | virtual bool RunWizard(wxWizardPage *firstPage) = 0; |
| 197 | |
| 198 | // get the current page (NULL if RunWizard() isn't running) |
| 199 | virtual wxWizardPage *GetCurrentPage() const = 0; |
| 200 | |
| 201 | // set the min size which should be available for the pages: a |
| 202 | // wizard will take into account the size of the bitmap (if any) |
| 203 | // itself and will never be less than some predefined fixed size |
| 204 | virtual void SetPageSize(const wxSize& size) = 0; |
| 205 | |
| 206 | // get the size available for the page |
| 207 | virtual wxSize GetPageSize() const = 0; |
| 208 | |
| 209 | // set the best size for the wizard, i.e. make it big enough to contain all |
| 210 | // of the pages starting from the given one |
| 211 | // |
| 212 | // this function may be called several times and possible with different |
| 213 | // pages in which case it will only increase the page size if needed (this |
| 214 | // may be useful if not all pages are accessible from the first one by |
| 215 | // default) |
| 216 | virtual void FitToPage(const wxWizardPage *firstPage) = 0; |
| 217 | |
| 218 | // Adding pages to page area sizer enlarges wizard |
| 219 | virtual wxSizer *GetPageAreaSizer() const = 0; |
| 220 | |
| 221 | // Set border around page area. Default is 0 if you add at least one |
| 222 | // page to GetPageAreaSizer and 5 if you don't. |
| 223 | virtual void SetBorder(int border) = 0; |
| 224 | |
| 225 | // the methods below may be overridden by the derived classes to provide |
| 226 | // custom logic for determining the pages order |
| 227 | |
| 228 | virtual bool HasNextPage(wxWizardPage *page) |
| 229 | { return page->GetNext() != NULL; } |
| 230 | |
| 231 | virtual bool HasPrevPage(wxWizardPage *page) |
| 232 | { return page->GetPrev() != NULL; } |
| 233 | |
| 234 | /// Override these functions to stop InitDialog from calling TransferDataToWindow |
| 235 | /// for _all_ pages when the wizard starts. Instead 'ShowPage' will call |
| 236 | /// TransferDataToWindow for the first page only. |
| 237 | bool TransferDataToWindow() { return true; } |
| 238 | bool TransferDataFromWindow() { return true; } |
| 239 | bool Validate() { return true; } |
| 240 | |
| 241 | private: |
| 242 | DECLARE_NO_COPY_CLASS(wxWizardBase) |
| 243 | }; |
| 244 | |
| 245 | // include the real class declaration |
| 246 | #include "wx/generic/wizard.h" |
| 247 | |
| 248 | // ---------------------------------------------------------------------------- |
| 249 | // wxWizardEvent class represents an event generated by the wizard: this event |
| 250 | // is first sent to the page itself and, if not processed there, goes up the |
| 251 | // window hierarchy as usual |
| 252 | // ---------------------------------------------------------------------------- |
| 253 | |
| 254 | class WXDLLIMPEXP_ADV wxWizardEvent : public wxNotifyEvent |
| 255 | { |
| 256 | public: |
| 257 | wxWizardEvent(wxEventType type = wxEVT_NULL, |
| 258 | int id = wxID_ANY, |
| 259 | bool direction = true, |
| 260 | wxWizardPage* page = NULL); |
| 261 | |
| 262 | // for EVT_WIZARD_PAGE_CHANGING, return true if we're going forward or |
| 263 | // false otherwise and for EVT_WIZARD_PAGE_CHANGED return true if we came |
| 264 | // from the previous page and false if we returned from the next one |
| 265 | // (this function doesn't make sense for CANCEL events) |
| 266 | bool GetDirection() const { return m_direction; } |
| 267 | |
| 268 | wxWizardPage* GetPage() const { return m_page; } |
| 269 | |
| 270 | private: |
| 271 | bool m_direction; |
| 272 | wxWizardPage* m_page; |
| 273 | |
| 274 | DECLARE_DYNAMIC_CLASS(wxWizardEvent) |
| 275 | DECLARE_NO_COPY_CLASS(wxWizardEvent) |
| 276 | }; |
| 277 | |
| 278 | // ---------------------------------------------------------------------------- |
| 279 | // macros for handling wxWizardEvents |
| 280 | // ---------------------------------------------------------------------------- |
| 281 | |
| 282 | BEGIN_DECLARE_EVENT_TYPES() |
| 283 | DECLARE_EXPORTED_EVENT_TYPE(WXDLLIMPEXP_ADV, wxEVT_WIZARD_PAGE_CHANGED, 900) |
| 284 | DECLARE_EXPORTED_EVENT_TYPE(WXDLLIMPEXP_ADV, wxEVT_WIZARD_PAGE_CHANGING, 901) |
| 285 | DECLARE_EXPORTED_EVENT_TYPE(WXDLLIMPEXP_ADV, wxEVT_WIZARD_CANCEL, 902) |
| 286 | DECLARE_EXPORTED_EVENT_TYPE(WXDLLIMPEXP_ADV, wxEVT_WIZARD_HELP, 903) |
| 287 | DECLARE_EXPORTED_EVENT_TYPE(WXDLLIMPEXP_ADV, wxEVT_WIZARD_FINISHED, 903) |
| 288 | END_DECLARE_EVENT_TYPES() |
| 289 | |
| 290 | typedef void (wxEvtHandler::*wxWizardEventFunction)(wxWizardEvent&); |
| 291 | |
| 292 | #define wxWizardEventHandler(func) \ |
| 293 | (wxObjectEventFunction)(wxEventFunction)wxStaticCastEvent(wxWizardEventFunction, &func) |
| 294 | |
| 295 | #define wx__DECLARE_WIZARDEVT(evt, id, fn) \ |
| 296 | wx__DECLARE_EVT1(wxEVT_WIZARD_ ## evt, id, wxWizardEventHandler(fn)) |
| 297 | |
| 298 | // notifies that the page has just been changed (can't be vetoed) |
| 299 | #define EVT_WIZARD_PAGE_CHANGED(id, fn) wx__DECLARE_WIZARDEVT(PAGE_CHANGED, id, fn) |
| 300 | |
| 301 | // the user pressed "<Back" or "Next>" button and the page is going to be |
| 302 | // changed - unless the event handler vetoes the event |
| 303 | #define EVT_WIZARD_PAGE_CHANGING(id, fn) wx__DECLARE_WIZARDEVT(PAGE_CHANGING, id, fn) |
| 304 | |
| 305 | // the user pressed "Cancel" button and the wizard is going to be dismissed - |
| 306 | // unless the event handler vetoes the event |
| 307 | #define EVT_WIZARD_CANCEL(id, fn) wx__DECLARE_WIZARDEVT(CANCEL, id, fn) |
| 308 | |
| 309 | // the user pressed "Finish" button and the wizard is going to be dismissed - |
| 310 | #define EVT_WIZARD_FINISHED(id, fn) wx__DECLARE_WIZARDEVT(FINISHED, id, fn) |
| 311 | |
| 312 | // the user pressed "Help" button |
| 313 | #define EVT_WIZARD_HELP(id, fn) wx__DECLARE_WIZARDEVT(HELP, id, fn) |
| 314 | |
| 315 | #endif // wxUSE_WIZARDDLG |
| 316 | |
| 317 | #endif // _WX_WIZARD_H_ |