1 /////////////////////////////////////////////////////////////////////////////
2 // Name: src/common/cshelp.cpp
3 // Purpose: Context sensitive help class implementation
4 // Author: Julian Smart, Vadim Zeitlin
8 // Copyright: (c) 2000 Julian Smart, Vadim Zeitlin
9 // Licence: wxWindows licence
10 /////////////////////////////////////////////////////////////////////////////
12 // ============================================================================
14 // ============================================================================
16 // ----------------------------------------------------------------------------
18 // ----------------------------------------------------------------------------
20 // For compilers that support precompilation, includes "wx.h".
21 #include "wx/wxprec.h"
33 #include "wx/tipwin.h"
34 #include "wx/module.h"
35 #include "wx/cshelp.h"
37 // ----------------------------------------------------------------------------
38 // wxContextHelpEvtHandler private class
39 // ----------------------------------------------------------------------------
41 // This class exists in order to eat events until the left mouse button is
43 class wxContextHelpEvtHandler
: public wxEvtHandler
46 wxContextHelpEvtHandler(wxContextHelp
* contextHelp
)
48 m_contextHelp
= contextHelp
;
51 virtual bool ProcessEvent(wxEvent
& event
);
54 wxContextHelp
* m_contextHelp
;
56 DECLARE_NO_COPY_CLASS(wxContextHelpEvtHandler
)
59 // ============================================================================
61 // ============================================================================
63 // ----------------------------------------------------------------------------
65 // ----------------------------------------------------------------------------
68 * Invokes context-sensitive help
72 IMPLEMENT_DYNAMIC_CLASS(wxContextHelp
, wxObject
)
74 wxContextHelp::wxContextHelp(wxWindow
* win
, bool beginHelp
)
79 BeginContextHelp(win
);
82 wxContextHelp::~wxContextHelp()
88 // Not currently needed, but on some systems capture may not work as
89 // expected so we'll leave it here for now.
91 static void wxPushOrPopEventHandlers(wxContextHelp
* help
, wxWindow
* win
, bool push
)
94 win
->PushEventHandler(new wxContextHelpEvtHandler(help
));
96 win
->PopEventHandler(true);
98 wxWindowList::compatibility_iterator node
= win
->GetChildren().GetFirst();
101 wxWindow
* child
= node
->GetData();
102 wxPushOrPopEventHandlers(help
, child
, push
);
104 node
= node
->GetNext();
109 // Begin 'context help mode'
110 bool wxContextHelp::BeginContextHelp(wxWindow
* win
)
113 win
= wxTheApp
->GetTopWindow();
117 wxCursor
cursor(wxCURSOR_QUESTION_ARROW
);
118 wxCursor oldCursor
= win
->GetCursor();
119 win
->SetCursor(cursor
);
122 // wxSetCursor(cursor);
128 wxPushOrPopEventHandlers(this, win
, true);
130 win
->PushEventHandler(new wxContextHelpEvtHandler(this));
140 wxPushOrPopEventHandlers(this, win
, false);
142 win
->PopEventHandler(true);
145 win
->SetCursor(oldCursor
);
150 wxWindow
* winAtPtr
= wxFindWindowAtPointer(pt
);
155 printf("Picked %s (%d)\n", winAtPtr
->GetName().c_str(),
161 DispatchEvent(winAtPtr
, pt
);
167 bool wxContextHelp::EndContextHelp()
174 bool wxContextHelp::EventLoop()
180 if (wxTheApp
->Pending())
182 wxTheApp
->Dispatch();
186 wxTheApp
->ProcessIdle();
193 bool wxContextHelpEvtHandler::ProcessEvent(wxEvent
& event
)
195 if (event
.GetEventType() == wxEVT_LEFT_DOWN
)
197 m_contextHelp
->SetStatus(true);
198 m_contextHelp
->EndContextHelp();
202 if ((event
.GetEventType() == wxEVT_CHAR
) ||
203 (event
.GetEventType() == wxEVT_KEY_DOWN
) ||
204 (event
.GetEventType() == wxEVT_ACTIVATE
) ||
205 (event
.GetEventType() == wxEVT_MOUSE_CAPTURE_CHANGED
))
207 // May have already been set to true by a left-click
208 //m_contextHelp->SetStatus(false);
209 m_contextHelp
->EndContextHelp();
213 if ((event
.GetEventType() == wxEVT_PAINT
) ||
214 (event
.GetEventType() == wxEVT_ERASE_BACKGROUND
))
223 // Dispatch the help event to the relevant window
224 bool wxContextHelp::DispatchEvent(wxWindow
* win
, const wxPoint
& pt
)
226 wxWindow
* subjectOfHelp
= win
;
227 bool eventProcessed
= false;
228 while (subjectOfHelp
&& !eventProcessed
)
230 wxHelpEvent
helpEvent(wxEVT_HELP
, subjectOfHelp
->GetId(), pt
) ;
231 helpEvent
.SetEventObject(subjectOfHelp
);
233 eventProcessed
= win
->GetEventHandler()->ProcessEvent(helpEvent
);
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();
240 return eventProcessed
;
243 // ----------------------------------------------------------------------------
244 // wxContextHelpButton
245 // ----------------------------------------------------------------------------
248 * wxContextHelpButton
249 * You can add this to your dialogs (especially on non-Windows platforms)
250 * to put the application into context help mode.
255 static const char * csquery_xpm
[] = {
273 IMPLEMENT_CLASS(wxContextHelpButton
, wxBitmapButton
)
275 BEGIN_EVENT_TABLE(wxContextHelpButton
, wxBitmapButton
)
276 EVT_BUTTON(wxID_CONTEXT_HELP
, wxContextHelpButton::OnContextHelp
)
279 wxContextHelpButton::wxContextHelpButton(wxWindow
* parent
,
284 #if defined(__WXPM__)
285 : wxBitmapButton(parent
, id
, wxBitmap(wxCSQUERY_BITMAP
286 ,wxBITMAP_TYPE_RESOURCE
290 : wxBitmapButton(parent
, id
, wxBitmap(csquery_xpm
),
296 void wxContextHelpButton::OnContextHelp(wxCommandEvent
& WXUNUSED(event
))
298 wxContextHelp
contextHelp(GetParent());
301 // ----------------------------------------------------------------------------
303 // ----------------------------------------------------------------------------
305 wxHelpProvider
*wxHelpProvider::ms_helpProvider
= (wxHelpProvider
*)NULL
;
307 // trivial implementation of some methods which we don't want to make pure
308 // virtual for convenience
310 void wxHelpProvider::AddHelp(wxWindowBase
* WXUNUSED(window
),
311 const wxString
& WXUNUSED(text
))
315 void wxHelpProvider::AddHelp(wxWindowID
WXUNUSED(id
),
316 const wxString
& WXUNUSED(text
))
320 // removes the association
321 void wxHelpProvider::RemoveHelp(wxWindowBase
* WXUNUSED(window
))
325 wxHelpProvider::~wxHelpProvider()
329 // ----------------------------------------------------------------------------
330 // wxSimpleHelpProvider
331 // ----------------------------------------------------------------------------
333 #define WINHASH_KEY(w) wxPtrToUInt(w)
335 wxString
wxSimpleHelpProvider::GetHelp(const wxWindowBase
*window
)
337 wxSimpleHelpProviderHashMap::iterator it
= m_hashWindows
.find(WINHASH_KEY(window
));
339 if ( it
== m_hashWindows
.end() )
341 it
= m_hashIds
.find(window
->GetId());
342 if ( it
== m_hashIds
.end() )
343 return wxEmptyString
;
349 void wxSimpleHelpProvider::AddHelp(wxWindowBase
*window
, const wxString
& text
)
351 m_hashWindows
.erase(WINHASH_KEY(window
));
352 m_hashWindows
[WINHASH_KEY(window
)] = text
;
355 void wxSimpleHelpProvider::AddHelp(wxWindowID id
, const wxString
& text
)
357 wxSimpleHelpProviderHashMap::key_type key
= (wxSimpleHelpProviderHashMap::key_type
)id
;
358 m_hashIds
.erase(key
);
359 m_hashIds
[key
] = text
;
362 // removes the association
363 void wxSimpleHelpProvider::RemoveHelp(wxWindowBase
* window
)
365 m_hashWindows
.erase(WINHASH_KEY(window
));
368 bool wxSimpleHelpProvider::ShowHelp(wxWindowBase
*window
)
371 static wxTipWindow
* s_tipWindow
= NULL
;
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();
382 wxString text
= GetHelp(window
);
385 s_tipWindow
= new wxTipWindow((wxWindow
*)window
, text
, 100, & s_tipWindow
);
391 #endif // wxUSE_TIPWINDOW
396 // ----------------------------------------------------------------------------
397 // wxHelpControllerHelpProvider
398 // ----------------------------------------------------------------------------
400 wxHelpControllerHelpProvider::wxHelpControllerHelpProvider(wxHelpControllerBase
* hc
)
402 m_helpController
= hc
;
405 bool wxHelpControllerHelpProvider::ShowHelp(wxWindowBase
*window
)
407 wxString text
= GetHelp(window
);
410 if (m_helpController
)
413 return m_helpController
->DisplayContextPopup(wxAtoi(text
));
415 // If the help controller is capable of popping up the text...
416 else if (m_helpController
->DisplayTextPopup(text
, wxGetMousePosition()))
421 // ...else use the default method.
422 return wxSimpleHelpProvider::ShowHelp(window
);
425 return wxSimpleHelpProvider::ShowHelp(window
);
432 // Convenience function for turning context id into wxString
433 wxString
wxContextId(int id
)
435 return wxString::Format(_T("%d"), id
);
438 // ----------------------------------------------------------------------------
439 // wxHelpProviderModule: module responsible for cleaning up help provider.
440 // ----------------------------------------------------------------------------
442 class wxHelpProviderModule
: public wxModule
449 DECLARE_DYNAMIC_CLASS(wxHelpProviderModule
)
452 IMPLEMENT_DYNAMIC_CLASS(wxHelpProviderModule
, wxModule
)
454 bool wxHelpProviderModule::OnInit()
456 // Probably we don't want to do anything by default,
457 // since it could pull in extra code
458 // wxHelpProvider::Set(new wxSimpleHelpProvider);
463 void wxHelpProviderModule::OnExit()
465 if (wxHelpProvider::Get())
467 delete wxHelpProvider::Get();
468 wxHelpProvider::Set(NULL
);