dlgshell.h

Go to the documentation of this file.

/**
 * \file mgui/dlgshell.h
 * \brief MGUI::DLGSHELL class definition
 *
 * \if NODOC
 * $Id: dlgshell.h_v 1.13 2004/11/09 18:24:27 mju Exp $
 *
 * $Log: dlgshell.h_v $
 * Revision 1.13  2004/11/09 18:24:27  mju
 * Add parm to getButtonPane so can put some buttons at left.
 *
 * Revision 1.12  2004/09/24 17:21:50  mju
 * Add isModal method.
 *
 * Revision 1.11  2004/06/04 20:58:51  dwilliss
 * added Tool style enum
 *
 * Revision 1.10  2004/03/16 17:54:53  mju
 * Don't allow further override of v_OnDestroy or v_GetMainPane.
 *
 * Revision 1.9  2003/11/19 14:33:26  mju
 * Add SetDeleteOnClose.
 *
 * Revision 1.8  2003/11/12 18:01:41  mju
 * Refine docs.
 *
 * Revision 1.7  2003/10/03 19:58:19  linux32build!build
 * Doxygen
 *
 * Revision 1.6  2003/09/15 13:49:32  fileserver!dwilliss
 * Doxygen
 *
 * Revision 1.5  2003/08/29 16:44:00  mju
 * Use mistring ref.
 *
 * Revision 1.4  2003/07/28 15:47:52  dwilliss
 * Added SetRootMargin() method
 *
 * Revision 1.3  2003/06/04 17:43:18  scowan
 * Fixed? for MFC.
 *
 * Revision 1.2  2003/05/28 17:51:08  mju
 * Add parm to ctor to specify title and eliminate virtual method to get name.
 *
 * Revision 1.1  2003/05/28 16:08:55  mju
 * Initial revision
 *
 * \endif
**/

#ifndef  INC_MGUI_DLGSHELL_H
#define  INC_MGUI_DLGSHELL_H

#ifndef  INC_MGUI_SHELL_H
#include <mgui/shell.h>
#endif

#ifndef  INC_MGUI_CTRL_H
#include <mgui/ctrl.h>
#endif


namespace MGUI {

//! Base class for general dialog support for both modeless and modal behavior.
//!
//! This class is available for both X and MFC with identical public and protected
//! interfaces.  The derived dialog implementation class must override the
//! v_CreateContent() method.  Most derived classes will also override v_OnApply
//! to perform the desired update of the external data when the user presses 'OK'
//! or 'Apply'.  When overriding the protected v_On...() virtual methods pay close
//! attention to when the corresponding base method is to be called to ensure correct
//! behavior.
class DLGSHELL : public MGUI::SHELL {
   public:

      //! Style settings, may be combined.
      enum STYLE {
         STYLE_Default =         0x00,    //!< Default style
         STYLE_Resizable =       0x01,    //!< Dialog is resizable
         STYLE_ContextHelp =     0x02,    //!< (Non-X) Include '?' icon in titlebar, cannot combine with AllowMinimize or AllowMaximize
         STYLE_AllowMinimize =   0x04,    //!< (Non-X) Include minimize box in titlebar, cannot combine with STYLE_ContextHelp
         STYLE_AllowMaximize =   0x08,    //!< (Non-X) Include maximize box in titlebar, cannot combine with STYLE_ContextHelp
         STYLE_CenterOnScreen =  0x10,    //!< Initially center dialog on monitor containing parent window
         STYLE_CenterOnMouse =   0x20,    //!< Initially center dialog on mouse cursor
         STYLE_DeleteOnClose =   0x40,    //!< Delete (destroy) dialog on closing, only used for modeless dialogs
         STYLE_ToolWindow =      0x80     //!< Window is a "tool controls" or "pallette" window. Gets a smaller title bar than normal windows
         };

      //! Standard dialog button selections, may be combined for some methods.
      enum BUTTONS {
         BUTTONS_Default =    0x00,       //!< Default buttons per dialog style
         BUTTON_OK =          0x01,
         BUTTON_Cancel =      0x02,
         BUTTON_Apply =       0x04,
         BUTTON_Close =       0x08,
         BUTTON_Help =        0x10
         };

      //! Destructor.
      virtual ~DLGSHELL (
         ) = 0;

      //! Cast to MDLGPARENT for use as parent for other dialogs.
      operator MDLGPARENT (
         ) const { return (GetDlgParent()); }

      //! Close the dialog if modeless.
      void Close (
         bool notify = true                     //!< Notify via OnClose()
         );

      //! Create 'modeless' dialog (without opening it).
      ERRVALUE CreateModeless (
         MDLGPARENT dlgparent,                  //!< Parent for dialog
         bool AllowMinimize = false             //!< (Non-X) Allow dialog to be "minimized"
         );

      //! Open dialog in modal state and wait for user to dismiss via OK/Cancel.
      //! @return 0 if OK, EUserCancel if Cancel, < 0 if error
      ERRVALUE DoModal (
         MDLGPARENT dlgparent                   //!< Parent for modal dialog
         );

      //! Determine if dialog is currently open.
      bool IsOpen (
         ) const;

      //! Open dialog if created in modeless state.
      ERRVALUE Open (
         );

      //! Set whether 'Apply' (if exists) button is enabled.
      void SetApplyEnabled (
         bool enabled = true
         ) { m_ApplyPB.SetEnabled(enabled); }

      //! Set to delete shell instance when closed (for modal dialogs).
      //! This allows the dialog to be created via 'new' without retaining the
      //! pointer instance.
      void SetDeleteOnClose (
         bool DeleteOnClose = true
         );

      //! Set whether 'OK' button (if exists) is enabled.
      void SetOkEnabled (
         bool enabled = true
         ) { m_OkPB.SetEnabled(enabled); }

   protected:

      //! Constructor, initializes only.
      DLGSHELL (
         const MISTRING& title,                 //!< Title string, can use TEXTID also
         HELPID HelpID,                         //!< Help ID, use HELPID__None if no 'help' available
         STYLE style = STYLE_Default            //!< Dialog style settings
         );

      //! Create standard button.
      //! @return Reference to button created (usually for alignment only).
      MGUI::CTRL_PUSHBUTTON& CreateButton (
         BUTTONS button,                        //!< Button to create
         const char *label = 0                  //!< Override for label, used for resource lookup
         );

      //! Create standard buttons at bottom of dialog.
      //! Default button labels will depend on the dialog style.
      //! Modal dialog buttons will be 'OK', 'Cancel' and 'Help'.
      //! Modeless dialog buttons will be 'OK', 'Cancel', 'Apply' and 'Help'.
      //! For modeless dialogs, pressing 'OK' has the same effect as pressing
      //! 'Apply' followed by 'Close'.
      void CreateButtons (
         BUTTONS buttons = BUTTONS_Default      //!< Buttons to create
         );

      //! Determine if dialog was open as modal.
      bool IsModal (
         ) const { return (m_IsModal); }

      //! Get pane to create buttons at bottom of dialog.
      //! This allows additional 'non-standard' buttons to be added to the dialog.
      //! This will create the pane if it has not been created already.
      MGUI::LAYOUT_PANE& GetButtonPane (
         bool AddSpace = true                   //!< Add space if creating so buttons placed at right
         );

      //! Send 'Cancel' notification to dialog.
      void NotifyCancel (
         ) { v_OnCancel(); }

      //! Send 'OK' notification to dialog.
      void NotifyOK (
         ) { v_OnOK(); }

      //! Set to ignore nonvisible items when doing layout.
      //! This must be called before CreateModeless() or DoModal() and is usually done in
      //! the subclass constructor.
      void SetIgnoreNonVisible (
         bool IgnoreNonVisible = true
         ) { m_IgnoreNonVisible = IgnoreNonVisible; return; }

      //! Set value to return from dialog.
      void SetReturnValue (
         int RetValue
         ) { m_RetValue = RetValue; }

      //! Set margin for root pane.
      //! This must be called before CreateModeless() or DoModal() and is usually done in
      //! the subclass constructor.
      void SetRootMargin (
         int RootMargin
         ) { m_RootMargin = RootMargin; }

      //! Set spacing for root pane.
      //! This must be called before CreateModeless() or DoModal() and is usually done in
      //! the subclass constructor.
      void SetRootSpacing (
         int RootSpacing
         ) { m_RootSpacing = RootSpacing; }

      //! Set dialog style.
      //! This must be called before CreateModeless() or DoModal() and not in
      //!   v_OnInitDialog() for proper behavior.
      void SetStyle (
         STYLE style
         ) { m_Style = style; }

      //! Force update of dialog layout.
      void UpdateLayout (
         )
      #ifdef X_NATIVE
         { }
      #endif
         ;

      // Overridables which may be called from derived classes.

      //! Called when 'Cancel' button is pressed.
      //! Derived class must call base class v_OnCancel() method AFTER performing its own processing
      //! to actually close the dialog.  In some cases the user may be given an opportunity to 
      //! verify that they intended to press the Cancel button.  If they elect not to cancel then
      //! the base class v_OnCancel() method should not be called.  This will cause the dialog to
      //! remain open and allow the user to retain the settings.
      //! Derived classes should generally declare this method as private.
      virtual void v_OnCancel ();

      //! Called when 'OK' button is pressed.
      //! Derived class must call base class v_OnOK() method AFTER performing its own processing
      //! to actually close the dialog.  If the dialog settings do not pass their associated
      //! validation test then an appropriate message should be displayed for the user and
      //! the base class v_OnOK() method should not be called.  This will cause the dialog to
      //! remain open and allow the user to correct the settings.  In addition, if an 'Apply'
      //! button has been created using the appropriate DLGSHELL methods then v_OnApply will
      //! be called before closing.
      //! Derived classes should generally declare this method as private.
      virtual void v_OnOK ();

   private:

      #ifndef GENERATING_DOXYGEN_OUTPUT
   #ifdef WIN32_MFC
      public:
      class MFCDLG;
      private:
      friend class MFCDLG;
      MFCDLG *m_pmfcdlg;
      UINT8 *m_TemplateBuf;
   #endif

      STYLE m_Style;
      bool m_IsModal;
      bool m_IgnoreNonVisible;
      ERRVALUE m_RetValue;
      int m_RootSpacing;
      int m_RootMargin;

      LAYOUT_PANE m_ButtonPane;
      CTRL_PUSHBUTTON_T<DLGSHELL> m_OkPB;
      CTRL_PUSHBUTTON_T<DLGSHELL> m_CancelPB;
      CTRL_PUSHBUTTON_T<DLGSHELL> m_ApplyPB;
      CTRL_PUSHBUTTON_T<DLGSHELL> m_HelpPB;

      //! Create actual dialog and root pane.
      ERRVALUE CreateDlg (
         MDLGPARENT dlgparent,                  //!< Parent for dialog, NULL for default
         bool modal = false,                    //!< Create as modal
         bool AllowMinimize = false
         );

   #ifdef WIN32_MFC           //!< XXXX Mike, please confirm the hack
      CTRL_STATUSBAR* GetStatusBar (
         ) { return (m_pStatusBar); }
   #endif
      
      void OnHelp ();
      void OnOpen () { v_OnOpen(); }

   #ifdef WIN32_MFC           //!< XXXX Mike, please confirm the hack
      void SetParentWindow (
         CWnd* cwnd
         ) { m_pWnd = cwnd;; }
   #endif
         
      DLGSHELL (const DLGSHELL&);
      DLGSHELL& operator= (const DLGSHELL&);

      // Overrides from SHELL.
   #ifdef WIN32_MFC
      MGUI::COMMAND_ROUTER* v_GetCmdRouter () const;
   #endif
      LAYOUT_PANE_MAIN& v_GetMainPane ();
      void v_Destroy ();

      #endif // GENERATING_DOXYGEN_OUTPUT

      // Overridables.

      //! Create dialog shell contents.
      //! Derived class MUST implement this.  Function must return 0 for success or an error code.
      //! This will be called by the dialog creation code and must not be called directly.
      //! This is normally overridden only by the specific dialog implementation and not by the
      //! code that actually uses that dialog implementation.  Implementation should call
      //! GetMainForm() or GetMainPane() to determine the form or pane to create the controls in.
      //! Note that you cannot override the dialog title in v_CreateContent, title must be set first.
      virtual ERRVALUE v_CreateContent () = 0;

      //! Called when user presses 'Apply' button.
      //! Will also be called by default v_OnOK implementation if 'Apply' button exists and is not disabled.
      virtual void v_OnApply ();

      //! Called when dialog gets closed.
      virtual void v_OnClose ();

      //! Called when user requests that shell be 'closed'.
      //! Default implementation simply calls Close().  May be overridden if different behavior desired.
      virtual void v_OnCloseRequest ();

      //! Called when dialog is destroyed.
      virtual void v_OnDestroy ();

      //! Called after dialog is actually opened.
      virtual void v_OnOpen ();

   };

DEFINE_ENUM_OPERATORS(DLGSHELL::BUTTONS);
DEFINE_ENUM_OPERATORS(DLGSHELL::STYLE);


}  // End namespace MGUI


#endif   // INC_MGUI_DLGSHELL_H

---