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     DocCtorStr(
  74         wxHelpEvent(wxEventType type = wxEVT_NULL,
  75                     wxWindowID winid = 0,
  76                     const wxPoint& pt = wxDefaultPosition),
  77         "", "");
  78
  79
  80     DocDeclStr(
  81         const wxPoint , GetPosition() const,
  82         "Returns the left-click position of the mouse, in screen
  83 coordinates. This allows the application to position the help
  84 appropriately.", "");
  85
  86     DocDeclStr(
  87         void , SetPosition(const wxPoint& pos),
  88         "Sets the left-click position of the mouse, in screen coordinates.", "");
  89
  90
  91     DocDeclStr(
  92         const wxString& , GetLink() const,
  93         "Get an optional link to further help", "");
  94
  95     DocDeclStr(
  96         void , SetLink(const wxString& link),
  97         "Set an optional link to further help", "");
  98
  99
 100     DocDeclStr(
 101         const wxString& , GetTarget() const,
 102         "Get an optional target to display help in. E.g. a window specification", "");
 103
 104     DocDeclStr(
 105         void , SetTarget(const wxString& target),
 106         "Set an optional target to display help in. E.g. a window specification", "");
 107
 108 };
 109
 110 //---------------------------------------------------------------------------
 111
 112
 113 DocStr(wxContextHelp,
 114 "This class changes the cursor to a query and puts the application into
 115 a 'context-sensitive help mode'. When the user left-clicks on a window
 116 within the specified window, a ``EVT_HELP`` event is sent to that
 117 control, and the application may respond to it by popping up some
 118 help.
 119
 120 There are a couple of ways to invoke this behaviour implicitly:
 121
 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).
 132
 133 :see: `wx.ContextHelpButton`
 134 ", "");
 135
 136 class wxContextHelp : public wxObject {
 137 public:
 138     DocCtorStr(
 139         wxContextHelp(wxWindow* window = NULL, bool doNow = True),
 140         "Constructs a context help object, calling BeginContextHelp if doNow is
 141 true (the default).
 142
 143 If window is None, the top window is used.", "");
 144
 145     ~wxContextHelp();
 146
 147     DocDeclStr(
 148         bool , BeginContextHelp(wxWindow* window = NULL),
 149         "Puts the application into context-sensitive help mode. window is the
 150 window which will be used to catch events; if NULL, the top window
 151 will be used.
 152
 153 Returns true if the application was successfully put into
 154 context-sensitive help mode. This function only returns when the event
 155 loop has finished.", "");
 156
 157     DocDeclStr(
 158         bool , EndContextHelp(),
 159         "Ends context-sensitive help mode. Not normally called by the
 160 application.", "");
 161
 162 };
 163
 164
 165 //----------------------------------------------------------------------
 166
 167 DocStr(wxContextHelpButton,
 168 "Instances of this class may be used to add a question mark button that
 169 when pressed, puts the application into context-help mode. It does
 170 this by creating a wx.ContextHelp object which itself generates a
 171 ``EVT_HELP`` event when the user clicks on a window.
 172
 173 On Windows, you may add a question-mark icon to a dialog by use of the
 174 ``wx.DIALOG_EX_CONTEXTHELP`` extra style, but on other platforms you
 175 will have to add a button explicitly, usually next to OK, Cancel or
 176 similar buttons.
 177
 178 :see: `wx.ContextHelp`, `wx.ContextHelpButton`
 179 ", "");
 180
 181 class wxContextHelpButton : public wxBitmapButton {
 182 public:
 183     %pythonAppend wxContextHelpButton "self._setOORInfo(self)"
 184
 185     DocCtorStr(
 186         wxContextHelpButton(wxWindow* parent, wxWindowID id = wxID_CONTEXT_HELP,
 187                             const wxPoint& pos = wxDefaultPosition,
 188                             const wxSize& size = wxDefaultSize,
 189                             long style = wxBU_AUTODRAW),
 190         "Constructor, creating and showing a context help button.", "");
 191 };
 192
 193
 194 //----------------------------------------------------------------------
 195
 196 DocStr(wxHelpProvider,
 197 "wx.HelpProvider is an abstract class used by a program
 198 implementing context-sensitive help to show the help text for the
 199 given window.
 200
 201 The current help provider must be explicitly set by the
 202 application using wx.HelpProvider.Set().", "");
 203
 204 class wxHelpProvider
 205 {
 206 public:
 207     DocDeclStr(
 208         static wxHelpProvider *, Set(wxHelpProvider *helpProvider),
 209         "Sset the current, application-wide help provider. Returns the previous
 210 one.  Unlike some other classes, the help provider is not created on
 211 demand. This must be explicitly done by the application.", "");
 212
 213     DocDeclStr(
 214         static wxHelpProvider *, Get(),
 215         "Return the current application-wide help provider.", "");
 216
 217
 218     DocDeclStr(
 219         wxString , GetHelp(const wxWindow *window),
 220         "Gets the help string for this window. Its interpretation is dependent
 221 on the help provider except that empty string always means that no
 222 help is associated with the window.", "");
 223
 224     DocDeclStr(
 225         bool , ShowHelp(wxWindow *window),
 226         "Shows help for the given window. Uses GetHelp internally if
 227 applicable. Returns True if it was done, or False if no help was
 228 available for this window.", "");
 229
 230     DocDeclStr(
 231         void , AddHelp(wxWindow *window, const wxString& text),
 232         "Associates the text with the given window.", "");
 233
 234     DocDeclStrName(
 235         void , AddHelp(wxWindowID id, const wxString& text),
 236         "This version associates the given text with all windows with this
 237 id. May be used to set the same help string for all Cancel buttons in
 238 the application, for example.", "",
 239         AddHelpById);
 240
 241     DocDeclStr(
 242         void , RemoveHelp(wxWindow* window),
 243         "Removes the association between the window pointer and the help
 244 text. This is called by the wx.Window destructor. Without this, the
 245 table of help strings will fill up and when window pointers are
 246 reused, the wrong help string will be found.", "");
 247
 248
 249     %extend { void Destroy() { delete self; } }
 250 };
 251
 252
 253 //----------------------------------------------------------------------
 254
 255 DocStr(wxSimpleHelpProvider,
 256 "wx.SimpleHelpProvider is an implementation of `wx.HelpProvider` which
 257 supports only plain text help strings, and shows the string associated
 258 with the control (if any) in a tooltip.", "");
 259
 260 class wxSimpleHelpProvider : public wxHelpProvider
 261 {
 262 public:
 263     wxSimpleHelpProvider();
 264 };
 265
 266
 267 //----------------------------------------------------------------------
 268
 269 // TODO: Add this once the wxHelpController is in wxPython...
 270
 271 //  class WXDLLEXPORT wxHelpControllerHelpProvider : public wxSimpleHelpProvider
 272 //  {
 273 //  public:
 274 //      wxHelpControllerHelpProvider(wxHelpController* hc = NULL);
 275 //      void SetHelpController(wxHelpController* hc);
 276 //      wxHelpController* GetHelpController();
 277 //  };
 278
 279
 280
 281
 282 //----------------------------------------------------------------------
 283 //---------------------------------------------------------------------------