]> git.saurik.com Git - wxWidgets.git/blame_incremental - include/wx/cshelp.h
Fixed to work with the new wxMacControl system.
[wxWidgets.git] / include / wx / cshelp.h
... / ...
CommitLineData
1/////////////////////////////////////////////////////////////////////////////
2// Name: wx/cshelp.h
3// Purpose: Context-sensitive help support classes
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#ifndef _WX_CSHELPH__
13#define _WX_CSHELPH__
14
15#if defined(__GNUG__) && !defined(NO_GCC_PRAGMA)
16 #pragma interface "cshelp.h"
17#endif
18
19#include "wx/defs.h"
20
21#if wxUSE_HELP
22
23#include "wx/help.h"
24
25#include "wx/hashmap.h"
26#if wxUSE_BMPBUTTON
27#include "wx/bmpbuttn.h"
28#endif
29
30// ----------------------------------------------------------------------------
31// classes used to implement context help UI
32// ----------------------------------------------------------------------------
33
34/*
35 * wxContextHelp
36 * Invokes context-sensitive help. When the user
37 * clicks on a window, a wxEVT_HELP event will be sent to that
38 * window for the application to display help for.
39 */
40
41class WXDLLEXPORT wxContextHelp : public wxObject
42{
43public:
44 wxContextHelp(wxWindow* win = NULL, bool beginHelp = TRUE);
45 virtual ~wxContextHelp();
46
47 bool BeginContextHelp(wxWindow* win);
48 bool EndContextHelp();
49
50 bool EventLoop();
51 bool DispatchEvent(wxWindow* win, const wxPoint& pt);
52
53 void SetStatus(bool status) { m_status = status; }
54
55protected:
56 bool m_inHelp;
57 bool m_status; // TRUE if the user left-clicked
58
59private:
60 DECLARE_DYNAMIC_CLASS(wxContextHelp)
61};
62
63#if wxUSE_BMPBUTTON
64/*
65 * wxContextHelpButton
66 * You can add this to your dialogs (especially on non-Windows platforms)
67 * to put the application into context help mode.
68 */
69
70class WXDLLEXPORT wxContextHelpButton : public wxBitmapButton
71{
72public:
73 wxContextHelpButton(wxWindow* parent,
74 wxWindowID id = wxID_CONTEXT_HELP,
75 const wxPoint& pos = wxDefaultPosition,
76 const wxSize& size = wxDefaultSize,
77 long style = wxBU_AUTODRAW);
78
79 void OnContextHelp(wxCommandEvent& event);
80
81private:
82 DECLARE_DYNAMIC_CLASS_NO_COPY(wxContextHelpButton)
83 DECLARE_EVENT_TABLE()
84};
85
86#endif
87
88// ----------------------------------------------------------------------------
89// classes used to implement context help support
90// ----------------------------------------------------------------------------
91
92// wxHelpProvider is an abstract class used by the program implementing context help to
93// show the help text (or whatever: it may be HTML page or anything else) for
94// the given window.
95//
96// The current help provider must be explicitly set by the application using
97// wxHelpProvider::Set().
98class WXDLLEXPORT wxHelpProvider
99{
100public:
101 // get/set the current (application-global) help provider (Set() returns
102 // the previous one)
103 static wxHelpProvider *Set(wxHelpProvider *helpProvider)
104 {
105 wxHelpProvider *helpProviderOld = ms_helpProvider;
106 ms_helpProvider = helpProvider;
107 return helpProviderOld;
108 }
109
110 // unlike some other class, the help provider is not created on demand,
111 // this must be explicitly done by the application
112 static wxHelpProvider *Get() { return ms_helpProvider; }
113
114 // get the help string (whose interpretation is help provider dependent
115 // except that empty string always means that no help is associated with
116 // the window) for this window
117 virtual wxString GetHelp(const wxWindowBase *window) = 0;
118
119 // do show help for the given window (uses GetHelp() internally if
120 // applicable), return TRUE if it was done or FALSE if no help available
121 // for this window
122 virtual bool ShowHelp(wxWindowBase *window) = 0;
123
124 // associate the text with the given window or id: although all help
125 // providers have these functions to allow making wxWindow::SetHelpText()
126 // work, not all of them implement them
127 virtual void AddHelp(wxWindowBase *window, const wxString& text);
128
129 // this version associates the given text with all window with this id
130 // (may be used to set the same help string for all [Cancel] buttons in
131 // the application, for example)
132 virtual void AddHelp(wxWindowID id, const wxString& text);
133
134 // removes the association
135 virtual void RemoveHelp(wxWindowBase* window);
136
137 // virtual dtor for any base class
138 virtual ~wxHelpProvider();
139
140private:
141 static wxHelpProvider *ms_helpProvider;
142};
143
144WX_DECLARE_EXPORTED_HASH_MAP( long, wxString, wxIntegerHash, wxIntegerEqual,
145 wxLongToStringHashMap );
146
147// wxSimpleHelpProvider is an implementation of wxHelpProvider which supports
148// only plain text help strings and shows the string associated with the
149// control (if any) in a tooltip
150class WXDLLEXPORT wxSimpleHelpProvider : public wxHelpProvider
151{
152public:
153 // implement wxHelpProvider methods
154 virtual wxString GetHelp(const wxWindowBase *window);
155 virtual bool ShowHelp(wxWindowBase *window);
156 virtual void AddHelp(wxWindowBase *window, const wxString& text);
157 virtual void AddHelp(wxWindowID id, const wxString& text);
158 virtual void RemoveHelp(wxWindowBase* window);
159
160protected:
161 // we use 2 hashes for storing the help strings associated with windows
162 // and the ids
163 wxLongToStringHashMap m_hashWindows,
164 m_hashIds;
165};
166
167// wxHelpControllerHelpProvider is an implementation of wxHelpProvider which supports
168// both context identifiers and plain text help strings. If the help text is an integer,
169// it is passed to wxHelpController::DisplayContextPopup. Otherwise, it shows the string
170// in a tooltip as per wxSimpleHelpProvider.
171class WXDLLEXPORT wxHelpControllerHelpProvider : public wxSimpleHelpProvider
172{
173public:
174 // Note that it doesn't own the help controller. The help controller
175 // should be deleted separately.
176 wxHelpControllerHelpProvider(wxHelpControllerBase* hc = (wxHelpControllerBase*) NULL);
177
178 // implement wxHelpProvider methods
179 virtual bool ShowHelp(wxWindowBase *window);
180
181 // Other accessors
182 void SetHelpController(wxHelpControllerBase* hc) { m_helpController = hc; }
183 wxHelpControllerBase* GetHelpController() const { return m_helpController; }
184
185protected:
186 wxHelpControllerBase* m_helpController;
187
188 DECLARE_NO_COPY_CLASS(wxHelpControllerHelpProvider)
189};
190
191// Convenience function for turning context id into wxString
192WXDLLEXPORT wxString wxContextId(int id);
193
194#endif // wxUSE_HELP
195
196#endif // _WX_CSHELPH__
197