/////////////////////////////////////////////////////////////////////////////
-// 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
/////////////////////////////////////////////////////////////////////////////
#define _WX_CSHELPH__
#ifdef __GNUG__
-#pragma interface "cshelp.h"
+ #pragma interface "cshelp.h"
#endif
#include "wx/defs.h"
#include "wx/bmpbuttn.h"
+// ----------------------------------------------------------------------------
+// classes used to implement context help UI
+// ----------------------------------------------------------------------------
+
/*
* wxContextHelp
* Invokes context-sensitive help. When the user
* 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();
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)
};
/*
* 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__
+
/////////////////////////////////////////////////////////////////////////////
-// 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
/////////////////////////////////////////////////////////////////////////////
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
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
// ----------------------------------------------------------------------------
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 );
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
// 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
}
#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
// ----------------------------------------------------------------------------
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
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);
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);
/////////////////////////////////////////////////////////////////////////////
-// 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:
wxContextHelp* m_contextHelp;
};
+// ============================================================================
+// implementation
+// ============================================================================
+
+// ----------------------------------------------------------------------------
+// wxContextHelp
+// ----------------------------------------------------------------------------
+
+/*
+ * Invokes context-sensitive help
+ */
+
+
IMPLEMENT_DYNAMIC_CLASS(wxContextHelp, wxObject)
wxContextHelp::wxContextHelp(wxWindow* win, bool beginHelp)
return eventProcessed;
}
+// ----------------------------------------------------------------------------
+// wxContextHelpButton
+// ----------------------------------------------------------------------------
+
/*
* wxContextHelpButton
* You can add this to your dialogs (especially on non-Windows platforms)
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
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
// ----------------------------------------------------------------------------
#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
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()
// ============================================================================
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
// ----------------------------------------------------------------------------
projects / wxWidgets.git / commitdiff
