wxPython/src/_cshelp.i

   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 {
  28 EVT_HELP = wx.PyEventBinder( wxEVT_HELP, 1)
  29 EVT_HELP_RANGE = wx.PyEventBinder(  wxEVT_HELP, 2)
  30 EVT_DETAILED_HELP = wx.PyEventBinder( wxEVT_DETAILED_HELP, 1)
  31 EVT_DETAILED_HELP_RANGE = wx.PyEventBinder( wxEVT_DETAILED_HELP, 2)
  32 }
  33
  34 //----------------------------------------------------------------------
  35
  36 DocStr(wxHelpEvent,
  37 "A help event is sent when the user has requested context-sensitive
  38 help. This can either be caused by the application requesting
  39 context-sensitive help mode via wx.ContextHelp, or (on MS Windows) by
  40 the system generating a WM_HELP message when the user pressed F1 or
  41 clicked on the query button in a dialog caption.
  42
  43 A help event is sent to the window that the user clicked on, and is
  44 propagated up the window hierarchy until the event is processed or
  45 there are no more event handlers. The application should call
  46 event.GetId to check the identity of the clicked-on window, and then
  47 either show some suitable help or call event.Skip if the identifier is
  48 unrecognised. Calling Skip is important because it allows wxWindows to
  49 generate further events for ancestors of the clicked-on
  50 window. Otherwise it would be impossible to show help for container
  51 windows, since processing would stop after the first window found.",
  52 "
  53
  54 Events
  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
  66 class wxHelpEvent : public wxCommandEvent
  67 {
  68 public:
  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
  88 coordinates. This allows the application to position the help
  89 appropriately.", "");
  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 };
 123
 124 //---------------------------------------------------------------------------
 125
 126
 127 DocStr(wxContextHelp,
 128 "This class changes the cursor to a query and puts the application into
 129 a 'context-sensitive help mode'. When the user left-clicks on a window
 130 within the specified window, a ``EVT_HELP`` event is sent to that
 131 control, and the application may respond to it by popping up some
 132 help.
 133
 134 There are a couple of ways to invoke this behaviour implicitly:
 135
 136     * Use the wx.WS_EX_CONTEXTHELP extended style for a dialog or frame
 137       (Windows only). This will put a question mark in the titlebar,
 138       and Windows will put the application into context-sensitive help
 139       mode automatically, with further programming.
 140
 141     * Create a `wx.ContextHelpButton`, whose predefined behaviour is
 142       to create a context help object. Normally you will write your
 143       application so that this button is only added to a dialog for
 144       non-Windows platforms (use ``wx.WS_EX_CONTEXTHELP`` on
 145       Windows).
 146
 147 :see: `wx.ContextHelpButton`
 148 ", "");
 149
 150 MustHaveApp(wxContextHelp);
 151
 152 class wxContextHelp : public wxObject {
 153 public:
 154     DocCtorStr(
 155         wxContextHelp(wxWindow* window = NULL, bool doNow = true),
 156         "Constructs a context help object, calling BeginContextHelp if doNow is
 157 true (the default).
 158
 159 If window is None, the top window is used.", "");
 160
 161     ~wxContextHelp();
 162
 163     DocDeclStr(
 164         bool , BeginContextHelp(wxWindow* window = NULL),
 165         "Puts the application into context-sensitive help mode. window is the
 166 window which will be used to catch events; if NULL, the top window
 167 will be used.
 168
 169 Returns true if the application was successfully put into
 170 context-sensitive help mode. This function only returns when the event
 171 loop has finished.", "");
 172
 173     DocDeclStr(
 174         bool , EndContextHelp(),
 175         "Ends context-sensitive help mode. Not normally called by the
 176 application.", "");
 177
 178 };
 179
 180
 181 //----------------------------------------------------------------------
 182
 183 DocStr(wxContextHelpButton,
 184 "Instances of this class may be used to add a question mark button that
 185 when pressed, puts the application into context-help mode. It does
 186 this by creating a wx.ContextHelp object which itself generates a
 187 ``EVT_HELP`` event when the user clicks on a window.
 188
 189 On Windows, you may add a question-mark icon to a dialog by use of the
 190 ``wx.DIALOG_EX_CONTEXTHELP`` extra style, but on other platforms you
 191 will have to add a button explicitly, usually next to OK, Cancel or
 192 similar buttons.
 193
 194 :see: `wx.ContextHelp`, `wx.ContextHelpButton`
 195 ", "");
 196
 197 MustHaveApp(wxContextHelpButton);
 198
 199 class wxContextHelpButton : public wxBitmapButton {
 200 public:
 201     %pythonAppend wxContextHelpButton "self._setOORInfo(self)"
 202
 203     DocCtorStr(
 204         wxContextHelpButton(wxWindow* parent, wxWindowID id = wxID_CONTEXT_HELP,
 205                             const wxPoint& pos = wxDefaultPosition,
 206                             const wxSize& size = wxDefaultSize,
 207                             long style = wxBU_AUTODRAW),
 208         "Constructor, creating and showing a context help button.", "");
 209 };
 210
 211
 212 //----------------------------------------------------------------------
 213
 214 DocStr(wxHelpProvider,
 215 "wx.HelpProvider is an abstract class used by a program
 216 implementing context-sensitive help to show the help text for the
 217 given window.
 218
 219 The current help provider must be explicitly set by the
 220 application using wx.HelpProvider.Set().", "");
 221
 222 class wxHelpProvider
 223 {
 224 public:
 225
 226     ~wxHelpProvider();
 227
 228
 229     %disownarg( wxHelpProvider *helpProvider );
 230     %newobject Set;
 231     DocDeclStr(
 232         static wxHelpProvider *, Set(wxHelpProvider *helpProvider),
 233         "Sset the current, application-wide help provider. Returns the previous
 234 one.  Unlike some other classes, the help provider is not created on
 235 demand. This must be explicitly done by the application.", "");
 236     %cleardisown( wxHelpProvider *helpProvider );
 237
 238     DocDeclStr(
 239         static wxHelpProvider *, Get(),
 240         "Return the current application-wide help provider.", "");
 241
 242
 243     DocDeclStr(
 244         wxString , GetHelp(const wxWindow *window),
 245         "Gets the help string for this window. Its interpretation is dependent
 246 on the help provider except that empty string always means that no
 247 help is associated with the window.", "");
 248
 249     DocDeclStr(
 250         bool , ShowHelp(wxWindow *window),
 251         "Shows help for the given window. Uses GetHelp internally if
 252 applicable. Returns True if it was done, or False if no help was
 253 available for this window.", "");
 254
 255     DocDeclStr(
 256         virtual bool , ShowHelpAtPoint(wxWindowBase *window,
 257                                        const wxPoint& pt,
 258                                        wxHelpEvent::Origin origin),
 259         "Show help for the given window (uses window.GetHelpAtPoint()
 260 internally if applicable), return true if it was done or false if no
 261 help available for this window.", "");
 262
 263
 264
 265     DocDeclStr(
 266         void , AddHelp(wxWindow *window, const wxString& text),
 267         "Associates the text with the given window.", "");
 268
 269     DocDeclStrName(
 270         void , AddHelp(wxWindowID id, const wxString& text),
 271         "This version associates the given text with all windows with this
 272 id. May be used to set the same help string for all Cancel buttons in
 273 the application, for example.", "",
 274         AddHelpById);
 275
 276     DocDeclStr(
 277         void , RemoveHelp(wxWindow* window),
 278         "Removes the association between the window pointer and the help
 279 text. This is called by the wx.Window destructor. Without this, the
 280 table of help strings will fill up and when window pointers are
 281 reused, the wrong help string will be found.", "");
 282
 283
 284     %pythonAppend Destroy "args[0].thisown = 0"
 285     %extend { void Destroy() { delete self; } }
 286 };
 287
 288
 289 //----------------------------------------------------------------------
 290
 291 DocStr(wxSimpleHelpProvider,
 292 "wx.SimpleHelpProvider is an implementation of `wx.HelpProvider` which
 293 supports only plain text help strings, and shows the string associated
 294 with the control (if any) in a tooltip.", "");
 295
 296 class wxSimpleHelpProvider : public wxHelpProvider
 297 {
 298 public:
 299     wxSimpleHelpProvider();
 300 };
 301
 302
 303 //----------------------------------------------------------------------
 304
 305 // TODO: Add this once the wxHelpController is in wxPython...
 306
 307 //  class WXDLLEXPORT wxHelpControllerHelpProvider : public wxSimpleHelpProvider
 308 //  {
 309 //  public:
 310 //      wxHelpControllerHelpProvider(wxHelpController* hc = NULL);
 311 //      void SetHelpController(wxHelpController* hc);
 312 //      wxHelpController* GetHelpController();
 313 //  };
 314
 315
 316
 317
 318 //----------------------------------------------------------------------
 319 //---------------------------------------------------------------------------