include/wx/modalhook.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/modalhook.h
   3 // Purpose:     Allows to hook into showing modal dialogs.
   4 // Author:      Vadim Zeitlin
   5 // Created:     2013-05-19
   6 // Copyright:   (c) 2013 Vadim Zeitlin <vadim@wxwidgets.org>
   7 // Licence:     wxWindows licence
   8 ///////////////////////////////////////////////////////////////////////////////
   9
  10 #ifndef _WX_MODALHOOK_H_
  11 #define _WX_MODALHOOK_H_
  12
  13 #include "wx/vector.h"
  14
  15 class WXDLLIMPEXP_FWD_CORE wxDialog;
  16
  17 // ----------------------------------------------------------------------------
  18 // Class allowing to be notified about any modal dialog calls.
  19 // ----------------------------------------------------------------------------
  20
  21 // To be notified about entering and exiting modal dialogs and possibly to
  22 // replace them with something else (e.g. just return a predefined value for
  23 // testing), define an object of this class, override its Enter() and
  24 // possibly Exit() methods and call Register() on it.
  25 class WXDLLIMPEXP_CORE wxModalDialogHook
  26 {
  27 public:
  28     // Default ctor doesn't do anything, call Register() to activate the hook.
  29     wxModalDialogHook() { }
  30
  31     // Dtor unregisters the hook if it had been registered.
  32     virtual ~wxModalDialogHook() { DoUnregister(); }
  33
  34     // Register this hook as being active, i.e. its Enter() and Exit() methods
  35     // will be called.
  36     //
  37     // Notice that the order of registration matters: the last hook registered
  38     // is called first, and if its Enter() returns something != wxID_NONE, the
  39     // subsequent hooks are skipped.
  40     void Register();
  41
  42     // Unregister this hook. Notice that is done automatically from the dtor.
  43     void Unregister();
  44
  45     // Called from wxWidgets code before showing any modal dialogs and calls
  46     // Enter() for every registered hook.
  47     static int CallEnter(wxDialog* dialog);
  48
  49     // Called from wxWidgets code after dismissing the dialog and calls Exit()
  50     // for every registered hook.
  51     static void CallExit(wxDialog* dialog);
  52
  53 protected:
  54     // Called by wxWidgets before showing any modal dialogs, override this to
  55     // be notified about this and return anything but wxID_NONE to skip showing
  56     // the modal dialog entirely and just return the specified result.
  57     virtual int Enter(wxDialog* dialog) = 0;
  58
  59     // Called by wxWidgets after dismissing the modal dialog. Notice that it
  60     // won't be called if Enter() hadn't been.
  61     virtual void Exit(wxDialog* WXUNUSED(dialog)) { }
  62
  63 private:
  64     // Unregister the given hook, return true if it was done or false if the
  65     // hook wasn't found.
  66     bool DoUnregister();
  67
  68     // All the hooks in reverse registration order (i.e. in call order).
  69     typedef wxVector<wxModalDialogHook*> Hooks;
  70     static Hooks ms_hooks;
  71
  72     wxDECLARE_NO_COPY_CLASS(wxModalDialogHook);
  73 };
  74
  75 // Helper object used by WX_MODAL_DIALOG_HOOK below to ensure that CallExit()
  76 // is called on scope exit.
  77 class wxModalDialogHookExitGuard
  78 {
  79 public:
  80     wxEXPLICIT wxModalDialogHookExitGuard(wxDialog* dialog)
  81         : m_dialog(dialog)
  82     {
  83     }
  84
  85     ~wxModalDialogHookExitGuard()
  86     {
  87         wxModalDialogHook::CallExit(m_dialog);
  88     }
  89
  90 private:
  91     wxDialog* const m_dialog;
  92
  93     wxDECLARE_NO_COPY_CLASS(wxModalDialogHookExitGuard);
  94 };
  95
  96 // This macro needs to be used at the top of every implementation of
  97 // ShowModal() in order for wxModalDialogHook to work.
  98 #define WX_HOOK_MODAL_DIALOG()                                                \
  99     const int modalDialogHookRC = wxModalDialogHook::CallEnter(this);         \
 100     if ( modalDialogHookRC != wxID_NONE )                                     \
 101         return modalDialogHookRC;                                             \
 102     wxModalDialogHookExitGuard modalDialogHookExit(this)
 103
 104 #endif // _WX_MODALHOOK_H_