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     %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
 131 DocStr(wxContextHelp,
 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.
 137
 138 There 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
 154 MustHaveApp(wxContextHelp);
 155
 156 class wxContextHelp : public wxObject {
 157 public:
 158     DocCtorStr(
 159         wxContextHelp(wxWindow* window = NULL, bool doNow = true),
 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.", "");
 164
 165     ~wxContextHelp();
 166
 167     DocDeclStr(
 168         bool , BeginContextHelp(wxWindow* window = NULL),
 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.", "");
 176
 177     DocDeclStr(
 178         bool , EndContextHelp(),
 179         "Ends context-sensitive help mode. Not normally called by the
 180 application.", "");
 181
 182 };
 183
 184
 185 //----------------------------------------------------------------------
 186
 187 DocStr(wxContextHelpButton,
 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 ", "");
 200
 201 MustHaveApp(wxContextHelpButton);
 202
 203 class wxContextHelpButton : public wxBitmapButton {
 204 public:
 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
 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
 224 application using wx.HelpProvider.Set().", "");
 225
 226 class wxHelpProvider
 227 {
 228 public:
 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
 238 one.  Unlike some other classes, the help provider is not created on
 239 demand. 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
 250 on the help provider except that empty string always means that no
 251 help is associated with the window.", "");
 252
 253     DocDeclStr(
 254         bool , ShowHelp(wxWindow *window),
 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.", "");
 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()
 264 internally if applicable), return true if it was done or false if no
 265 help 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
 276 id. May be used to set the same help string for all Cancel buttons in
 277 the application, for example.", "",
 278         AddHelpById);
 279
 280     DocDeclStr(
 281         void , RemoveHelp(wxWindow* window),
 282         "Removes the association between the window pointer and the help
 283 text. This is called by the wx.Window destructor. Without this, the
 284 table of help strings will fill up and when window pointers are
 285 reused, the wrong help string will be found.", "");
 286
 287
 288     %pythonAppend Destroy "args[0].thisown = 0"
 289     %extend { void Destroy() { delete self; } }
 290 };
 291
 292
 293 //----------------------------------------------------------------------
 294
 295 DocStr(wxSimpleHelpProvider,
 296 "wx.SimpleHelpProvider is an implementation of `wx.HelpProvider` which
 297 supports only plain text help strings, and shows the string associated
 298 with the control (if any) in a tooltip.", "");
 299
 300 class wxSimpleHelpProvider : public wxHelpProvider
 301 {
 302 public:
 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 //---------------------------------------------------------------------------