midialog.h

Go to the documentation of this file.

/**
 * \file midialog.h <mi32/midialog.h>
 * \brief MIDIALOG class definition
 *
 * \if NODOC
 * $Id: midialog.h_v 1.10 2003/09/15 13:49:56 fileserver!dwilliss Exp $
 *
 * $Log: midialog.h_v $
 * Revision 1.10  2003/09/15 13:49:56  fileserver!dwilliss
 * Doxygen
 *
 * Revision 1.9  2000/10/05 15:42:43  mju
 * WIN32-native.
 *
 * Revision 1.8  2000/09/14 17:18:57  mju
 * Make SetApplySensitive const.
 *
 * Revision 1.7  2000/08/02 15:40:06  mju
 * Add OnOK/OnCancel and make work like MFC.
 *
 * Revision 1.6  2000/07/31 15:23:42  mju
 * Change interface to use OnInitDialog() for creation and eliminate base hierarchy.
 *
 * Revision 1.5  2000/07/25 17:35:38  mju
 * Add notify parm to Close().
 *
 * Revision 1.4  2000/07/24 21:03:19  mju
 * Add AddForm().
 *
 * Revision 1.3  2000/07/24 20:11:41  mju
 * Make SetupButton... non-const.
 *
 * Revision 1.2  2000/07/24 15:03:37  mju
 * Add IsCreated().
 *
 * Revision 1.1  2000/07/21 21:12:20  mju
 * Initial revision
 *
 * \endif
**/

#ifndef  INC_MI32_MIDIALOG_H
#define  INC_MI32_MIDIALOG_H

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

#ifndef  INC_MI32_XDEFNS_H
#include <mi32/xdefns.h>
#endif

struct BUTTONITEM;


//! Base class for general dialog support for both modeless and modal behavior.
//!
//! The derived class must override the GetDialogName(), GetDialogHelpID() 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 if)
//! the corresponding superclass method is to be called.
class MIDIALOG {
public:

   // ENUMERATIONS

   enum BUTTONS {
      BUTTONS_Default =    0x00,       //!< Default buttons per dialog style
      BUTTON_OK =          0x01,
      BUTTON_Cancel =      0x02,
      BUTTON_Apply =       0x04,
      BUTTON_Close =       0x08
      };

   // CONSTRUCTION / DESTRUCTION

   //! Default constructor, initialize only.
   MIDIALOG (
      );

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

   // METHODS

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

   //! 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 has been created.
   bool IsCreated (
      ) const {
      return (m_form != 0);
      }

   //! Determine if dialog is currently open.
   bool IsOpen (
      ) const {
      #ifndef WIN32_NATIVE
         return (m_form != 0 && XtIsManaged(m_form));
      #else
         return (false);
      #endif
      }

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

   //! Set "Apply" (if exists) button sensitivity.
   void SetApplySensitive (
      bool sensitive
      ) const {
      #ifndef WIN32_NATIVE
         MxSetSensitive(m_ApplyPB,sensitive);
      #endif
      return;
      }

protected:

   // VIRTUAL METHODS

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

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

   //! Called when user presses "Apply" button.
   //! Will also be called when "OK" button is pressed if have "Apply" button
   //! and "Apply" is not disabled.
   //! Derived class must call superclass OnApply() method BEFORE
   //! performing its own processing.
   virtual void OnApply (
      );

   //! Called when "Cancel" button is pressed.
   //!
   //! Derived class must call superclass 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 superclass 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.
   virtual void OnClose (
      );

   //! 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.
   virtual ERRVALUE OnInitDialog (
      Widget form                            //!< Form to create contents in
      ) = 0;

   //! Called when "OK" button is pressed.
   //!
   //! Derived class must call superclass 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 superclass 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 superclass OnOpen() method BEFORE
   //! performing its own processing.
   virtual void OnOpen (
      );

   // METHODS

   //! Create buttons at bottom of form.
   //!
   //! @return Separator Widget attached above buttons
   Widget CreateButtonRow (
      const BUTTONITEM* ButtonItems,
      void *cbdata = 0,
      void *userdata = 0
      );

   //! Create standard buttons at bottom of form.
   //! 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".
   //!
   //! @return Separator Widget attached above buttons
   Widget CreateButtons (
      BUTTONS buttons = BUTTONS_Default      //!< Buttons to create
      );

   //! Get outermost Form widget.
   Widget GetMainForm (
      ) const {
      return (m_form);
      }

   //! Setup BUTTONITEM for "Apply" button.
   void SetupButtonApply (
      BUTTONITEM& bi
      );

   //! Setup BUTTONITEM for Cancel button.
   void SetupButtonCancel (
      BUTTONITEM& bi
      );

   //! Setup BUTTONITEM for Close button.
   void SetupButtonClose (
      BUTTONITEM& bi
      );

   //! Setup BUTTONITEM for "OK" button.
   void SetupButtonOK (
      BUTTONITEM& bi
      );

private:
   #ifndef GENERATING_DOXYGEN_OUTPUT
   //! MEMBERS
   Widget m_form;
   Widget m_ApplyPB;
   bool m_IsModal;
   ERRVALUE m_RetValue;

   // METHODS

   //! Create FormDialog widget.
   ERRVALUE CreateDialog (
      MDLGPARENT dlgparent,                  //!< Parent for dialog, NULL for TopLevel
      bool modal = false                     //!< Create as modal
      );

   static void CB_Apply (Widget, MIDIALOG*, void*);
   static void CB_Cancel (Widget, MIDIALOG*, void*);
   static void CB_Destroy (Widget, MIDIALOG*, void*);
   static void CB_OK (Widget, MIDIALOG*, void*);

   MXXTCB_ADD(MIDIALOG);
   MXXTCB_REMOVE(MIDIALOG);

   // UNIMPLEMENTED / UNSUPPORTED

   MIDIALOG (
      const MIDIALOG& rhs
      );

   MIDIALOG& operator= (
      const MIDIALOG& rhs
      );
   #endif // GENERATING_DOXYGEN_OUTPUT

   };

DEFINE_ENUM_OPERATORS(MIDIALOG::BUTTONS);


#endif   //!< INC_MI32_MIDIALOG_H

---