]>
Commit | Line | Data |
---|---|---|
1 | ///////////////////////////////////////////////////////////////////////////// | |
2 | // Name: src/common/cshelp.cpp | |
3 | // Purpose: Context sensitive help class implementation | |
4 | // Author: Julian Smart, Vadim Zeitlin | |
5 | // Modified by: | |
6 | // Created: 08/09/2000 | |
7 | // RCS-ID: $Id$ | |
8 | // Copyright: (c) 2000 Julian Smart, Vadim Zeitlin | |
9 | // Licence: wxWindows licence | |
10 | ///////////////////////////////////////////////////////////////////////////// | |
11 | ||
12 | // ============================================================================ | |
13 | // declarations | |
14 | // ============================================================================ | |
15 | ||
16 | // ---------------------------------------------------------------------------- | |
17 | // headers | |
18 | // ---------------------------------------------------------------------------- | |
19 | ||
20 | // For compilers that support precompilation, includes "wx.h". | |
21 | #include "wx/wxprec.h" | |
22 | ||
23 | #ifdef __BORLANDC__ | |
24 | #pragma hdrstop | |
25 | #endif | |
26 | ||
27 | #if wxUSE_HELP | |
28 | ||
29 | #ifndef WX_PRECOMP | |
30 | #include "wx/app.h" | |
31 | #endif | |
32 | ||
33 | #include "wx/tipwin.h" | |
34 | #include "wx/module.h" | |
35 | #include "wx/cshelp.h" | |
36 | ||
37 | // ---------------------------------------------------------------------------- | |
38 | // wxContextHelpEvtHandler private class | |
39 | // ---------------------------------------------------------------------------- | |
40 | ||
41 | // This class exists in order to eat events until the left mouse button is | |
42 | // pressed | |
43 | class wxContextHelpEvtHandler: public wxEvtHandler | |
44 | { | |
45 | public: | |
46 | wxContextHelpEvtHandler(wxContextHelp* contextHelp) | |
47 | { | |
48 | m_contextHelp = contextHelp; | |
49 | } | |
50 | ||
51 | virtual bool ProcessEvent(wxEvent& event); | |
52 | ||
53 | //// Data | |
54 | wxContextHelp* m_contextHelp; | |
55 | ||
56 | DECLARE_NO_COPY_CLASS(wxContextHelpEvtHandler) | |
57 | }; | |
58 | ||
59 | // ============================================================================ | |
60 | // implementation | |
61 | // ============================================================================ | |
62 | ||
63 | // ---------------------------------------------------------------------------- | |
64 | // wxContextHelp | |
65 | // ---------------------------------------------------------------------------- | |
66 | ||
67 | /* | |
68 | * Invokes context-sensitive help | |
69 | */ | |
70 | ||
71 | ||
72 | IMPLEMENT_DYNAMIC_CLASS(wxContextHelp, wxObject) | |
73 | ||
74 | wxContextHelp::wxContextHelp(wxWindow* win, bool beginHelp) | |
75 | { | |
76 | m_inHelp = false; | |
77 | ||
78 | if (beginHelp) | |
79 | BeginContextHelp(win); | |
80 | } | |
81 | ||
82 | wxContextHelp::~wxContextHelp() | |
83 | { | |
84 | if (m_inHelp) | |
85 | EndContextHelp(); | |
86 | } | |
87 | ||
88 | // Not currently needed, but on some systems capture may not work as | |
89 | // expected so we'll leave it here for now. | |
90 | #ifdef __WXMOTIF__ | |
91 | static void wxPushOrPopEventHandlers(wxContextHelp* help, wxWindow* win, bool push) | |
92 | { | |
93 | if (push) | |
94 | win->PushEventHandler(new wxContextHelpEvtHandler(help)); | |
95 | else | |
96 | win->PopEventHandler(true); | |
97 | ||
98 | wxWindowList::compatibility_iterator node = win->GetChildren().GetFirst(); | |
99 | while (node) | |
100 | { | |
101 | wxWindow* child = node->GetData(); | |
102 | wxPushOrPopEventHandlers(help, child, push); | |
103 | ||
104 | node = node->GetNext(); | |
105 | } | |
106 | } | |
107 | #endif | |
108 | ||
109 | // Begin 'context help mode' | |
110 | bool wxContextHelp::BeginContextHelp(wxWindow* win) | |
111 | { | |
112 | if (!win) | |
113 | win = wxTheApp->GetTopWindow(); | |
114 | if (!win) | |
115 | return false; | |
116 | ||
117 | wxCursor cursor(wxCURSOR_QUESTION_ARROW); | |
118 | wxCursor oldCursor = win->GetCursor(); | |
119 | win->SetCursor(cursor); | |
120 | ||
121 | #ifdef __WXMSW__ | |
122 | // wxSetCursor(cursor); | |
123 | #endif | |
124 | ||
125 | m_status = false; | |
126 | ||
127 | #ifdef __WXMOTIF__ | |
128 | wxPushOrPopEventHandlers(this, win, true); | |
129 | #else | |
130 | win->PushEventHandler(new wxContextHelpEvtHandler(this)); | |
131 | #endif | |
132 | ||
133 | win->CaptureMouse(); | |
134 | ||
135 | EventLoop(); | |
136 | ||
137 | win->ReleaseMouse(); | |
138 | ||
139 | #ifdef __WXMOTIF__ | |
140 | wxPushOrPopEventHandlers(this, win, false); | |
141 | #else | |
142 | win->PopEventHandler(true); | |
143 | #endif | |
144 | ||
145 | win->SetCursor(oldCursor); | |
146 | ||
147 | if (m_status) | |
148 | { | |
149 | wxPoint pt; | |
150 | wxWindow* winAtPtr = wxFindWindowAtPointer(pt); | |
151 | ||
152 | #if 0 | |
153 | if (winAtPtr) | |
154 | { | |
155 | printf("Picked %s (%d)\n", winAtPtr->GetName().c_str(), | |
156 | winAtPtr->GetId()); | |
157 | } | |
158 | #endif | |
159 | ||
160 | if (winAtPtr) | |
161 | DispatchEvent(winAtPtr, pt); | |
162 | } | |
163 | ||
164 | return true; | |
165 | } | |
166 | ||
167 | bool wxContextHelp::EndContextHelp() | |
168 | { | |
169 | m_inHelp = false; | |
170 | ||
171 | return true; | |
172 | } | |
173 | ||
174 | bool wxContextHelp::EventLoop() | |
175 | { | |
176 | m_inHelp = true; | |
177 | ||
178 | while ( m_inHelp ) | |
179 | { | |
180 | if (wxTheApp->Pending()) | |
181 | { | |
182 | wxTheApp->Dispatch(); | |
183 | } | |
184 | else | |
185 | { | |
186 | wxTheApp->ProcessIdle(); | |
187 | } | |
188 | } | |
189 | ||
190 | return true; | |
191 | } | |
192 | ||
193 | bool wxContextHelpEvtHandler::ProcessEvent(wxEvent& event) | |
194 | { | |
195 | if (event.GetEventType() == wxEVT_LEFT_DOWN) | |
196 | { | |
197 | m_contextHelp->SetStatus(true); | |
198 | m_contextHelp->EndContextHelp(); | |
199 | return true; | |
200 | } | |
201 | ||
202 | if ((event.GetEventType() == wxEVT_CHAR) || | |
203 | (event.GetEventType() == wxEVT_KEY_DOWN) || | |
204 | (event.GetEventType() == wxEVT_ACTIVATE) || | |
205 | (event.GetEventType() == wxEVT_MOUSE_CAPTURE_CHANGED)) | |
206 | { | |
207 | // May have already been set to true by a left-click | |
208 | //m_contextHelp->SetStatus(false); | |
209 | m_contextHelp->EndContextHelp(); | |
210 | return true; | |
211 | } | |
212 | ||
213 | if ((event.GetEventType() == wxEVT_PAINT) || | |
214 | (event.GetEventType() == wxEVT_ERASE_BACKGROUND)) | |
215 | { | |
216 | event.Skip(); | |
217 | return false; | |
218 | } | |
219 | ||
220 | return true; | |
221 | } | |
222 | ||
223 | // Dispatch the help event to the relevant window | |
224 | bool wxContextHelp::DispatchEvent(wxWindow* win, const wxPoint& pt) | |
225 | { | |
226 | wxWindow* subjectOfHelp = win; | |
227 | bool eventProcessed = false; | |
228 | while (subjectOfHelp && !eventProcessed) | |
229 | { | |
230 | wxHelpEvent helpEvent(wxEVT_HELP, subjectOfHelp->GetId(), pt) ; | |
231 | helpEvent.SetEventObject(subjectOfHelp); | |
232 | ||
233 | eventProcessed = win->GetEventHandler()->ProcessEvent(helpEvent); | |
234 | ||
235 | // Go up the window hierarchy until the event is handled (or not). | |
236 | // I.e. keep submitting ancestor windows until one is recognised | |
237 | // by the app code that processes the ids and displays help. | |
238 | subjectOfHelp = subjectOfHelp->GetParent(); | |
239 | } | |
240 | return eventProcessed; | |
241 | } | |
242 | ||
243 | // ---------------------------------------------------------------------------- | |
244 | // wxContextHelpButton | |
245 | // ---------------------------------------------------------------------------- | |
246 | ||
247 | /* | |
248 | * wxContextHelpButton | |
249 | * You can add this to your dialogs (especially on non-Windows platforms) | |
250 | * to put the application into context help mode. | |
251 | */ | |
252 | ||
253 | #ifndef __WXPM__ | |
254 | ||
255 | static const char * csquery_xpm[] = { | |
256 | "12 11 2 1", | |
257 | " c None", | |
258 | ". c #000000", | |
259 | " ", | |
260 | " .... ", | |
261 | " .. .. ", | |
262 | " .. .. ", | |
263 | " .. ", | |
264 | " .. ", | |
265 | " .. ", | |
266 | " ", | |
267 | " .. ", | |
268 | " .. ", | |
269 | " "}; | |
270 | ||
271 | #endif | |
272 | ||
273 | IMPLEMENT_CLASS(wxContextHelpButton, wxBitmapButton) | |
274 | ||
275 | BEGIN_EVENT_TABLE(wxContextHelpButton, wxBitmapButton) | |
276 | EVT_BUTTON(wxID_CONTEXT_HELP, wxContextHelpButton::OnContextHelp) | |
277 | END_EVENT_TABLE() | |
278 | ||
279 | wxContextHelpButton::wxContextHelpButton(wxWindow* parent, | |
280 | wxWindowID id, | |
281 | const wxPoint& pos, | |
282 | const wxSize& size, | |
283 | long style) | |
284 | #if defined(__WXPM__) | |
285 | : wxBitmapButton(parent, id, wxBitmap(wxCSQUERY_BITMAP | |
286 | ,wxBITMAP_TYPE_RESOURCE | |
287 | ), | |
288 | pos, size, style) | |
289 | #else | |
290 | : wxBitmapButton(parent, id, wxBitmap(csquery_xpm), | |
291 | pos, size, style) | |
292 | #endif | |
293 | { | |
294 | } | |
295 | ||
296 | void wxContextHelpButton::OnContextHelp(wxCommandEvent& WXUNUSED(event)) | |
297 | { | |
298 | wxContextHelp contextHelp(GetParent()); | |
299 | } | |
300 | ||
301 | // ---------------------------------------------------------------------------- | |
302 | // wxHelpProvider | |
303 | // ---------------------------------------------------------------------------- | |
304 | ||
305 | wxHelpProvider *wxHelpProvider::ms_helpProvider = (wxHelpProvider *)NULL; | |
306 | ||
307 | // trivial implementation of some methods which we don't want to make pure | |
308 | // virtual for convenience | |
309 | ||
310 | void wxHelpProvider::AddHelp(wxWindowBase * WXUNUSED(window), | |
311 | const wxString& WXUNUSED(text)) | |
312 | { | |
313 | } | |
314 | ||
315 | void wxHelpProvider::AddHelp(wxWindowID WXUNUSED(id), | |
316 | const wxString& WXUNUSED(text)) | |
317 | { | |
318 | } | |
319 | ||
320 | // removes the association | |
321 | void wxHelpProvider::RemoveHelp(wxWindowBase* WXUNUSED(window)) | |
322 | { | |
323 | } | |
324 | ||
325 | wxHelpProvider::~wxHelpProvider() | |
326 | { | |
327 | } | |
328 | ||
329 | // ---------------------------------------------------------------------------- | |
330 | // wxSimpleHelpProvider | |
331 | // ---------------------------------------------------------------------------- | |
332 | ||
333 | #define WINHASH_KEY(w) wxPtrToUInt(w) | |
334 | ||
335 | wxString wxSimpleHelpProvider::GetHelp(const wxWindowBase *window) | |
336 | { | |
337 | wxSimpleHelpProviderHashMap::iterator it = m_hashWindows.find(WINHASH_KEY(window)); | |
338 | ||
339 | if ( it == m_hashWindows.end() ) | |
340 | { | |
341 | it = m_hashIds.find(window->GetId()); | |
342 | if ( it == m_hashIds.end() ) | |
343 | return wxEmptyString; | |
344 | } | |
345 | ||
346 | return it->second; | |
347 | } | |
348 | ||
349 | void wxSimpleHelpProvider::AddHelp(wxWindowBase *window, const wxString& text) | |
350 | { | |
351 | m_hashWindows.erase(WINHASH_KEY(window)); | |
352 | m_hashWindows[WINHASH_KEY(window)] = text; | |
353 | } | |
354 | ||
355 | void wxSimpleHelpProvider::AddHelp(wxWindowID id, const wxString& text) | |
356 | { | |
357 | wxSimpleHelpProviderHashMap::key_type key = (wxSimpleHelpProviderHashMap::key_type)id; | |
358 | m_hashIds.erase(key); | |
359 | m_hashIds[key] = text; | |
360 | } | |
361 | ||
362 | // removes the association | |
363 | void wxSimpleHelpProvider::RemoveHelp(wxWindowBase* window) | |
364 | { | |
365 | m_hashWindows.erase(WINHASH_KEY(window)); | |
366 | } | |
367 | ||
368 | bool wxSimpleHelpProvider::ShowHelp(wxWindowBase *window) | |
369 | { | |
370 | #if wxUSE_TIPWINDOW | |
371 | static wxTipWindow* s_tipWindow = NULL; | |
372 | ||
373 | if (s_tipWindow) | |
374 | { | |
375 | // Prevent s_tipWindow being nulled in OnIdle, | |
376 | // thereby removing the chance for the window to be closed by ShowHelp | |
377 | s_tipWindow->SetTipWindowPtr(NULL); | |
378 | s_tipWindow->Close(); | |
379 | } | |
380 | s_tipWindow = NULL; | |
381 | ||
382 | wxString text = GetHelp(window); | |
383 | if ( !text.empty() ) | |
384 | { | |
385 | s_tipWindow = new wxTipWindow((wxWindow *)window, text, 100, & s_tipWindow); | |
386 | ||
387 | return true; | |
388 | } | |
389 | #else | |
390 | wxUnusedVar(window); | |
391 | #endif // wxUSE_TIPWINDOW | |
392 | ||
393 | return false; | |
394 | } | |
395 | ||
396 | // ---------------------------------------------------------------------------- | |
397 | // wxHelpControllerHelpProvider | |
398 | // ---------------------------------------------------------------------------- | |
399 | ||
400 | wxHelpControllerHelpProvider::wxHelpControllerHelpProvider(wxHelpControllerBase* hc) | |
401 | { | |
402 | m_helpController = hc; | |
403 | } | |
404 | ||
405 | bool wxHelpControllerHelpProvider::ShowHelp(wxWindowBase *window) | |
406 | { | |
407 | wxString text = GetHelp(window); | |
408 | if ( !text.empty() ) | |
409 | { | |
410 | if (m_helpController) | |
411 | { | |
412 | if (text.IsNumber()) | |
413 | return m_helpController->DisplayContextPopup(wxAtoi(text)); | |
414 | ||
415 | // If the help controller is capable of popping up the text... | |
416 | else if (m_helpController->DisplayTextPopup(text, wxGetMousePosition())) | |
417 | { | |
418 | return true; | |
419 | } | |
420 | else | |
421 | // ...else use the default method. | |
422 | return wxSimpleHelpProvider::ShowHelp(window); | |
423 | } | |
424 | else | |
425 | return wxSimpleHelpProvider::ShowHelp(window); | |
426 | ||
427 | } | |
428 | ||
429 | return false; | |
430 | } | |
431 | ||
432 | // Convenience function for turning context id into wxString | |
433 | wxString wxContextId(int id) | |
434 | { | |
435 | return wxString::Format(_T("%d"), id); | |
436 | } | |
437 | ||
438 | // ---------------------------------------------------------------------------- | |
439 | // wxHelpProviderModule: module responsible for cleaning up help provider. | |
440 | // ---------------------------------------------------------------------------- | |
441 | ||
442 | class wxHelpProviderModule : public wxModule | |
443 | { | |
444 | public: | |
445 | bool OnInit(); | |
446 | void OnExit(); | |
447 | ||
448 | private: | |
449 | DECLARE_DYNAMIC_CLASS(wxHelpProviderModule) | |
450 | }; | |
451 | ||
452 | IMPLEMENT_DYNAMIC_CLASS(wxHelpProviderModule, wxModule) | |
453 | ||
454 | bool wxHelpProviderModule::OnInit() | |
455 | { | |
456 | // Probably we don't want to do anything by default, | |
457 | // since it could pull in extra code | |
458 | // wxHelpProvider::Set(new wxSimpleHelpProvider); | |
459 | ||
460 | return true; | |
461 | } | |
462 | ||
463 | void wxHelpProviderModule::OnExit() | |
464 | { | |
465 | if (wxHelpProvider::Get()) | |
466 | { | |
467 | delete wxHelpProvider::Get(); | |
468 | wxHelpProvider::Set(NULL); | |
469 | } | |
470 | } | |
471 | ||
472 | #endif // wxUSE_HELP |