// Copyright (c) 1997-1999 Microsoft Corporation
// 
// Dialog class
// 
// 10-15-97 sburns



#ifndef DIALOG_HPP_INCLUDED
#define DIALOG_HPP_INCLUDED



// Wraps a Windows dialog box, cracks and demuxes the dialog messages, and
// provides a mechanism for tracking the control IDs that have been touched
// over a given period.  Also provides what-is help.
//
// May only be used as a base class.

class Dialog
{
   public:

   // can't use an enum 'cause the type needs to be DWORD
   #define NO_HELP (static_cast<DWORD>(-1))
      
   // Executes the dialog modally via the Win DialogBox API.  Blocks until the
   // Win EndDialog API is called; returns the value passed to EndDialog.
   // Derived classes must call EndDialog in their message processing to
   // terminate the execution of the dialog.
   //
   // parent - handle to the parent window, which will be disabled during
   // the execution of the dialog.

   INT_PTR
   ModalExecute(HWND parent);

   INT_PTR
   ModalExecute(const Dialog& parent);

   // Executes the dialog box modelessly, returning immediately.  Derived
   // classes should call EndModelessExecution to close a Dialog executing
   // modelessly, or, destroy the Dialog instance.
   // 
   // Example:
   // 
   // MyFooDialog* dlg = new MyFooDialog(....);
   // dlg->ModlessExecute();
   // 
   // // ... later
   // 
   // dlg->EndModelessExecution();
   // 
   // // or just:
   // 
   // delete dlg;
   // 
   // parent - handle to the parent window of this dialog, for establishing
   // z-order.

   void
   ModelessExecute(HWND parent);

   void
   ModelessExecute(const Dialog& parent);

   // Terminates the modeless execution of a dialog that has been started
   // with ModalExecute.  It is illegal to call this method before calling
   // ModalExecute.

   void
   EndModelessExecution();

   // Returns the window handle of the dialog.  This method is only valid
   // after the window has been created and initialized by receiving
   // WM_INITDIALOG (which will be the case before any virtual message
   // handling functions are invoked).

   HWND
   GetHWND() const;

   // Returns the resource ID with which this instance was created.

   unsigned
   GetResID() const;

   // Returns a pointer to the Dialog instance that has been previously
   // stashed in the DWL_USER portion of the window structure.  This method is
   // only valid after the window has been created and initialized by
   // receiving WM_INITDIALOG (which will be the case before any virtual
   // message handling functions are invoked).
   // 
   // dialog - handle to initialized dialog window.

   static
   Dialog*
   GetInstance(HWND dialog);

   protected:

   // Constructs a new instance.  Declared protected so that this class
   // only functions as base class
   // 
   // resID - resource identifier of the dialog template resource.
   // 
   // helpMap - array mapping dialog control IDs to context help IDs.  The
   // array must be in the following form:
   // {
   //    controlID1, helpID1,
   //    controlID2, helpID2,
   //    controlIDn, helpIDn,
   //    0, 0
   // }
   // 
   // To indicate that a control does not have help, the value of its
   // corresponding help ID should be NO_HELP.  This array is copied
   // by the constructor.

   Dialog(
      unsigned    resID,
      const DWORD helpMap[]);

   // Destroys an instance.  If the ModelessExecute method has been called,
   // and the EndModlessExecution method has not yet been called,
   // EndModelessExecution is called.

   virtual ~Dialog();

   // Resets the control ID change map.

   void
   ClearChanges();

   // Marks a control ID as changed.  Derived classes should call this from
   // their processing of OnCommand or OnNotify as appropriate to indicate
   // that a control has changed state.  This is useful for keeping track of
   // the fields in a database that need to be changed, etc.
   //
   // controlResID - the resource ID of the control that changed.

   void
   SetChanged(UINT_PTR controlResID);

   // Queries the control ID change map, returning true if the specified
   // control ID was previously marked as changed (with SetChanged), false
   // if not.
   //
   // controlResID - the resource ID of the control that changed.

   bool
   WasChanged(UINT_PTR controlResID) const;

   // Returns true if SetChanged was called for any control on the dialog,
   // false if not.

   bool
   WasChanged() const;

   // (For debugging) dumps the state of the control ID change map using
   // OutputDebugString.  For non-debug builds, a no-op.

   void
   DumpChangeMap() const;

   // Invoked upon receipt of WM_DESTROY.  The default implementation does
   // nothing.

   virtual
   void
   OnDestroy();

   // Invoked upon receipt of WM_COMMAND.  Derived class' implementation
   // should return true they handle the message, false if not.  The default
   // implementation returns false.
   //
   // windowFrom - the HWND of the child window (control) that originated the
   // message.
   // 
   // controlIDFrom - The resource ID of the child window corresponding to the
   // window indicated in the windowFrom parameter.   
   // 
   // code - the notification code.

   virtual
   bool
   OnCommand(
      HWND        windowFrom,
      unsigned    controlIdFrom,
      unsigned    code);

   // Invoked upon receipt of WM_INITDIALOG, after having set things up such
   // that GetHWND and GetInstance will work correctly.  The default
   // implementation does nothing.

   virtual
   void
   OnInit();

   // Invoked upon receipt of any window message that is not dispatched to
   // other member functions of this class, including user-defined messages.
   // Derived class' implementation should return true they handle the
   // message, false if not.  The default implementation returns false.
   // 
   // message - the message code passed to the dialog window.
   // 
   // wparam - the WPARAM parameter accompanying the message.
   // 
   // lparam - the LPARAM parameter accompanying the message.
   
   virtual
   bool
   OnMessage(
      UINT     message,
      WPARAM   wparam,
      LPARAM   lparam);

   // Invoked upon receipt of WM_NOTIFY.  Derived class' implementation should
   // return true they handle the message, false if not.  The default
   // implementation returns false.
   //
   // windowFrom - the HWND of the child window (control) that originated the
   // message.
   // 
   // controlIDFrom - The resource ID of the child window corresponding to the
   // window indicated in the windowFrom parameter.   
   // 
   // code - the notification code.
   //
   // lparam - the LPARAM parameter of the WM_NOTIFY message, which may,
   // depending on the window that originated the message, be a pointer to a
   // structure indicating other parameters to the notification.

   virtual
   bool
   OnNotify(
      HWND     windowFrom,
      UINT_PTR controlIDFrom,
      UINT     code,
      LPARAM   lparam);

   // Stores the window handle of the dialog in this instance, so that it can
   // be later retrieved by GetHWND.  This is typically called by derived
   // classes that are doing their own processing of WM_INITDIALOG.  This
   // function may be legally called only once in the lifetime of any Dialog
   // instance.
   // 
   // window - handle to the dialog window.

   void
   SetHWND(HWND window);

   // The window handle of corresponding to this instance.  Only valid after
   // WM_INITDIALOG has been received.

   HWND hwnd;

   // accessible to PropertyPage, etc.

   static
   INT_PTR CALLBACK
   dialogProc(HWND dialog, UINT message, WPARAM wparam, LPARAM lparam);

   private:

   // not implemented: no copying allowed
   Dialog(const Dialog&);
   const Dialog& operator=(const Dialog&);

   typedef
      std::map<
         UINT_PTR,
         bool,
         std::less<UINT_PTR>,
         Burnslib::Heap::Allocator<bool> >
      ChangeMap;

   // 'mutable' required for non-const map<>::operator[].  
   mutable ChangeMap changemap;
   DWORD*            helpMap;
   bool              isEnded;
   bool              isModeless;
   unsigned          resID;
};



#endif   // DIALOG_HPP_INCLUDED