From bd83cb56d29385e2a87840eeb3876b976a5afc43 Mon Sep 17 00:00:00 2001 From: Vadim Zeitlin Date: Sun, 10 Sep 2000 12:43:37 +0000 Subject: [PATCH] 1. added wxHelpProvider and (unfinished) wxSimpleHelpProvider 2. added wxStringHashTable which wxStringHashTable uses git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@8316 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- include/wx/cshelp.h | 111 ++++++++++++++++++++++++++++++++++------ include/wx/event.h | 52 +++++++++++-------- include/wx/hash.h | 30 +++++++++++ include/wx/window.h | 19 +++++++ samples/help/demo.cpp | 34 ++++++++++--- src/common/cshelp.cpp | 115 +++++++++++++++++++++++++++++++++++++----- src/common/hash.cpp | 79 +++++++++++++++++++++++++++++ src/common/wincmn.cpp | 67 ++++++++++++++++++++++++ 8 files changed, 449 insertions(+), 58 deletions(-) diff --git a/include/wx/cshelp.h b/include/wx/cshelp.h index e4b241f492..836e76e195 100644 --- a/include/wx/cshelp.h +++ b/include/wx/cshelp.h @@ -1,11 +1,11 @@ ///////////////////////////////////////////////////////////////////////////// -// Name: cshelp.h -// Purpose: Context-sensitive help classes -// Author: Julian Smart +// Name: wx/cshelp.h +// Purpose: Context-sensitive help support classes +// Author: Julian Smart, Vadim Zeitlin // Modified by: // Created: 08/09/2000 // RCS-ID: $Id$ -// Copyright: (c) Julian Smart +// Copyright: (c) 2000 Julian Smart, Vadim Zeitlin // Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// @@ -13,7 +13,7 @@ #define _WX_CSHELPH__ #ifdef __GNUG__ -#pragma interface "cshelp.h" + #pragma interface "cshelp.h" #endif #include "wx/defs.h" @@ -22,6 +22,10 @@ #include "wx/bmpbuttn.h" +// ---------------------------------------------------------------------------- +// classes used to implement context help UI +// ---------------------------------------------------------------------------- + /* * wxContextHelp * Invokes context-sensitive help. When the user @@ -29,12 +33,11 @@ * window for the application to display help for. */ -class WXDLLEXPORT wxContextHelp: public wxObject +class WXDLLEXPORT wxContextHelp : public wxObject { - DECLARE_DYNAMIC_CLASS(wxContextHelp) public: wxContextHelp(wxWindow* win = NULL, bool beginHelp = TRUE); - ~wxContextHelp(); + virtual ~wxContextHelp(); bool BeginContextHelp(wxWindow* win); bool EndContextHelp(); @@ -45,9 +48,11 @@ public: void SetStatus(bool status) { m_status = status; } protected: - bool m_inHelp; bool m_status; // TRUE if the user left-clicked + +private: + DECLARE_DYNAMIC_CLASS(wxContextHelp) }; /* @@ -56,19 +61,95 @@ protected: * to put the application into context help mode. */ -class WXDLLEXPORT wxContextHelpButton: public wxBitmapButton +class WXDLLEXPORT wxContextHelpButton : public wxBitmapButton { public: - wxContextHelpButton(wxWindow* parent, wxWindowID id = wxID_CONTEXT_HELP, - const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxSize(20, -1), - long style = wxBU_AUTODRAW); + wxContextHelpButton(wxWindow* parent, + wxWindowID id = wxID_CONTEXT_HELP, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxBU_AUTODRAW); void OnContextHelp(wxCommandEvent& event); +private: DECLARE_CLASS(wxContextHelpButton) DECLARE_EVENT_TABLE() }; #endif // wxUSE_HELP -#endif -// _WX_CSHELPH__ + +// ---------------------------------------------------------------------------- +// classes used to implement context help support +// ---------------------------------------------------------------------------- + +// wxHelpProvider is an ABC used by the program implementing context help to +// show the help text (or whatever: it may be HTML page or anything else) for +// the given window. +// +// The current help provider must be explicitly set by the application using +// wxHelpProvider::Set(). +class WXDLLEXPORT wxHelpProvider +{ +public: + // get/set the current (application-global) help provider (Set() returns + // the previous one) + static wxHelpProvider *Set(wxHelpProvider *helpProvider) + { + wxHelpProvider *helpProviderOld = ms_helpProvider; + ms_helpProvider = helpProvider; + return helpProviderOld; + } + + // unlike some other class, the help provider is not created on demand, + // this must be explicitly done by the application + static wxHelpProvider *Get() { return ms_helpProvider; } + + // get the help string (whose interpretation is help provider dependent + // except that empty string always means that no help is associated with + // the window) for this window + virtual wxString GetHelp(const wxWindowBase *window) = 0; + + // do show help for the given window (uses GetHelp() internally if + // applicable), return TRUE if it was done or FALSE if no help available + // for this window + virtual bool ShowHelp(wxWindowBase *window) = 0; + + // associate the text with the given window or id: although all help + // providers have these functions to allow making wxWindow::SetHelpText() + // work, not all of them implement them + virtual void AddHelp(wxWindowBase *window, const wxString& text); + + // this version associates the given text with all window with this id + // (may be used to set the same help string for all [Cancel] buttons in + // the application, for example) + virtual void AddHelp(wxWindowID id, const wxString& text); + + // virtual dtor for any base class + virtual ~wxHelpProvider(); + +private: + static wxHelpProvider *ms_helpProvider; +}; + +// wxSimpleHelpProvider is an implementation of wxHelpProvider which supports +// only plain text help strings and shows the string associated with the +// control (if any) in a tooltip +class WXDLLEXPORT wxSimpleHelpProvider : public wxHelpProvider +{ +public: + // implement wxHelpProvider methods + virtual wxString GetHelp(const wxWindowBase *window); + virtual bool ShowHelp(wxWindowBase *window); + virtual void AddHelp(wxWindowBase *window, const wxString& text); + virtual void AddHelp(wxWindowID id, const wxString& text); + +protected: + // we use 2 hashes for storing the help strings associated with windows + // and the ids + wxStringHashTable m_hashWindows, + m_hashIds; +}; + +#endif // _WX_CSHELPH__ + diff --git a/include/wx/event.h b/include/wx/event.h index 17aad6eace..1c319832e1 100644 --- a/include/wx/event.h +++ b/include/wx/event.h @@ -1,11 +1,11 @@ ///////////////////////////////////////////////////////////////////////////// -// Name: event.h +// Name: wx/event.h // Purpose: Event classes // Author: Julian Smart // Modified by: // Created: 01/02/97 // RCS-ID: $Id$ -// Copyright: (c) +// Copyright: (c) wxWindows team // Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// @@ -1404,35 +1404,43 @@ public: wxWindow *GetWindow() const { return (wxWindow *)GetEventObject(); } }; +// A help event is sent when the user clicks on a window in context-help mode. /* - wxEVT_HELP, wxEVT_DETAILED_HELP - Sent when the user clicks on a window in context-help mode. - The cursor position is in screen coordinates. - */ + wxEVT_HELP + wxEVT_DETAILED_HELP +*/ class WXDLLEXPORT wxHelpEvent : public wxCommandEvent { - DECLARE_DYNAMIC_CLASS(wxHelpEvent) - public: - wxHelpEvent(wxEventType type = wxEVT_NULL, wxWindowID id = 0, const wxPoint& pt = wxPoint(0, 0)) - { m_eventType = type; m_id = id; m_pos = pt; } + wxHelpEvent(wxEventType type = wxEVT_NULL, + wxWindowID id = 0, + const wxPoint& pt = wxDefaultPosition) + { + m_eventType = type; + m_id = id; + m_pos = pt; + } - // Position of event - const wxPoint& GetPosition() const { return m_pos; } - void SetPosition(const wxPoint& pos) { m_pos = pos; } + // Position of event (in screen coordinates) + const wxPoint& GetPosition() const { return m_pos; } + void SetPosition(const wxPoint& pos) { m_pos = pos; } - // Optional link to further help - const wxString& GetLink() const { return m_link; } - void SetLink(const wxString& link) { m_link = link; } + // Optional link to further help + const wxString& GetLink() const { return m_link; } + void SetLink(const wxString& link) { m_link = link; } - // Optional target to display help in. E.g. a window specification - const wxString& GetTarget() const { return m_target; } - void SetTarget(const wxString& target) { m_target = target; } + // Optional target to display help in. E.g. a window specification + const wxString& GetTarget() const { return m_target; } + void SetTarget(const wxString& target) { m_target = target; } - wxPoint m_pos; - wxString m_target; - wxString m_link; +protected: + wxPoint m_pos; + wxString m_target; + wxString m_link; + +private: + DECLARE_DYNAMIC_CLASS(wxHelpEvent) }; #endif // wxUSE_GUI diff --git a/include/wx/hash.h b/include/wx/hash.h index af9cbbce94..79e8339577 100644 --- a/include/wx/hash.h +++ b/include/wx/hash.h @@ -109,6 +109,36 @@ private: DECLARE_NO_COPY_CLASS(wxHashTableLong); }; +// ---------------------------------------------------------------------------- +// wxStringHashTable: a hash table which indexes strings with longs +// ---------------------------------------------------------------------------- + +class WXDLLEXPORT wxStringHashTable : public wxObject +{ +public: + wxStringHashTable(size_t sizeTable = wxHASH_SIZE_DEFAULT); + virtual ~wxStringHashTable(); + + // add a string associated with this key to the table + void Put(long key, const wxString& value); + + // get the string from the key: if not found, an empty string is returned + // and the wasFound is set to FALSE if not NULL + wxString Get(long key, bool *wasFound = NULL) const; + + // clean up + void Destroy(); + +private: + wxArrayLong **m_keys; + wxArrayString **m_values; + + // the size of array above + size_t m_hashSize; + + DECLARE_NO_COPY_CLASS(wxStringHashTable); +}; + // ---------------------------------------------------------------------------- // for compatibility only // ---------------------------------------------------------------------------- diff --git a/include/wx/window.h b/include/wx/window.h index e3ae2b4d99..61e65b7a9f 100644 --- a/include/wx/window.h +++ b/include/wx/window.h @@ -579,8 +579,24 @@ public: virtual void ScrollWindow( int dx, int dy, const wxRect* rect = (wxRect *) NULL ) = 0; + // context-sensitive help + // ---------------------- + + // these are the convenience functions wrapping wxHelpProvider methods + +#if wxUSE_HELP + // associate this help text with this window + void SetHelpText(const wxString& text); + // associate this help text with all windows with the same id as this + // one + void SetHelpTextForId(const wxString& text); + // get the help string associated with this window (may be empty) + wxString GetHelpText() const; +#endif // wxUSE_HELP + // tooltips // -------- + #if wxUSE_TOOLTIPS // the easiest way to set a tooltip for a window is to use this method void SetToolTip( const wxString &tip ); @@ -661,6 +677,9 @@ public: void OnSysColourChanged( wxSysColourChangedEvent& event ); void OnInitDialog( wxInitDialogEvent &event ); void OnMiddleClick( wxMouseEvent& event ); +#if wxUSE_HELP + void OnHelp(wxHelpEvent& event); +#endif // wxUSE_HELP // get the haqndle of the window for the underlying window system: this // is only used for wxWin itself or for user code which wants to call diff --git a/samples/help/demo.cpp b/samples/help/demo.cpp index 99bee8b693..ae8ff74766 100644 --- a/samples/help/demo.cpp +++ b/samples/help/demo.cpp @@ -90,6 +90,9 @@ public: // initialization (doing it here and not in the ctor allows to have an error // return: if OnInit() returns false, the application terminates) virtual bool OnInit(); + + // do some clean up here + virtual int OnExit(); }; // Define a new frame type: this is going to be our main frame @@ -318,9 +321,20 @@ bool MyApp::OnInit() } #endif + // create a simple help provider to make SetHelpText() do something + wxHelpProvider::Set(new wxSimpleHelpProvider); + return TRUE; } +int MyApp::OnExit() +{ + // clean up + delete wxHelpProvider::Set(NULL); + + return 0; +} + // ---------------------------------------------------------------------------- // main frame // ---------------------------------------------------------------------------- @@ -339,7 +353,7 @@ MyFrame::MyFrame(const wxString& title, const wxPoint& pos, const wxSize& size) menuFile->Append(HelpDemo_Help_Classes, "&Help on Classes..."); menuFile->Append(HelpDemo_Help_Functions, "&Help on Functions..."); menuFile->Append(HelpDemo_Help_ContextHelp, "&Context Help..."); - menuFile->Append(HelpDemo_Help_DialogContextHelp, "&Dialog Context Help..."); + menuFile->Append(HelpDemo_Help_DialogContextHelp, "&Dialog Context Help...\tCtrl-H"); menuFile->Append(HelpDemo_Help_Help, "&About Help Demo..."); menuFile->Append(HelpDemo_Help_Search, "&Search help..."); #if USE_HTML_HELP @@ -599,9 +613,6 @@ END_EVENT_TABLE() MyModalDialog::MyModalDialog(wxWindow *parent) : wxDialog() { - // Add the context-sensitive help button on the caption, MSW only - SetExtraStyle(wxDIALOG_EX_CONTEXTHELP); - wxDialog::Create(parent, -1, wxString("Modal dialog")); wxBoxSizer *sizerTop = new wxBoxSizer(wxVERTICAL); @@ -612,13 +623,20 @@ MyModalDialog::MyModalDialog(wxWindow *parent) sizerRow->Add(btnOK, 0, wxALIGN_CENTER | wxALL, 5); sizerRow->Add(btnCancel, 0, wxALIGN_CENTER | wxALL, 5); - // Add the explicit context-sensitive help button, non-MSW -#ifndef __WXMSW__ + // Add the context-sensitive help button on the caption for MSW and the + // explicit context-sensitive help button elsewhere +#ifdef __WXMSW__ + SetExtraStyle(wxDIALOG_EX_CONTEXTHELP); +#else sizerRow->Add(new wxContextHelpButton(this), 0, wxALIGN_CENTER | wxALL, 5); #endif - sizerTop->Add(new wxTextCtrl(this, wxID_APPLY, wxT("A demo text control"), wxDefaultPosition, wxSize(300, 100), wxTE_MULTILINE), - 0, wxEXPAND|wxALIGN_CENTER_VERTICAL|wxALL, 5 ); + wxTextCtrl *text = new wxTextCtrl(this, -1, wxT("A demo text control"), + wxDefaultPosition, wxSize(300, 100), + wxTE_MULTILINE); + text->SetHelpText(_("Type text here if you have got nothing more " + "more interesting to do")); + sizerTop->Add(text, 0, wxEXPAND|wxALIGN_CENTER_VERTICAL|wxALL, 5 ); sizerTop->Add(sizerRow, 0, wxALIGN_RIGHT|wxALIGN_CENTER_VERTICAL|wxALL, 5 ); SetAutoLayout(TRUE); diff --git a/src/common/cshelp.cpp b/src/common/cshelp.cpp index cc59931d9c..c9a033d8a6 100644 --- a/src/common/cshelp.cpp +++ b/src/common/cshelp.cpp @@ -1,41 +1,52 @@ ///////////////////////////////////////////////////////////////////////////// -// Name: cshelp.cpp +// Name: src/common/cshelp.cpp // Purpose: Context sensitive help class implementation -// Author: Julian Smart +// Author: Julian Smart, Vadim Zeitlin // Modified by: // Created: 08/09/2000 // RCS-ID: $Id$ -// Copyright: (c) Julian Smart +// Copyright: (c) 2000 Julian Smart, Vadim Zeitlin // Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// +// ============================================================================ +// declarations +// ============================================================================ + #ifdef __GNUG__ -#pragma implementation "cshelp.h" + #pragma implementation "cshelp.h" #endif +// ---------------------------------------------------------------------------- +// headers +// ---------------------------------------------------------------------------- + // For compilers that support precompilation, includes "wx.h". #include "wx/wxprec.h" #ifdef __BORLANDC__ -#pragma hdrstop + #pragma hdrstop #endif +#if wxUSE_HELP + #ifndef WX_PRECOMP -#include "wx/defs.h" + // FIXME: temporary needed for wxSimpleHelpProvider compilation, to be + // removed later + #include "wx/intl.h" + #include "wx/msgdlg.h" #endif #include "wx/app.h" -#if wxUSE_HELP - #include "wx/cshelp.h" -/* - * Invokes context-sensitive help - */ +// ---------------------------------------------------------------------------- +// wxContextHelpEvtHandler private class +// ---------------------------------------------------------------------------- -// This class exists in order to eat events until the left mouse -// button is pressed +// This class exists in order to eat events until the left mouse button is +// pressed class wxContextHelpEvtHandler: public wxEvtHandler { public: @@ -50,6 +61,19 @@ public: wxContextHelp* m_contextHelp; }; +// ============================================================================ +// implementation +// ============================================================================ + +// ---------------------------------------------------------------------------- +// wxContextHelp +// ---------------------------------------------------------------------------- + +/* + * Invokes context-sensitive help + */ + + IMPLEMENT_DYNAMIC_CLASS(wxContextHelp, wxObject) wxContextHelp::wxContextHelp(wxWindow* win, bool beginHelp) @@ -182,6 +206,10 @@ bool wxContextHelp::DispatchEvent(wxWindow* win, const wxPoint& pt) return eventProcessed; } +// ---------------------------------------------------------------------------- +// wxContextHelpButton +// ---------------------------------------------------------------------------- + /* * wxContextHelpButton * You can add this to your dialogs (especially on non-Windows platforms) @@ -227,4 +255,65 @@ void wxContextHelpButton::OnContextHelp(wxCommandEvent& event) wxContextHelp contextHelp(GetParent()); } +// ---------------------------------------------------------------------------- +// wxHelpProvider +// ---------------------------------------------------------------------------- + +wxHelpProvider *wxHelpProvider::ms_helpProvider = (wxHelpProvider *)NULL; + +// trivial implementation of some methods which we don't want to make pure +// virtual for convenience + +void wxHelpProvider::AddHelp(wxWindowBase * WXUNUSED(window), + const wxString& WXUNUSED(text)) +{ +} + +void wxHelpProvider::AddHelp(wxWindowID WXUNUSED(id), + const wxString& WXUNUSED(text)) +{ +} + +wxHelpProvider::~wxHelpProvider() +{ +} + +// ---------------------------------------------------------------------------- +// wxSimpleHelpProvider +// ---------------------------------------------------------------------------- + +wxString wxSimpleHelpProvider::GetHelp(const wxWindowBase *window) +{ + bool wasFound; + wxString text = m_hashWindows.Get((long)window, &wasFound); + if ( !wasFound ) + text = m_hashIds.Get(window->GetId()); + + return text; +} + +void wxSimpleHelpProvider::AddHelp(wxWindowBase *window, const wxString& text) +{ + m_hashWindows.Put((long)window, text); +} + +void wxSimpleHelpProvider::AddHelp(wxWindowID id, const wxString& text) +{ + m_hashIds.Put(id, text); +} + +bool wxSimpleHelpProvider::ShowHelp(wxWindowBase *window) +{ + wxString text = GetHelp(window); + if ( !text.empty() ) + { + wxMessageBox(text, _("Help"), wxICON_INFORMATION | wxOK, + (wxWindow *)window); + + return TRUE; + } + + return FALSE; +} + #endif // wxUSE_HELP diff --git a/src/common/hash.cpp b/src/common/hash.cpp index f2a43cd10b..09e9b42d13 100644 --- a/src/common/hash.cpp +++ b/src/common/hash.cpp @@ -226,6 +226,85 @@ long wxHashTableLong::Delete(long key) return wxNOT_FOUND; } +// ---------------------------------------------------------------------------- +// wxStringHashTable: more efficient than storing strings in a list +// ---------------------------------------------------------------------------- + +wxStringHashTable::wxStringHashTable(size_t sizeTable) +{ + m_keys = new wxArrayLong *[sizeTable]; + m_values = new wxArrayString *[sizeTable]; + + m_hashSize = sizeTable; + for ( size_t n = 0; n < m_hashSize; n++ ) + { + m_values[n] = (wxArrayString *)NULL; + m_keys[n] = (wxArrayLong *)NULL; + } +} + +wxStringHashTable::~wxStringHashTable() +{ + Destroy(); +} + +void wxStringHashTable::Destroy() +{ + for ( size_t n = 0; n < m_hashSize; n++ ) + { + delete m_values[n]; + delete m_keys[n]; + } + + delete [] m_values; + delete [] m_keys; + m_hashSize = 0; +} + +void wxStringHashTable::Put(long key, const wxString& value) +{ + wxCHECK_RET( m_hashSize, _T("must call Create() first") ); + + size_t slot = (size_t)abs((int)(key % (long)m_hashSize)); + + if ( !m_keys[slot] ) + { + m_keys[slot] = new wxArrayLong; + m_values[slot] = new wxArrayString; + } + + m_keys[slot]->Add(key); + m_values[slot]->Add(value); +} + +wxString wxStringHashTable::Get(long key, bool *wasFound) const +{ + wxCHECK_MSG( m_hashSize, _T(""), _T("must call Create() first") ); + + size_t slot = (size_t)abs((int)(key % (long)m_hashSize)); + + wxArrayLong *keys = m_keys[slot]; + if ( keys ) + { + size_t count = keys->GetCount(); + for ( size_t n = 0; n < count; n++ ) + { + if ( keys->Item(n) == key ) + { + if ( wasFound ) + *wasFound = TRUE; + + return m_values[slot]->Item(n); + } + } + } + + if ( wasFound ) + *wasFound = FALSE; + + return _T(""); +} + // ---------------------------------------------------------------------------- // old not type safe wxHashTable // ---------------------------------------------------------------------------- diff --git a/src/common/wincmn.cpp b/src/common/wincmn.cpp index e40b8f23c4..c419076210 100644 --- a/src/common/wincmn.cpp +++ b/src/common/wincmn.cpp @@ -53,6 +53,10 @@ #include "wx/dnd.h" #endif // wxUSE_DRAG_AND_DROP +#if wxUSE_HELP + #include "wx/cshelp.h" +#endif // wxUSE_HELP + #if wxUSE_TOOLTIPS #include "wx/tooltip.h" #endif // wxUSE_TOOLTIPS @@ -77,6 +81,11 @@ BEGIN_EVENT_TABLE(wxWindowBase, wxEvtHandler) EVT_SYS_COLOUR_CHANGED(wxWindowBase::OnSysColourChanged) EVT_INIT_DIALOG(wxWindowBase::OnInitDialog) EVT_MIDDLE_DOWN(wxWindowBase::OnMiddleClick) + +#if wxUSE_HELP + EVT_HELP(-1, wxWindowBase::OnHelp) +#endif // wxUSE_HELP + END_EVENT_TABLE() // ============================================================================ @@ -838,6 +847,64 @@ void wxWindowBase::InitDialog() GetEventHandler()->ProcessEvent(event); } +// ---------------------------------------------------------------------------- +// context-sensitive help support +// ---------------------------------------------------------------------------- + +#if wxUSE_HELP + +// associate this help text with this window +void wxWindowBase::SetHelpText(const wxString& text) +{ + wxHelpProvider *helpProvider = wxHelpProvider::Get(); + if ( helpProvider ) + { + helpProvider->AddHelp(this, text); + } +} + +// associate this help text with all windows with the same id as this +// one +void wxWindowBase::SetHelpTextForId(const wxString& text) +{ + wxHelpProvider *helpProvider = wxHelpProvider::Get(); + if ( helpProvider ) + { + helpProvider->AddHelp(GetId(), text); + } +} + +// get the help string associated with this window (may be empty) +wxString wxWindowBase::GetHelpText() const +{ + wxString text; + wxHelpProvider *helpProvider = wxHelpProvider::Get(); + if ( helpProvider ) + { + text = helpProvider->GetHelp(this); + } + + return text; +} + +// show help for this window +void wxWindowBase::OnHelp(wxHelpEvent& event) +{ + wxHelpProvider *helpProvider = wxHelpProvider::Get(); + if ( helpProvider ) + { + if ( helpProvider->ShowHelp(this) ) + { + // skip the event.Skip() below + return; + } + } + + event.Skip(); +} + +#endif // wxUSE_HELP + // ---------------------------------------------------------------------------- // tooltips // ---------------------------------------------------------------------------- -- 2.45.2