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