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