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: wizard.h 63262 2010-01-25 18:47:47Z JS $ 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_FWD_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: wxWizardPage()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. GetBitmap()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. TransferDataToWindow()77 virtual bool TransferDataToWindow() 78 { 79 return GetValidator() ? GetValidator()->TransferToWindow() 80 : wxPanel::TransferDataToWindow(); 81 } 82 TransferDataFromWindow()83 virtual bool TransferDataFromWindow() 84 { 85 return GetValidator() ? GetValidator()->TransferFromWindow() 86 : wxPanel::TransferDataFromWindow(); 87 } 88 Validate()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: wxWizardPageSimple()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 SetPrev(wxWizardPage * prev)142 void SetPrev(wxWizardPage *prev) { m_prev = prev; } SetNext(wxWizardPage * next)143 void SetNext(wxWizardPage *next) { m_next = next; } 144 145 // a convenience function to make the pages follow each other Chain(wxWizardPageSimple * first,wxWizardPageSimple * second)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: Init()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 */ wxWizardBase()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 HasNextPage(wxWizardPage * page)228 virtual bool HasNextPage(wxWizardPage *page) 229 { return page->GetNext() != NULL; } 230 HasPrevPage(wxWizardPage * page)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. TransferDataToWindow()237 bool TransferDataToWindow() { return true; } TransferDataFromWindow()238 bool TransferDataFromWindow() { return true; } Validate()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) GetDirection()266 bool GetDirection() const { return m_direction; } 267 GetPage()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 #if wxABI_VERSION >= 20811 289 DECLARE_EXPORTED_EVENT_TYPE(WXDLLIMPEXP_ADV, wxEVT_WIZARD_PAGE_SHOWN, 904) 290 #endif 291 END_DECLARE_EVENT_TYPES() 292 293 typedef void (wxEvtHandler::*wxWizardEventFunction)(wxWizardEvent&); 294 295 #define wxWizardEventHandler(func) \ 296 (wxObjectEventFunction)(wxEventFunction)wxStaticCastEvent(wxWizardEventFunction, &func) 297 298 #define wx__DECLARE_WIZARDEVT(evt, id, fn) \ 299 wx__DECLARE_EVT1(wxEVT_WIZARD_ ## evt, id, wxWizardEventHandler(fn)) 300 301 // notifies that the page has just been changed (can't be vetoed) 302 #define EVT_WIZARD_PAGE_CHANGED(id, fn) wx__DECLARE_WIZARDEVT(PAGE_CHANGED, id, fn) 303 304 // the user pressed "<Back" or "Next>" button and the page is going to be 305 // changed - unless the event handler vetoes the event 306 #define EVT_WIZARD_PAGE_CHANGING(id, fn) wx__DECLARE_WIZARDEVT(PAGE_CHANGING, id, fn) 307 308 // the user pressed "Cancel" button and the wizard is going to be dismissed - 309 // unless the event handler vetoes the event 310 #define EVT_WIZARD_CANCEL(id, fn) wx__DECLARE_WIZARDEVT(CANCEL, id, fn) 311 312 // the user pressed "Finish" button and the wizard is going to be dismissed - 313 #define EVT_WIZARD_FINISHED(id, fn) wx__DECLARE_WIZARDEVT(FINISHED, id, fn) 314 315 // the user pressed "Help" button 316 #define EVT_WIZARD_HELP(id, fn) wx__DECLARE_WIZARDEVT(HELP, id, fn) 317 318 // the page was just shown and laid out 319 #define EVT_WIZARD_PAGE_SHOWN(id, fn) wx__DECLARE_WIZARDEVT(PAGE_SHOWN, id, fn) 320 321 #endif // wxUSE_WIZARDDLG 322 323 #endif // _WX_WIZARD_H_ 324