Main Page Class Hierarchy Alphabetical List Compound List File List Compound Members

FXWizardDialog.h

Go to the documentation of this file.
00001 /*******************************************************************************
00002 * Copyright (C) 2001,2002 by H. J. Daniel III. All Rights Reserved.            *
00003 ********************************************************************************
00004 * This library is free software; you can redistribute it and/or                *
00005 * modify it under the terms of the GNU Lesser General Public                   *
00006 * License as published by the Free Software Foundation; either                 *
00007 * version 2.1 of the License, or (at your option) any later version.           *
00008 *                                                                              *
00009 * This library is distributed in the hope that it will be useful,              *
00010 * but WITHOUT ANY WARRANTY; without even the implied warranty of               *
00011 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU            *
00012 * Lesser General Public License for more details.                              *
00013 *                                                                              *
00014 * You should have received a copy of the GNU Lesser General Public             *
00015 * License along with this library; if not, write to the Free Software          *
00016 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA.   *
00017 *******************************************************************************/
00018 #ifndef FXWIZARDDIALOG_H
00019 #define FXWIZARDDIALOG_H
00020 
00021 #ifndef FXDIALOGBOX_H
00022 #include <fox/FXDialogBox.h>
00023 using namespace FX;
00024 #endif
00025 namespace FXEX {
00026 class FXWizardPage;
00027 
00028 /**
00029  * When used in describing the default FXWizardDialog image, it sets the default 
00030  * image as having NO image. When used in describing a FXWizardPage, it sets
00031  * the page as having NO image.  NULL means use default image.
00032  */
00033 #define FXWizardEmptyImage ((FXImage*) -1)
00034 
00035 ///  The following are some predefined placement types, for FXWizardDialog
00036 #define FXPlacementDefault    FXPoint(-1,-1)   /// Place it at the default size and location
00037 #define FXPlacementVisible    FXPoint(-2,-2)   /// Place window to be fully visible
00038 #define FXPlacementCursor     FXPoint(-3,-3)   /// Place it under the cursor position
00039 #define FXPlacementOwner      FXPoint(-4,-4)   /// Place it centered on its owner
00040 #define FXPlacementScreen     FXPoint(-5,-5)   /// Place it centered on the screen
00041 #define FXPlacementMaximized  FXPoint(-6,-6)   /// Place it maximized to the screen size
00042 
00043 /**
00044  *  FXWizardDialog : Adds support for Windows like wizard dialogs.
00045  *
00046  *  FXWizardDialog is the central class for implementing 'wizard-like' dialogs. These
00047  *  dialogs are mostly familiar to Windows users and are nothing else but a 
00048  *  sequence of 'pages' each of them displayed inside a dialog which has the 
00049  *  buttons to pass to the next (and previous) pages.
00050  *  
00051  *  The wizards are typically used to decompose a complex dialog into several 
00052  *  simple steps and are mainly useful to the novice users, hence it is 
00053  *  important to keep them as simple as possible.
00054  *  
00055  *  To show a wizard dialog, you must first create an object of FXWizardDialog class.
00056  *  Then you should add all pages you want the wizard to show and then call 
00057  *  FXWizardDialog::run.
00058  */
00059 class FXAPI FXWizardDialog : public FXDialogBox {
00060   FXDECLARE(FXWizardDialog);
00061 
00062 private:
00063   // the global image to display with the wizard pages. This is the image that will
00064   // be displayed if the current pages' image is set to FXNullImage. If the page
00065   // does not want any image displayed it should use FXEmptyImage.
00066   FXImage *wizImage;
00067 
00068   // the current page or NULL
00069   FXWizardPage *page;       
00070 
00071   // wizard dimensions
00072   FXuint width;       // the size of the wizard itself
00073   FXuint height;      // (total width is width + m_x)
00074 
00075   // the page size requested by user
00076   FXSize sizePage;
00077 
00078   // the dialog position from the ctor
00079   FXPoint posWizard;
00080 
00081   // wizard controls and contents
00082   FXButton *btnPrev;     // the "<Back" button
00083   FXButton *btnNext;     // the "Next>" or "Finish" button
00084   FXButton *btnCancel;   // the "Cancel" button
00085   FXHorizontalSeparator *separator;  //the separator
00086   FXImageFrame *wizImageFrame; // frame around image
00087 
00088 private:
00089   // Moves the upper right hand corner of all of the FXWizardPage's to a
00090   // specified location in the FXWizard's coordinate space.
00091   void movePages(FXuint x, FXuint y);
00092 
00093   // Displays the wizard with the currently active FXWizardPage.
00094   FXbool showPage(FXWizardPage *pg, FXbool goingForward);
00095   
00096   // Construct the default controls used in the wizard
00097   void constructControls();
00098   
00099   // Was the dialog really created?
00100   bool wasCreated() const { return btnPrev != NULL; }
00101 
00102   // Routine to find the minimum size required to fully display all
00103   // the pages.
00104   FXSize getPageSizes();
00105 
00106   // Routine to set the minimum size required to fully display all
00107   // the pages.
00108   void setPageSizes(FXuint w, FXuint h);
00109   
00110   // Finds the maximum size required by all of the page images.
00111   FXSize getImageSizes();
00112 
00113 protected:
00114   FXWizardDialog(){}  //no default constructor allowed.
00115 
00116 public:
00117   enum {
00118     /// This message is sent to the wizard when the <PREV> button is selected
00119     ID_WIZARD_PREV=FXDialogBox::ID_LAST,
00120     /// This message is sent to the wizard when the <NEXT> button is selected
00121     ID_WIZARD_NEXT,
00122     /*! This message is sent to the wizard when the <CANCEL> button is selected,
00123      * and, if the wizard contains a title bar, when the user selects [X].
00124     */
00125     ID_WIZARD_CANCEL,
00126     /// This message is sent to the wizard when the <HELP> button is selected
00127     ID_WIZARD_HELP,
00128     ID_LAST
00129     };
00130 
00131 public:
00132   // these should not be overridden.
00133 
00134   /// Called when the <NEXT>, <PREV>, and <FINISH>(last page only) is pressed.
00135   long onPrevOrNext(FXObject*,FXSelector,void* ptr);
00136 
00137   /// Called when the <CANCEL> or [X](if toolbar is active) is pressed.
00138   long onCancel(FXObject*,FXSelector,void* ptr);
00139 
00140   /// Called when the <HELP> button is pressed.
00141   long onHelp(FXObject*,FXSelector,void* ptr);
00142 
00143 public:
00144   /*! Holds an array of FXWizard pages. This is the only thing that effects 
00145    * portablility(it uses template classes). Therefore future versions may replace 
00146    * this with a more portable method. But for now it works :)
00147    * This should also be made private and accessed through member functions but
00148    * i'll save that for later.
00149   */
00150   FXArray<FXWizardPage*> pageArray;
00151 
00152 public:
00153   /*! Construct a free-floating FXWizardDialog dialog. This is the construtor to 
00154    * use if creating a dialog-based FXWizardDialog application.
00155    * \param app The application object.
00156    * \param name The name of the wizard which will be display on the title bar
00157    * \param image The default image to display on the left of the pages. 
00158    *              This should be a user image or one the @link 
00159    *              DefaultImageGroup default image types@endlink.
00160    * \param position A FXPoint location on the display where the wizard will
00161    *                 will be displayed. The value can be an explicit FXPoint
00162    *                 or one of the @link DefaultPlacementGroup default 
00163    *                 placement types@endlink.
00164    * \param padding The padding between the different components in the FXWizardDialog.
00165   */
00166   FXWizardDialog(FXApp *app,const FXString& name,FXImage* image=NULL,FXPoint position=FXPlacementScreen,FXint padding=DEFAULT_PAD);
00167 
00168   /*! Construct a model FXWizardDialog dialog which will always float over the owner window.
00169    * \param owner The parent window to which the wizard is owned by.
00170    * \param name The name of the wizard which will be display on the title bar
00171    * \param image The default image to display on the left of the pages. 
00172    *              This should be a user image or one the @link 
00173    *              DefaultImageGroup default image types@endlink.
00174    * \param position A FXPoint location on the display where the wizard will
00175    *                 will be displayed. The value can be an explicit FXPoint
00176    *                 or one of the @link DefaultPlacementGroup default 
00177    *                 placement types@endlink.
00178    * \param padding The padding between the different components in the FXWizardDialog.
00179   */
00180   FXWizardDialog(FXWindow *owner,const FXString& name,FXImage* image=NULL,FXPoint position=FXPlacementScreen,FXint padding=DEFAULT_PAD);
00181 
00182   /// Create the server side resources for the wizard.
00183   void create();
00184   
00185   /** Executes the wizard starting from the given page, returns TRUE if it 
00186    *  was successfully finished or FALSE if user cancelled it. The first Page
00187    *  can not be NULL.
00188   */
00189   int run(FXWizardPage* startPage);
00190 
00191   /** Moves the wizard window to a specific location. This can be called anytime 
00192    *  before FXWizardDialog::run()
00193   */
00194   void move(FXuint x, FXuint y);
00195 
00196   /** Moves the wizard window to a specific location. This can be called anytime 
00197    *  before FXWizardDialog::run()
00198   */
00199   void move(FXPoint pos);
00200 
00201   /** A convenience function to make the pages follow each other. A NULL 
00202    *  value should terminate the list.
00203    */
00204   static void chain(FXWizardPage *first, ...);
00205 
00206   /// dtor
00207   virtual ~FXWizardDialog();
00208   };
00209 
00210 } // namespace FXEX
00211 #endif // FXWIZARDDIALOG_H