]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/cshelp.h
Add wxFileName::SetPermissions().
[wxWidgets.git] / interface / wx / cshelp.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: cshelp.h
3 // Purpose: interface of wxHelpProvider
4 // Author: wxWidgets team
5 // Licence: wxWindows licence
6 /////////////////////////////////////////////////////////////////////////////
7
8 /**
9 @class wxHelpProvider
10
11 wxHelpProvider is an abstract class used by a program implementing
12 context-sensitive help to show the help text for the given window.
13
14 The current help provider must be explicitly set by the application using
15 Set().
16
17 @library{wxcore}
18 @category{help}
19
20 @see wxContextHelp, wxContextHelpButton, wxSimpleHelpProvider,
21 wxHelpControllerHelpProvider, wxWindow::SetHelpText(),
22 wxWindow::GetHelpTextAtPoint()
23 */
24 class wxHelpProvider
25 {
26 public:
27 /**
28 Virtual destructor for any base class.
29 */
30 virtual ~wxHelpProvider();
31
32 /**
33 Associates the text with the given window.
34
35 @remarks
36 Although all help providers have these functions to allow making
37 wxWindow::SetHelpText() work, not all of them implement the functions.
38 */
39 virtual void AddHelp(wxWindowBase* window, const wxString& text);
40
41 /**
42 Associates the text with the given ID.
43
44 This help text will be shown for all windows with ID @a id, unless they
45 have more specific help text associated using the other AddHelp()
46 prototype. May be used to set the same help string for all Cancel
47 buttons in the application, for example.
48
49 @remarks
50 Although all help providers have these functions to allow making
51 wxWindow::SetHelpText() work, not all of them implement the functions.
52 */
53 virtual void AddHelp(wxWindowID id, const wxString& text);
54
55 /**
56 Returns pointer to help provider instance.
57
58 Unlike some other classes, the help provider is not created on demand.
59 This must be explicitly done by the application using Set().
60 */
61 static wxHelpProvider* Get();
62
63 /**
64 This version associates the given text with all windows with this id.
65 May be used to set the same help string for all Cancel buttons in
66 the application, for example.
67 */
68 virtual wxString GetHelp(const wxWindowBase* window) = 0;
69
70 /**
71 Removes the association between the window pointer and the help text.
72 This is called by the wxWindow destructor. Without this, the table of
73 help strings will fill up and when window pointers are reused, the
74 wrong help string will be found.
75 */
76 virtual void RemoveHelp(wxWindowBase* window);
77
78 /**
79 Set the current, application-wide help provider.
80
81 @return Pointer to previous help provider or @NULL if there wasn't any.
82 */
83 static wxHelpProvider* Set(wxHelpProvider* helpProvider);
84
85 /**
86 Shows help for the given window.
87
88 Override this function if the help doesn't depend on the exact position
89 inside the window, otherwise you need to override ShowHelpAtPoint().
90 Returns @true if help was shown, or @false if no help was available for
91 this window.
92 */
93 virtual bool ShowHelp(wxWindowBase* window);
94
95 /**
96 This function may be overridden to show help for the window when it
97 should depend on the position inside the window, By default this method
98 forwards to ShowHelp(), so it is enough to only implement the latter if
99 the help doesn't depend on the position.
100
101 @param window
102 Window to show help text for.
103 @param point
104 Coordinates of the mouse at the moment of help event emission.
105 @param origin
106 Help event origin, see wxHelpEvent::GetOrigin.
107
108 @return @true if help was shown, or @false if no help was available
109 for this window.
110
111 @since 2.7.0
112 */
113 virtual bool ShowHelpAtPoint(wxWindowBase* window, const wxPoint& point,
114 wxHelpEvent::Origin origin);
115 };
116
117
118
119 /**
120 @class wxHelpControllerHelpProvider
121
122 wxHelpControllerHelpProvider is an implementation of wxHelpProvider which
123 supports both context identifiers and plain text help strings. If the help
124 text is an integer, it is passed to wxHelpController::DisplayContextPopup().
125 Otherwise, it shows the string in a tooltip as per wxSimpleHelpProvider. If
126 you use this with a wxCHMHelpController instance on windows, it will use
127 the native style of tip window instead of wxTipWindow.
128
129 You can use the convenience function wxContextId() to convert an integer
130 context id to a string for passing to wxWindow::SetHelpText().
131
132 @library{wxcore}
133 @category{help}
134
135 @see wxHelpProvider, wxSimpleHelpProvider, wxContextHelp,
136 wxWindow::SetHelpText(), wxWindow::GetHelpTextAtPoint()
137 */
138 class wxHelpControllerHelpProvider : public wxSimpleHelpProvider
139 {
140 public:
141 /**
142 Note that the instance doesn't own the help controller. The help
143 controller should be deleted separately.
144 */
145 wxHelpControllerHelpProvider(wxHelpControllerBase* hc = NULL);
146
147 /**
148 Returns the help controller associated with this help provider.
149 */
150 wxHelpControllerBase* GetHelpController() const;
151
152 /**
153 Sets the help controller associated with this help provider.
154 */
155 void SetHelpController(wxHelpControllerBase* hc);
156 };
157
158
159
160 /**
161 @class wxContextHelp
162
163 This class changes the cursor to a query and puts the application into a
164 'context-sensitive help mode'. When the user left-clicks on a window
165 within the specified window, a @c wxEVT_HELP event is sent to that control,
166 and the application may respond to it by popping up some help.
167
168 For example:
169 @code
170 wxContextHelp contextHelp(myWindow);
171 @endcode
172
173 There are a couple of ways to invoke this behaviour implicitly:
174
175 - Use the wxDIALOG_EX_CONTEXTHELP style for a dialog (Windows only). This
176 will put a question mark in the titlebar, and Windows will put the
177 application into context-sensitive help mode automatically, with further
178 programming.
179
180 - Create a wxContextHelpButton, whose predefined behaviour is
181 to create a context help object. Normally you will write your application
182 so that this button is only added to a dialog for non-Windows platforms
183 (use wxDIALOG_EX_CONTEXTHELP on Windows).
184
185 Note that on Mac OS X, the cursor does not change when in context-sensitive
186 help mode.
187
188 @library{wxcore}
189 @category{help}
190
191 @see wxHelpEvent, wxHelpController, wxContextHelpButton
192 */
193 class wxContextHelp : public wxObject
194 {
195 public:
196 /**
197 Constructs a context help object, calling BeginContextHelp() if
198 @a doNow is @true (the default).
199
200 If @a window is @NULL, the top window is used.
201 */
202 wxContextHelp(wxWindow* window = NULL, bool doNow = true);
203
204 /**
205 Destroys the context help object.
206 */
207 virtual ~wxContextHelp();
208
209 /**
210 Puts the application into context-sensitive help mode. @a window is the
211 window which will be used to catch events; if @NULL, the top window
212 will be used.
213
214 Returns @true if the application was successfully put into
215 context-sensitive help mode.
216 This function only returns when the event loop has finished.
217 */
218 bool BeginContextHelp(wxWindow* window);
219
220 /**
221 Ends context-sensitive help mode. Not normally called by the
222 application.
223 */
224 bool EndContextHelp();
225 };
226
227
228
229 /**
230 @class wxContextHelpButton
231
232 Instances of this class may be used to add a question mark button that when
233 pressed, puts the application into context-help mode. It does this by
234 creating a wxContextHelp object which itself generates a @c wxEVT_HELP event
235 when the user clicks on a window.
236
237 On Windows, you may add a question-mark icon to a dialog by use of the
238 wxDIALOG_EX_CONTEXTHELP extra style, but on other platforms you will have
239 to add a button explicitly, usually next to OK, Cancel or similar buttons.
240
241 @library{wxcore}
242 @category{help}
243
244 @see wxBitmapButton, wxContextHelp
245 */
246 class wxContextHelpButton : public wxBitmapButton
247 {
248 public:
249 /**
250 Constructor, creating and showing a context help button.
251
252 @param parent
253 Parent window. Must not be @NULL.
254 @param id
255 Button identifier. Defaults to wxID_CONTEXT_HELP.
256 @param pos
257 Button position.
258 If ::wxDefaultPosition is specified then a default position is chosen.
259 @param size
260 Button size.
261 If ::wxDefaultSize is specified then the button is sized appropriately
262 for the question mark bitmap.
263 @param style
264 Window style.
265
266 @remarks
267 Normally you only need pass the parent window to the constructor, and
268 use the defaults for the remaining parameters.
269 */
270 wxContextHelpButton(wxWindow* parent,
271 wxWindowID id = wxID_CONTEXT_HELP,
272 const wxPoint& pos = wxDefaultPosition,
273 const wxSize& size = wxDefaultSize,
274 long style = wxBU_AUTODRAW);
275 };
276
277
278 /**
279 @class wxSimpleHelpProvider
280
281 wxSimpleHelpProvider is an implementation of wxHelpProvider which supports
282 only plain text help strings, and shows the string associated with the
283 control (if any) in a tooltip.
284
285 @library{wxcore}
286 @category{help}
287
288 @see wxHelpProvider, wxHelpControllerHelpProvider, wxContextHelp,
289 wxWindow::SetHelpText()(, wxWindow::GetHelpTextAtPoint()
290 */
291 class wxSimpleHelpProvider : public wxHelpProvider
292 {
293 public:
294
295 };
296