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

@@ -1,11 +1,11 @@
 /////////////////////////////////////////////////////////////////////////////
-// Name:        cshelp.h
+// Name:        wx/cshelp.h
-// Purpose:     Context-sensitive help classes
+// Purpose:     Context-sensitive help support classes
-// 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
 /////////////////////////////////////////////////////////////////////////////
 
@@ -22,6 +22,10 @@
 
 #include "wx/bmpbuttn.h"
 
+// ----------------------------------------------------------------------------
+// classes used to implement context help UI
+// ----------------------------------------------------------------------------
+
 /*
  * wxContextHelp
  * Invokes context-sensitive help. When the user
@@ -31,10 +35,9 @@
 
 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)
 };
 
 /*
@@ -59,16 +64,92 @@ protected:
 class WXDLLEXPORT wxContextHelpButton : public wxBitmapButton
 {
 public:
-    wxContextHelpButton(wxWindow* parent, wxWindowID id = wxID_CONTEXT_HELP,
+    wxContextHelpButton(wxWindow* parent,
-        const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxSize(20, -1),
+                        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__
+

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,21 +1404,25 @@ 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
+ wxEVT_HELP
- Sent when the user clicks on a window in context-help mode.
+ wxEVT_DETAILED_HELP
- The cursor position is in screen coordinates.
 */
 
 class WXDLLEXPORT wxHelpEvent : public wxCommandEvent
 {
-    DECLARE_DYNAMIC_CLASS(wxHelpEvent)
-
 public:
-  wxHelpEvent(wxEventType type = wxEVT_NULL, wxWindowID id = 0, const wxPoint& pt = wxPoint(0, 0))
+    wxHelpEvent(wxEventType type = wxEVT_NULL,
-      { m_eventType = type; m_id = id; m_pos = pt; }
+                wxWindowID id = 0,
+                const wxPoint& pt = wxDefaultPosition)
+    {
+        m_eventType = type;
+        m_id = id;
+        m_pos = pt;
+    }
 
-  // Position of event
+    // Position of event (in screen coordinates)
     const wxPoint& GetPosition() const { return m_pos; }
     void SetPosition(const wxPoint& pos) { m_pos = pos; }
 
@@ -1430,9 +1434,13 @@ public:
     const wxString& GetTarget() const { return m_target; }
     void SetTarget(const wxString& target) { m_target = target; }
 
+protected:
     wxPoint   m_pos;
     wxString  m_target;
     wxString  m_link;
+
+private:
+    DECLARE_DYNAMIC_CLASS(wxHelpEvent)
 };
 
 #endif // wxUSE_GUI

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
 // ----------------------------------------------------------------------------

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

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
+    // Add the context-sensitive help button on the caption for MSW and the
-#ifndef __WXMSW__
+    // 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),
+    wxTextCtrl *text = new wxTextCtrl(this, -1, wxT("A demo text control"),
-            0, wxEXPAND|wxALIGN_CENTER_VERTICAL|wxALL, 5 );
+                                      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);

src/common/cshelp.cpp

@@ -1,18 +1,26 @@
 /////////////////////////////////////////////////////////////////////////////
-// 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"
 #endif
 
+// ----------------------------------------------------------------------------
+// headers
+// ----------------------------------------------------------------------------
+
 // For compilers that support precompilation, includes "wx.h".
 #include "wx/wxprec.h"
 
@@ -20,22 +28,25 @@
     #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
+// This class exists in order to eat events until the left mouse button is
-// button is pressed
+// 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

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
 // ----------------------------------------------------------------------------

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
 // ----------------------------------------------------------------------------