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