]>
Commit | Line | Data |
---|---|---|
4f3449b4 | 1 | ///////////////////////////////////////////////////////////////////////////// |
d14a1e28 | 2 | // Name: _cshelp.i |
4f3449b4 RD |
3 | // Purpose: Context sensitive help classes, and etc. |
4 | // | |
5 | // Author: Robin Dunn | |
6 | // | |
7 | // Created: 28-July-2001 | |
8 | // RCS-ID: $Id$ | |
9 | // Copyright: (c) 2001 by Total Control Software | |
10 | // Licence: wxWindows license | |
11 | ///////////////////////////////////////////////////////////////////////////// | |
12 | ||
d14a1e28 RD |
13 | // not a %module |
14 | ||
15 | //--------------------------------------------------------------------------- | |
16 | %newgroup | |
4f3449b4 RD |
17 | |
18 | %{ | |
4f3449b4 RD |
19 | %} |
20 | ||
4f3449b4 RD |
21 | //---------------------------------------------------------------------- |
22 | ||
23 | enum { | |
24 | wxFRAME_EX_CONTEXTHELP, | |
25 | wxDIALOG_EX_CONTEXTHELP, | |
4f3449b4 | 26 | }; |
d14a1e28 RD |
27 | %constant wxEventType wxEVT_HELP; |
28 | %constant wxEventType wxEVT_DETAILED_HELP; | |
4f3449b4 RD |
29 | |
30 | ||
d14a1e28 RD |
31 | %pythoncode { |
32 | EVT_HELP = wx.PyEventBinder( wxEVT_HELP, 1) | |
33 | EVT_HELP_RANGE = wx.PyEventBinder( wxEVT_HELP, 2) | |
34 | EVT_DETAILED_HELP = wx.PyEventBinder( wxEVT_DETAILED_HELP, 1) | |
35 | EVT_DETAILED_HELP_RANGE = wx.PyEventBinder( wxEVT_DETAILED_HELP, 2) | |
36 | } | |
4f3449b4 RD |
37 | |
38 | //---------------------------------------------------------------------- | |
39 | ||
4c42683a | 40 | DocStr(wxHelpEvent, |
d07d2bc9 RD |
41 | "A help event is sent when the user has requested context-sensitive |
42 | help. This can either be caused by the application requesting | |
43 | context-sensitive help mode via wx.ContextHelp, or (on MS Windows) by | |
44 | the system generating a WM_HELP message when the user pressed F1 or | |
45 | clicked on the query button in a dialog caption. | |
46 | ||
47 | A help event is sent to the window that the user clicked on, and is | |
48 | propagated up the window hierarchy until the event is processed or | |
49 | there are no more event handlers. The application should call | |
50 | event.GetId to check the identity of the clicked-on window, and then | |
51 | either show some suitable help or call event.Skip if the identifier is | |
52 | unrecognised. Calling Skip is important because it allows wxWindows to | |
53 | generate further events for ancestors of the clicked-on | |
54 | window. Otherwise it would be impossible to show help for container | |
55 | windows, since processing would stop after the first window found.", | |
56 | " | |
57 | ||
58 | Events | |
59 | ------- | |
60 | ============== ========================================= | |
4c42683a RD |
61 | EVT_HELP Sent when the user has requested context- |
62 | sensitive help. | |
63 | EVT_HELP_RANGE Allows to catch EVT_HELP for a range of IDs | |
d07d2bc9 RD |
64 | ============== ========================================= |
65 | ||
66 | :see: `wx.ContextHelp`, `wx.ContextHelpButton` | |
4c42683a RD |
67 | "); |
68 | ||
d14a1e28 | 69 | |
4f3449b4 RD |
70 | class wxHelpEvent : public wxCommandEvent |
71 | { | |
72 | public: | |
45dc66f8 RD |
73 | // how was this help event generated? |
74 | enum Origin | |
75 | { | |
76 | Origin_Unknown, // unrecognized event source | |
77 | Origin_Keyboard, // event generated from F1 key press | |
78 | Origin_HelpButton // event from [?] button on the title bar (Windows) | |
79 | }; | |
80 | ||
4c42683a RD |
81 | DocCtorStr( |
82 | wxHelpEvent(wxEventType type = wxEVT_NULL, | |
83 | wxWindowID winid = 0, | |
45dc66f8 RD |
84 | const wxPoint& pt = wxDefaultPosition, |
85 | Origin origin = Origin_Unknown ), | |
d07d2bc9 | 86 | "", ""); |
4c42683a RD |
87 | |
88 | ||
89 | DocDeclStr( | |
90 | const wxPoint , GetPosition() const, | |
d07d2bc9 RD |
91 | "Returns the left-click position of the mouse, in screen |
92 | coordinates. This allows the application to position the help | |
93 | appropriately.", ""); | |
4c42683a RD |
94 | |
95 | DocDeclStr( | |
96 | void , SetPosition(const wxPoint& pos), | |
d07d2bc9 | 97 | "Sets the left-click position of the mouse, in screen coordinates.", ""); |
4c42683a RD |
98 | |
99 | ||
100 | DocDeclStr( | |
101 | const wxString& , GetLink() const, | |
d07d2bc9 | 102 | "Get an optional link to further help", ""); |
4c42683a RD |
103 | |
104 | DocDeclStr( | |
105 | void , SetLink(const wxString& link), | |
d07d2bc9 | 106 | "Set an optional link to further help", ""); |
4c42683a RD |
107 | |
108 | ||
109 | DocDeclStr( | |
110 | const wxString& , GetTarget() const, | |
d07d2bc9 | 111 | "Get an optional target to display help in. E.g. a window specification", ""); |
4c42683a RD |
112 | |
113 | DocDeclStr( | |
114 | void , SetTarget(const wxString& target), | |
d07d2bc9 | 115 | "Set an optional target to display help in. E.g. a window specification", ""); |
45dc66f8 RD |
116 | |
117 | // optional indication of the event source | |
118 | DocDeclStr( | |
119 | Origin , GetOrigin() const, | |
120 | "Optiononal indication of the source of the event.", ""); | |
4c42683a | 121 | |
45dc66f8 RD |
122 | DocDeclStr( |
123 | void , SetOrigin(Origin origin), | |
124 | "", ""); | |
125 | ||
4c42683a | 126 | }; |
d14a1e28 | 127 | |
4c42683a | 128 | //--------------------------------------------------------------------------- |
d14a1e28 | 129 | |
d14a1e28 | 130 | |
4c42683a | 131 | DocStr(wxContextHelp, |
d07d2bc9 RD |
132 | "This class changes the cursor to a query and puts the application into |
133 | a 'context-sensitive help mode'. When the user left-clicks on a window | |
134 | within the specified window, a ``EVT_HELP`` event is sent to that | |
135 | control, and the application may respond to it by popping up some | |
136 | help. | |
4f3449b4 | 137 | |
4c42683a RD |
138 | There are a couple of ways to invoke this behaviour implicitly: |
139 | ||
d07d2bc9 RD |
140 | * Use the wx.DIALOG_EX_CONTEXTHELP extended style for a dialog |
141 | (Windows only). This will put a question mark in the titlebar, | |
142 | and Windows will put the application into context-sensitive help | |
143 | mode automatically, with further programming. | |
144 | ||
145 | * Create a `wx.ContextHelpButton`, whose predefined behaviour is | |
146 | to create a context help object. Normally you will write your | |
147 | application so that this button is only added to a dialog for | |
148 | non-Windows platforms (use ``wx.DIALOG_EX_CONTEXTHELP`` on | |
149 | Windows). | |
4c42683a | 150 | |
d07d2bc9 RD |
151 | :see: `wx.ContextHelpButton` |
152 | ", ""); | |
4f3449b4 | 153 | |
ab1f7d2a RD |
154 | MustHaveApp(wxContextHelp); |
155 | ||
4f3449b4 RD |
156 | class wxContextHelp : public wxObject { |
157 | public: | |
4c42683a | 158 | DocCtorStr( |
a72f4631 | 159 | wxContextHelp(wxWindow* window = NULL, bool doNow = true), |
d07d2bc9 RD |
160 | "Constructs a context help object, calling BeginContextHelp if doNow is |
161 | true (the default). | |
162 | ||
163 | If window is None, the top window is used.", ""); | |
4c42683a | 164 | |
4f3449b4 RD |
165 | ~wxContextHelp(); |
166 | ||
4c42683a RD |
167 | DocDeclStr( |
168 | bool , BeginContextHelp(wxWindow* window = NULL), | |
d07d2bc9 RD |
169 | "Puts the application into context-sensitive help mode. window is the |
170 | window which will be used to catch events; if NULL, the top window | |
171 | will be used. | |
172 | ||
173 | Returns true if the application was successfully put into | |
174 | context-sensitive help mode. This function only returns when the event | |
175 | loop has finished.", ""); | |
4c42683a RD |
176 | |
177 | DocDeclStr( | |
178 | bool , EndContextHelp(), | |
d07d2bc9 RD |
179 | "Ends context-sensitive help mode. Not normally called by the |
180 | application.", ""); | |
4c42683a | 181 | |
4f3449b4 RD |
182 | }; |
183 | ||
184 | ||
185 | //---------------------------------------------------------------------- | |
186 | ||
4c42683a | 187 | DocStr(wxContextHelpButton, |
d07d2bc9 RD |
188 | "Instances of this class may be used to add a question mark button that |
189 | when pressed, puts the application into context-help mode. It does | |
190 | this by creating a wx.ContextHelp object which itself generates a | |
191 | ``EVT_HELP`` event when the user clicks on a window. | |
192 | ||
193 | On Windows, you may add a question-mark icon to a dialog by use of the | |
194 | ``wx.DIALOG_EX_CONTEXTHELP`` extra style, but on other platforms you | |
195 | will have to add a button explicitly, usually next to OK, Cancel or | |
196 | similar buttons. | |
197 | ||
198 | :see: `wx.ContextHelp`, `wx.ContextHelpButton` | |
199 | ", ""); | |
4c42683a | 200 | |
ab1f7d2a RD |
201 | MustHaveApp(wxContextHelpButton); |
202 | ||
4f3449b4 RD |
203 | class wxContextHelpButton : public wxBitmapButton { |
204 | public: | |
2b9048c5 | 205 | %pythonAppend wxContextHelpButton "self._setOORInfo(self)" |
d14a1e28 | 206 | |
4c42683a RD |
207 | DocCtorStr( |
208 | wxContextHelpButton(wxWindow* parent, wxWindowID id = wxID_CONTEXT_HELP, | |
209 | const wxPoint& pos = wxDefaultPosition, | |
210 | const wxSize& size = wxDefaultSize, | |
211 | long style = wxBU_AUTODRAW), | |
d07d2bc9 | 212 | "Constructor, creating and showing a context help button.", ""); |
4f3449b4 RD |
213 | }; |
214 | ||
215 | ||
216 | //---------------------------------------------------------------------- | |
217 | ||
4c42683a RD |
218 | DocStr(wxHelpProvider, |
219 | "wx.HelpProvider is an abstract class used by a program | |
220 | implementing context-sensitive help to show the help text for the | |
221 | given window. | |
222 | ||
223 | The current help provider must be explicitly set by the | |
d07d2bc9 | 224 | application using wx.HelpProvider.Set().", ""); |
4c42683a | 225 | |
d14a1e28 | 226 | class wxHelpProvider |
4f3449b4 RD |
227 | { |
228 | public: | |
6cedc146 RD |
229 | |
230 | ~wxHelpProvider(); | |
231 | ||
232 | ||
214c4fbe RD |
233 | %disownarg( wxHelpProvider *helpProvider ); |
234 | %newobject Set; | |
4c42683a RD |
235 | DocDeclStr( |
236 | static wxHelpProvider *, Set(wxHelpProvider *helpProvider), | |
d07d2bc9 RD |
237 | "Sset the current, application-wide help provider. Returns the previous |
238 | one. Unlike some other classes, the help provider is not created on | |
239 | demand. This must be explicitly done by the application.", ""); | |
214c4fbe | 240 | %cleardisown( wxHelpProvider *helpProvider ); |
4c42683a RD |
241 | |
242 | DocDeclStr( | |
243 | static wxHelpProvider *, Get(), | |
d07d2bc9 | 244 | "Return the current application-wide help provider.", ""); |
4c42683a RD |
245 | |
246 | ||
247 | DocDeclStr( | |
248 | wxString , GetHelp(const wxWindow *window), | |
d07d2bc9 RD |
249 | "Gets the help string for this window. Its interpretation is dependent |
250 | on the help provider except that empty string always means that no | |
251 | help is associated with the window.", ""); | |
4c42683a RD |
252 | |
253 | DocDeclStr( | |
254 | bool , ShowHelp(wxWindow *window), | |
d07d2bc9 RD |
255 | "Shows help for the given window. Uses GetHelp internally if |
256 | applicable. Returns True if it was done, or False if no help was | |
257 | available for this window.", ""); | |
4c42683a RD |
258 | |
259 | DocDeclStr( | |
260 | void , AddHelp(wxWindow *window, const wxString& text), | |
d07d2bc9 | 261 | "Associates the text with the given window.", ""); |
4c42683a RD |
262 | |
263 | DocDeclStrName( | |
264 | void , AddHelp(wxWindowID id, const wxString& text), | |
d07d2bc9 RD |
265 | "This version associates the given text with all windows with this |
266 | id. May be used to set the same help string for all Cancel buttons in | |
267 | the application, for example.", "", | |
4c42683a RD |
268 | AddHelpById); |
269 | ||
270 | DocDeclStr( | |
271 | void , RemoveHelp(wxWindow* window), | |
d07d2bc9 RD |
272 | "Removes the association between the window pointer and the help |
273 | text. This is called by the wx.Window destructor. Without this, the | |
274 | table of help strings will fill up and when window pointers are | |
275 | reused, the wrong help string will be found.", ""); | |
4c42683a RD |
276 | |
277 | ||
214c4fbe | 278 | %pythonAppend Destroy "args[0].thisown = 0" |
d14a1e28 | 279 | %extend { void Destroy() { delete self; } } |
4f3449b4 RD |
280 | }; |
281 | ||
d14a1e28 | 282 | |
4f3449b4 RD |
283 | //---------------------------------------------------------------------- |
284 | ||
4c42683a | 285 | DocStr(wxSimpleHelpProvider, |
d07d2bc9 RD |
286 | "wx.SimpleHelpProvider is an implementation of `wx.HelpProvider` which |
287 | supports only plain text help strings, and shows the string associated | |
288 | with the control (if any) in a tooltip.", ""); | |
4c42683a | 289 | |
4f3449b4 RD |
290 | class wxSimpleHelpProvider : public wxHelpProvider |
291 | { | |
292 | public: | |
293 | wxSimpleHelpProvider(); | |
294 | }; | |
295 | ||
296 | ||
297 | //---------------------------------------------------------------------- | |
298 | ||
299 | // TODO: Add this once the wxHelpController is in wxPython... | |
300 | ||
301 | // class WXDLLEXPORT wxHelpControllerHelpProvider : public wxSimpleHelpProvider | |
302 | // { | |
303 | // public: | |
304 | // wxHelpControllerHelpProvider(wxHelpController* hc = NULL); | |
305 | // void SetHelpController(wxHelpController* hc); | |
306 | // wxHelpController* GetHelpController(); | |
307 | // }; | |
308 | ||
309 | ||
310 | ||
311 | ||
312 | //---------------------------------------------------------------------- | |
4f3449b4 | 313 | //--------------------------------------------------------------------------- |