]> git.saurik.com Git - wxWidgets.git/blame_incremental - interface/wx/modalhook.h
support for iPhone callbacks
[wxWidgets.git] / interface / wx / modalhook.h
... / ...
CommitLineData
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 */
78class wxModalDialogHook
79{
80public:
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
118protected:
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};