| 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 licence |
| 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 | #include "wx/bitmap.h" |
| 33 | |
| 34 | // Extended style to specify a help button |
| 35 | #define wxWIZARD_EX_HELPBUTTON 0x00000010 |
| 36 | |
| 37 | // forward declarations |
| 38 | class WXDLLEXPORT wxWizard; |
| 39 | |
| 40 | // ---------------------------------------------------------------------------- |
| 41 | // wxWizardPage is one of the wizards screen: it must know what are the |
| 42 | // following and preceding pages (which may be NULL for the first/last page). |
| 43 | // |
| 44 | // Other than GetNext/Prev() functions, wxWizardPage is just a panel and may be |
| 45 | // used as such (i.e. controls may be placed directly on it &c). |
| 46 | // ---------------------------------------------------------------------------- |
| 47 | |
| 48 | class WXDLLEXPORT wxWizardPage : public wxPanel |
| 49 | { |
| 50 | public: |
| 51 | wxWizardPage() { 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 | // common part of ctors: |
| 78 | void Init(); |
| 79 | |
| 80 | wxBitmap m_bitmap; |
| 81 | |
| 82 | private: |
| 83 | DECLARE_ABSTRACT_CLASS(wxWizardPage) |
| 84 | }; |
| 85 | |
| 86 | // ---------------------------------------------------------------------------- |
| 87 | // wxWizardPageSimple just returns the pointers given to the ctor and is useful |
| 88 | // to create a simple wizard where the order of pages never changes. |
| 89 | // |
| 90 | // OTOH, it is also possible to dynamicly decide which page to return (i.e. |
| 91 | // depending on the user's choices) as the wizard sample shows - in order to do |
| 92 | // this, you must derive from wxWizardPage directly. |
| 93 | // ---------------------------------------------------------------------------- |
| 94 | |
| 95 | class WXDLLEXPORT wxWizardPageSimple : public wxWizardPage |
| 96 | { |
| 97 | public: |
| 98 | wxWizardPageSimple() { Init(); } |
| 99 | |
| 100 | // ctor takes the previous and next pages |
| 101 | wxWizardPageSimple(wxWizard *parent, |
| 102 | wxWizardPage *prev = (wxWizardPage *)NULL, |
| 103 | wxWizardPage *next = (wxWizardPage *)NULL, |
| 104 | const wxBitmap& bitmap = wxNullBitmap, |
| 105 | const wxChar* resource = NULL) |
| 106 | { |
| 107 | Create(parent, prev, next, bitmap, resource); |
| 108 | } |
| 109 | |
| 110 | bool Create(wxWizard *parent = NULL, // let it be default ctor too |
| 111 | wxWizardPage *prev = (wxWizardPage *)NULL, |
| 112 | wxWizardPage *next = (wxWizardPage *)NULL, |
| 113 | const wxBitmap& bitmap = wxNullBitmap, |
| 114 | const wxChar* resource = NULL) |
| 115 | { |
| 116 | m_prev = prev; |
| 117 | m_next = next; |
| 118 | return wxWizardPage::Create(parent, bitmap, resource); |
| 119 | } |
| 120 | |
| 121 | // the pointers may be also set later - but before starting the wizard |
| 122 | void SetPrev(wxWizardPage *prev) { m_prev = prev; } |
| 123 | void SetNext(wxWizardPage *next) { m_next = next; } |
| 124 | |
| 125 | // a convenience function to make the pages follow each other |
| 126 | static void Chain(wxWizardPageSimple *first, wxWizardPageSimple *second) |
| 127 | { |
| 128 | wxCHECK_RET( first && second, |
| 129 | wxT("NULL passed to wxWizardPageSimple::Chain") ); |
| 130 | |
| 131 | first->SetNext(second); |
| 132 | second->SetPrev(first); |
| 133 | } |
| 134 | |
| 135 | // base class pure virtuals |
| 136 | virtual wxWizardPage *GetPrev() const; |
| 137 | virtual wxWizardPage *GetNext() const; |
| 138 | |
| 139 | private: |
| 140 | // common part of ctors: |
| 141 | void Init() |
| 142 | { |
| 143 | m_prev = m_next = NULL; |
| 144 | } |
| 145 | |
| 146 | // pointers are private, the derived classes shouldn't mess with them - |
| 147 | // just derive from wxWizardPage directly to implement different behaviour |
| 148 | wxWizardPage *m_prev, |
| 149 | *m_next; |
| 150 | |
| 151 | DECLARE_DYNAMIC_CLASS(wxWizardPageSimple) |
| 152 | DECLARE_NO_COPY_CLASS(wxWizardPageSimple) |
| 153 | }; |
| 154 | |
| 155 | // ---------------------------------------------------------------------------- |
| 156 | // wxWizard |
| 157 | // ---------------------------------------------------------------------------- |
| 158 | |
| 159 | class WXDLLEXPORT wxWizardBase : public wxDialog |
| 160 | { |
| 161 | public: |
| 162 | /* |
| 163 | The derived class (i.e. the real wxWizard) has a ctor and Create() |
| 164 | function taking the following arguments: |
| 165 | |
| 166 | wxWizard(wxWindow *parent, |
| 167 | int id = -1, |
| 168 | const wxString& title = wxEmptyString, |
| 169 | const wxBitmap& bitmap = wxNullBitmap, |
| 170 | const wxPoint& pos = wxDefaultPosition); |
| 171 | */ |
| 172 | |
| 173 | // executes the wizard starting from the given page, returns TRUE if it was |
| 174 | // successfully finished, FALSE if user cancelled it |
| 175 | virtual bool RunWizard(wxWizardPage *firstPage) = 0; |
| 176 | |
| 177 | // get the current page (NULL if RunWizard() isn't running) |
| 178 | virtual wxWizardPage *GetCurrentPage() const = 0; |
| 179 | |
| 180 | // set the min size which should be available for the pages: a |
| 181 | // wizard will take into account the size of the bitmap (if any) |
| 182 | // itself and will never be less than some predefined fixed size |
| 183 | virtual void SetPageSize(const wxSize& size) = 0; |
| 184 | |
| 185 | // get the size available for the page: the wizards are not resizeable, so |
| 186 | // this size doesn't change |
| 187 | virtual wxSize GetPageSize() const = 0; |
| 188 | |
| 189 | // set the best size for the wizard, i.e. make it big enough to contain all |
| 190 | // of the pages starting from the given one |
| 191 | // |
| 192 | // this function may be called several times and possible with different |
| 193 | // pages in which case it will only increase the page size if needed (this |
| 194 | // may be useful if not all pages are accessible from the first one by |
| 195 | // default) |
| 196 | virtual void FitToPage(const wxWizardPage *firstPage) = 0; |
| 197 | |
| 198 | // wxWizard should be created using "new wxWizard" now, not with Create() |
| 199 | #ifdef WXWIN_COMPATIBILITY_2_2 |
| 200 | static wxWizard *Create(wxWindow *parent, |
| 201 | int id = -1, |
| 202 | const wxString& title = wxEmptyString, |
| 203 | const wxBitmap& bitmap = wxNullBitmap, |
| 204 | const wxPoint& pos = wxDefaultPosition, |
| 205 | const wxSize& size = wxDefaultSize); |
| 206 | #endif // WXWIN_COMPATIBILITY_2_2 |
| 207 | |
| 208 | // the methods below may be overridden by the derived classes to provide |
| 209 | // custom logic for determining the pages order |
| 210 | |
| 211 | virtual bool HasNextPage(wxWizardPage *page) |
| 212 | { return page->GetNext() != NULL; } |
| 213 | |
| 214 | virtual bool HasPrevPage(wxWizardPage *page) |
| 215 | { return page->GetPrev() != NULL; } |
| 216 | }; |
| 217 | |
| 218 | // include the real class declaration |
| 219 | #include "wx/generic/wizard.h" |
| 220 | |
| 221 | // ---------------------------------------------------------------------------- |
| 222 | // wxWizardEvent class represents an event generated by the wizard: this event |
| 223 | // is first sent to the page itself and, if not processed there, goes up the |
| 224 | // window hierarchy as usual |
| 225 | // ---------------------------------------------------------------------------- |
| 226 | |
| 227 | class WXDLLEXPORT wxWizardEvent : public wxNotifyEvent |
| 228 | { |
| 229 | public: |
| 230 | wxWizardEvent(wxEventType type = wxEVT_NULL, |
| 231 | int id = -1, |
| 232 | bool direction = TRUE, |
| 233 | wxWizardPage* page = NULL); |
| 234 | |
| 235 | // for EVT_WIZARD_PAGE_CHANGING, return TRUE if we're going forward or |
| 236 | // FALSE otherwise and for EVT_WIZARD_PAGE_CHANGED return TRUE if we came |
| 237 | // from the previous page and FALSE if we returned from the next one |
| 238 | // (this function doesn't make sense for CANCEL events) |
| 239 | bool GetDirection() const { return m_direction; } |
| 240 | |
| 241 | wxWizardPage* GetPage() const { return m_page; } |
| 242 | |
| 243 | private: |
| 244 | bool m_direction; |
| 245 | wxWizardPage* m_page; |
| 246 | |
| 247 | DECLARE_DYNAMIC_CLASS(wxWizardEvent) |
| 248 | DECLARE_NO_COPY_CLASS(wxWizardEvent) |
| 249 | }; |
| 250 | |
| 251 | // ---------------------------------------------------------------------------- |
| 252 | // macros for handling wxWizardEvents |
| 253 | // ---------------------------------------------------------------------------- |
| 254 | |
| 255 | BEGIN_DECLARE_EVENT_TYPES() |
| 256 | DECLARE_EVENT_TYPE(wxEVT_WIZARD_PAGE_CHANGED, 900) |
| 257 | DECLARE_EVENT_TYPE(wxEVT_WIZARD_PAGE_CHANGING, 901) |
| 258 | DECLARE_EVENT_TYPE(wxEVT_WIZARD_CANCEL, 902) |
| 259 | DECLARE_EVENT_TYPE(wxEVT_WIZARD_HELP, 903) |
| 260 | DECLARE_EVENT_TYPE(wxEVT_WIZARD_FINISHED, 903) |
| 261 | END_DECLARE_EVENT_TYPES() |
| 262 | |
| 263 | typedef void (wxEvtHandler::*wxWizardEventFunction)(wxWizardEvent&); |
| 264 | |
| 265 | // notifies that the page has just been changed (can't be vetoed) |
| 266 | #define EVT_WIZARD_PAGE_CHANGED(id, fn) DECLARE_EVENT_TABLE_ENTRY(wxEVT_WIZARD_PAGE_CHANGED, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxWizardEventFunction) & fn, (wxObject *)NULL), |
| 267 | |
| 268 | // the user pressed "<Back" or "Next>" button and the page is going to be |
| 269 | // changed - unless the event handler vetoes the event |
| 270 | #define EVT_WIZARD_PAGE_CHANGING(id, fn) DECLARE_EVENT_TABLE_ENTRY(wxEVT_WIZARD_PAGE_CHANGING, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxWizardEventFunction) & fn, (wxObject *)NULL), |
| 271 | |
| 272 | // the user pressed "Cancel" button and the wizard is going to be dismissed - |
| 273 | // unless the event handler vetoes the event |
| 274 | #define EVT_WIZARD_CANCEL(id, fn) DECLARE_EVENT_TABLE_ENTRY(wxEVT_WIZARD_CANCEL, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxWizardEventFunction) & fn, (wxObject *)NULL), |
| 275 | |
| 276 | // the user pressed "Finish" button and the wizard is going to be dismissed - |
| 277 | #define EVT_WIZARD_FINISHED(id, fn) DECLARE_EVENT_TABLE_ENTRY(wxEVT_WIZARD_FINISHED, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxWizardEventFunction) & fn, (wxObject *)NULL), |
| 278 | |
| 279 | // the user pressed "Help" button |
| 280 | #define EVT_WIZARD_HELP(id, fn) DECLARE_EVENT_TABLE_ENTRY(wxEVT_WIZARD_HELP, id, -1, (wxObjectEventFunction) (wxEventFunction) (wxWizardEventFunction) & fn, (wxObject *)NULL), |
| 281 | |
| 282 | #endif // wxUSE_WIZARDDLG |
| 283 | |
| 284 | #endif // _WX_WIZARD_H_ |