dlgbase.h

Go to the documentation of this file.

/**
 * \file mgui/dlgbase.h
 * \brief MGUI::DLG_BASE class definition
 *
 * \if NODOC
 * $Id: dlgbase.h_v 1.21 2004/03/01 17:01:34 mju Exp $
 *
 * $Log: dlgbase.h_v $
 * Revision 1.21  2004/03/01 17:01:34  mju
 * Deprecate entire dlg_base class.
 *
 * Revision 1.20  2003/11/12 16:59:19  mju
 * Add doxygen deprecated tag.
 *
 * Revision 1.19  2003/10/27 17:22:25  scowan
 * Added deprecate groupkey defines.
 *
 * Revision 1.18  2003/10/03 19:58:19  linux32build!build
 * Doxygen
 *
 * Revision 1.17  2003/09/15 13:49:32  fileserver!dwilliss
 * Doxygen
 *
 * Revision 1.16  2003/03/05 16:00:42  mju
 * Use mainpane's widget instead of keeping own copy.
 *
 * Revision 1.15  2003/01/31 17:54:34  mju
 * Add SetReturnValue.
 *
 * Revision 1.14  2003/01/22 15:34:47  mju
 * GetHelpID no longer pure.
 *
 * Revision 1.13  2002/10/23 22:03:36  mju
 * Add m_Title so can set title before creating dialog.
 *
 * Revision 1.12  2002/10/23 15:40:04  mju
 * Add SetTitle from textid.
 *
 * Revision 1.11  2002/10/09 15:47:18  mju
 * Move to 'mgui' folder.
 *
 * Revision 1.10  2002/07/15 21:04:27  mju
 * Add ability to set root border.
 *
 * Revision 1.9  2002/05/30 15:25:13  mju
 * Remove deprecated typedef.
 *
 * Revision 1.7  2001/12/18 15:28:23  mju
 * Rename as DLG_BASE.
 *
 * Revision 1.6  2001/12/17 18:49:52  mju
 * Add implementations of UpdateLayout and GetCmdTarget for X.
 * Add protected SetStyle() method.
 *
 * Revision 1.5  2001/12/13 22:19:09  mju
 * Unify X and MFC interface.
 *
 * Revision 1.4  2001/12/13 17:00:13  mju
 * Don't use deprecated miwin header.
 *
 * Revision 1.3  2001/11/30 18:54:22  mju
 * Make On... methods public.
 *
 * Revision 1.2  2001/11/29 18:28:52  mju
 * Fix to compile for MFC.
 *
 * Revision 1.1  2001/11/28 22:11:45  mju
 * Initial revision
 * \endif
**/

#ifndef  INC_MGUI_DLGBASE_H
#define  INC_MGUI_DLGBASE_H

#if defined(DEPRECATE_ALL)
#error <mgui/dlgbase.h> is deprecated, use <mgui/dlgshell.h> instead
#endif

#if !defined(DEPRECATE_GROUPKEY)

#ifndef  INC_MI32_STDDEFNS_H
#include <mi32/stddefns.h>
#endif

#ifndef  INC_MGUI_COMMAND_H
#include <mgui/command.h>
#endif

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

#ifdef WIN32
#pragma warning (disable:4996)   // Disable warning about deprecated declaration within header
#endif

namespace MGUI {

//! \deprecated Replaced with MGUI::DLGSHELL
//! Base class for general dialog support for both modeless and modal behavior.
//!
//! This class is available for both X and MFC with a nearly identical public
//! and protected interfaces.  There are a few platform-specific methods for
//! use by the actual dialog implementation.  The derived dialog implementation
//! class must override the GetDialogName() and OnInitDialog()
//! methods.  Most derived classes will also override the OnApply to perform the
//! desired update of the external data when the user presses 'OK' or 'Apply'.
//! When overriding the On...() virtual methods pay close attention to when (or
//! whether) the corresponding base method is to be called to ensure correct behavior.
class DEPRECATED DLG_BASE {
   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
         };

      //! 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 ~DLG_BASE (
         ) = 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
         );

      //! Get MDLGPARENT for use as parent for child dialogs.
      MDLGPARENT GetDlgParent (
         ) const;

   #ifdef WIN32_MFC
      //! Get current window placement (MFC only).
      void GetWindowPlacement (
         WINDOWPLACEMENT& placement
         ) const;
   #endif

      //! Determine if dialog window has been created.
      bool IsCreated (
         ) const {
         #ifdef WIN32_MFC
            return (m_pmfcdlg != 0);
         #else
            return (m_MainPane.IsCreated());
         #endif
         }

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

      //! Called when user presses 'Apply' button.
      //! Will also be called when 'OK' button is pressed UNLESS 'Apply' button exists AND is disabled.
      //! Derived class must call base class OnApply() method BEFORE performing its own processing.
      virtual void OnApply (
         );

      //! Called when 'Cancel' button is pressed.
      //! Derived class must call base class OnCancel() method AFTER performing its own processing
      //! to properly 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 OnCancel() method should not be called.  This will cause the dialog to
      //! remain open and allow the user to retain the settings.
      virtual void OnCancel (
         );

      //! Called when dialog is closed.
      //! Derived class must call base class OnClose() method AFTER performing its own processing
      //! to properly close the dialog.  
      virtual void OnClose (
         );

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

      //! Called when 'OK' button is pressed.
      //! Derived class must call base class OnOK() method AFTER performing its own processing
      //! to properly 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 OnOK() method should not be called.  This will cause the dialog to
      //! remain open and allow the user to correct the settings.
      virtual void OnOK (
         );

      //! Called when dialog is opened after the dialog is actually "managed" and displayed.
      //! Derived class must call base class OnOpen() method BEFORE performing its own processing.
      virtual void OnOpen (
         );

      //! 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 whether 'OK' button (if exists) is enabled.
      void SetOkEnabled (
         bool enabled = true
         ) { m_OkPB.SetEnabled(enabled); }

      //! Set dialog title from UNICODE string.
      void SetTitle (
         const UNICODE *title
         );

      //! Set dialog title from TEXTID.
      void SetTitle (
         TEXTID textid
         );

   #ifdef WIN32_MFC
      //! Set window placement (MFC only).
      bool SetWindowPlacement (
         const WINDOWPLACEMENT& placement
         );
   #endif

   protected:

      //! Default constructor, initializes only.
      DLG_BASE (
         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
         );

      //! 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 (
         );

      //! Get "command router" for dialog.
      MGUI::COMMAND_ROUTER* GetCmdRouter (
         ) const
      #ifdef X_NATIVE
         { return (0); }
      #endif
         ;

      //! Get dialog HelpID.
      //! @return String for HelpID.
      virtual const char* GetDialogHelpID (
         ) const;

      //! Get dialog name for title resource.
      //! @return String for title resource lookup.
      virtual const char* GetDialogName (
         ) const = 0;

      //! Get main layout pane.
      MGUI::LAYOUT_PANE_MAIN& GetMainPane (
         );

      //! Create dialog 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 thus should 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.
      //! The implementation should call GetMainForm() or GetMainPane() to determine the form
      //! widget or pane to create the controls in.
      virtual ERRVALUE OnInitDialog (
         ) = 0;

      //! 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 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; }

   #ifdef WIN32_MFC
      //! Set status bar so dialog allows for in layout (MFC only).
      //! StatusBar must be created before OnInitDialog() returns.
      void SetStatusBar (
         CStatusBar *StatusBar                  //!< Pointer to status bar
         ) { m_pStatusBar = StatusBar; }
   #endif

   #ifdef WIN32_MFC
      //! Set status bar so dialog allows for in layout (MFC only).
      //! StatusBar must be created before OnInitDialog() returns.
      void SetStatusBar (
         MGUI::CTRL_STATUSBAR& StatusBar
         ) { m_pStatusBar = &StatusBar.GetStatusBar(); }
   #endif

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

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

   private:
   #ifndef GENERATING_DOXYGEN_OUTPUT

   #ifdef WIN32_MFC
      public:
      class MFCDLG;
      private:
      friend class MFCDLG;
      MFCDLG *m_pmfcdlg;
      CStatusBar *m_pStatusBar;
      UINT8 *m_TemplateBuf;
   #endif

   #ifdef X_NATIVE
      Widget XXXdelete;
      LAYOUT_PANE_MAIN m_MainPane;
   #endif

      STYLE m_Style;
      bool m_IsModal;
      bool m_IgnoreNonVisible;
      ERRVALUE m_RetValue;
      int m_RootSpacing;
      MISTRING m_Title;

      LAYOUT_PANE m_ButtonPane;
      CTRL_PUSHBUTTON_T<DLG_BASE> m_OkPB;
      CTRL_PUSHBUTTON_T<DLG_BASE> m_CancelPB;
      CTRL_PUSHBUTTON_T<DLG_BASE> m_ApplyPB;
      CTRL_PUSHBUTTON_T<DLG_BASE> 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
         );

      void OnHelp ();

   #ifdef X_NATIVE
      static void CB_Close (Widget, DLG_BASE*, void*);
   #endif

      DLG_BASE (const DLG_BASE&);
      DLG_BASE& operator= (const DLG_BASE&);
   #endif // GENERATING_DOXYGEN_OUTPUT
   };

DEFINE_ENUM_OPERATORS(DLG_BASE::BUTTONS);
DEFINE_ENUM_OPERATORS(DLG_BASE::STYLE);

}  // End namespace MGUI

#ifdef WIN32
#pragma warning (default:4996)   // Restore warning about deprecated declaration
#endif

#endif   // !defined(DEPRECATE_GROUPKEY)
#endif   // INC_MGUI_DLGBASE_H

---