interface/wx/modalhook.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/modalhook.h
   3 // Purpose:     Public interface of wxModalDialogHook class.
   4 // Author:      Vadim Zeitlin
   5 // Copyright:   (c) 2013 Vadim Zeitlin <vadim@wxwidgets.org>
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     Allows to intercept all modal dialog calls.
  11
  12     This class can be used to hook into normal modal dialog handling for some
  13     special needs. One of the most common use cases is for testing: as
  14     automatic tests can't continue if a modal dialog is shown while they run,
  15     this class can be used to avoid showing the modal dialogs during unattended
  16     execution. wxModalDialogHook can also be used for disabling some background
  17     operation while a modal dialog is shown.
  18
  19     To install a modal dialog hook, you need to derive your own class from this
  20     one and implement its pure virtual Enter() method. Then simply create an
  21     object of your class and call Register() on it to start receiving calls to
  22     your overridden Enter() (and possibly Exit()) methods:
  23     @code
  24         class MyModalDialogHook : public wxModalDialogHook
  25         {
  26         protected:
  27             virtual int Enter(wxDialog* dialog)
  28             {
  29                 // Just for demonstration purposes, intercept all uses of
  30                 // wxFileDialog. Notice that this doesn't provide any real
  31                 // sandboxing, of course, the program can still read and write
  32                 // files by not using wxFileDialog to ask the user for their
  33                 // names.
  34                 if ( wxDynamicCast(dialog, wxFileDialog) )
  35                 {
  36                     wxLogError("Access to file system disallowed.");
  37
  38                     // Skip showing the file dialog entirely.
  39                     return wxID_CANCEL;
  40                 }
  41
  42                 m_lastEnter = wxDateTime::Now();
  43
  44                 // Allow the dialog to be shown as usual.
  45                 return wxID_NONE;
  46             }
  47
  48             virtual void Exit(wxDialog* dialog)
  49             {
  50                 // Again, just for demonstration purposes, show how long did
  51                 // the user take to dismiss the dialog. Notice that we
  52                 // shouldn't use wxLogMessage() here as this would result in
  53                 // another modal dialog call and hence infinite recursion. In
  54                 // general, the hooks should be as unintrusive as possible.
  55                 wxLogDebug("%s dialog took %s to be dismissed",
  56                            dialog->GetClassInfo()->GetClassName(),
  57                            (wxDateTime::Now() - m_lastEnter).Format());
  58             }
  59         };
  60
  61         class MyApp : public wxApp
  62         {
  63         public:
  64             virtual bool OnInit()
  65             {
  66                 ...
  67                 m_myHook.Register();
  68                 ...
  69             }
  70
  71         private:
  72             MyModalDialogHook m_myHook;
  73         };
  74     @endcode
  75
  76     @since 2.9.5
  77  */
  78 class wxModalDialogHook
  79 {
  80 public:
  81     /**
  82         Default and trivial constructor.
  83
  84         The constructor doesn't do anything, call Register() to make this hook
  85         active.
  86      */
  87     wxModalDialogHook();
  88
  89     /**
  90         Destructor unregisters the hook if it's currently active.
  91      */
  92     virtual ~wxModalDialogHook();
  93
  94     /**
  95         Register this hook as being active.
  96
  97         After registering the hook, its Enter() and Exit() methods will be
  98         called whenever a modal dialog is shown.
  99
 100         Notice that the order of registration matters: the last hook registered
 101         is called first, and if its Enter() returns a value different from
 102         ::wxID_NONE, the subsequent hooks are skipped.
 103
 104         It is an error to register the same hook twice.
 105      */
 106     void Register();
 107
 108     /**
 109         Unregister this hook.
 110
 111         Notice that is done automatically from the destructor, so usually
 112         calling this method explicitly is unnecessary.
 113
 114         The hook must be currently registered.
 115      */
 116     void Unregister();
 117
 118 protected:
 119     /**
 120         Called by wxWidgets before showing any modal dialogs.
 121
 122         Override this to be notified whenever a modal dialog is about to be
 123         shown.
 124
 125         If the return value of this method is ::wxID_NONE, the dialog is shown
 126         as usual and Exit() will be called when it is dismissed. If the return
 127         value is anything else, the dialog is not shown at all and its
 128         wxDialog::ShowModal() simply returns with the given result. In this
 129         case, Exit() won't be called neither.
 130
 131         @param dialog The dialog about to be shown, never @NULL.
 132         @return wxID_NONE to continue with showing the dialog or anything else
 133             to skip showing the dialog and just return this value from its
 134             ShowModal().
 135      */
 136     virtual int Enter(wxDialog* dialog) = 0;
 137
 138     /**
 139         Called by wxWidgets after dismissing the modal dialog.
 140
 141         Notice that it won't be called if Enter() hadn't been called because
 142         another modal hook, registered after this one, intercepted the dialog
 143         or if our Enter() was called but returned a value different from
 144         ::wxID_NONE.
 145
 146         @param dialog The dialog that was shown and dismissed, never @NULL.
 147      */
 148     virtual void Exit(wxDialog* dialog);
 149 };