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 enum {
  24     wxFRAME_EX_CONTEXTHELP,
  25     wxDIALOG_EX_CONTEXTHELP,
  26 };
  27 %constant wxEventType wxEVT_HELP;
  28 %constant wxEventType wxEVT_DETAILED_HELP;
  29
  30
  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 }
  37
  38 //----------------------------------------------------------------------
  39
  40 DocStr(wxHelpEvent,
  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     ==============      =========================================
  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
  64     ==============      =========================================
  65
  66 :see: `wx.ContextHelp`, `wx.ContextHelpButton`
  67 ");
  68
  69
  70 class wxHelpEvent : public wxCommandEvent
  71 {
  72 public:
  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
  81     DocCtorStr(
  82         wxHelpEvent(wxEventType type = wxEVT_NULL,
  83                     wxWindowID winid = 0,
  84                     const wxPoint& pt = wxDefaultPosition,
  85                     Origin origin = Origin_Unknown ),
  86         "", "");
  87
  88
  89     DocDeclStr(
  90         const wxPoint , GetPosition() const,
  91         "Returns the left-click position of the mouse, in screen
  92 coordinates. This allows the application to position the help
  93 appropriately.", "");
  94
  95     DocDeclStr(
  96         void , SetPosition(const wxPoint& pos),
  97         "Sets the left-click position of the mouse, in screen coordinates.", "");
  98
  99
 100     DocDeclStr(
 101         const wxString& , GetLink() const,
 102         "Get an optional link to further help", "");
 103
 104     DocDeclStr(
 105         void , SetLink(const wxString& link),
 106         "Set an optional link to further help", "");
 107
 108
 109     DocDeclStr(
 110         const wxString& , GetTarget() const,
 111         "Get an optional target to display help in. E.g. a window specification", "");
 112
 113     DocDeclStr(
 114         void , SetTarget(const wxString& target),
 115         "Set an optional target to display help in. E.g. a window specification", "");
 116
 117     // optional indication of the event source
 118     DocDeclStr(
 119         Origin , GetOrigin() const,
 120         "Optiononal indication of the source of the event.", "");
 121
 122     DocDeclStr(
 123         void , SetOrigin(Origin origin),
 124         "", "");
 125
 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.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).
 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         void , AddHelp(wxWindow *window, const wxString& text),
 261         "Associates the text with the given window.", "");
 262
 263     DocDeclStrName(
 264         void , AddHelp(wxWindowID id, const wxString& text),
 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.", "",
 268         AddHelpById);
 269
 270     DocDeclStr(
 271         void , RemoveHelp(wxWindow* window),
 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.", "");
 276
 277
 278     %pythonAppend Destroy "args[0].thisown = 0"
 279     %extend { void Destroy() { delete self; } }
 280 };
 281
 282
 283 //----------------------------------------------------------------------
 284
 285 DocStr(wxSimpleHelpProvider,
 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.", "");
 289
 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 //----------------------------------------------------------------------
 313 //---------------------------------------------------------------------------