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