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 MustHaveApp(wxContextHelp);
 137
 138 class wxContextHelp : public wxObject {
 139 public:
 140     DocCtorStr(
 141         wxContextHelp(wxWindow* window = NULL, bool doNow = true),
 142         "Constructs a context help object, calling BeginContextHelp if doNow is
 143 true (the default).
 144
 145 If window is None, the top window is used.", "");
 146
 147     ~wxContextHelp();
 148
 149     DocDeclStr(
 150         bool , BeginContextHelp(wxWindow* window = NULL),
 151         "Puts the application into context-sensitive help mode. window is the
 152 window which will be used to catch events; if NULL, the top window
 153 will be used.
 154
 155 Returns true if the application was successfully put into
 156 context-sensitive help mode. This function only returns when the event
 157 loop has finished.", "");
 158
 159     DocDeclStr(
 160         bool , EndContextHelp(),
 161         "Ends context-sensitive help mode. Not normally called by the
 162 application.", "");
 163
 164 };
 165
 166
 167 //----------------------------------------------------------------------
 168
 169 DocStr(wxContextHelpButton,
 170 "Instances of this class may be used to add a question mark button that
 171 when pressed, puts the application into context-help mode. It does
 172 this by creating a wx.ContextHelp object which itself generates a
 173 ``EVT_HELP`` event when the user clicks on a window.
 174
 175 On 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
 177 will have to add a button explicitly, usually next to OK, Cancel or
 178 similar buttons.
 179
 180 :see: `wx.ContextHelp`, `wx.ContextHelpButton`
 181 ", "");
 182
 183 MustHaveApp(wxContextHelpButton);
 184
 185 class wxContextHelpButton : public wxBitmapButton {
 186 public:
 187     %pythonAppend wxContextHelpButton "self._setOORInfo(self)"
 188
 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),
 194         "Constructor, creating and showing a context help button.", "");
 195 };
 196
 197
 198 //----------------------------------------------------------------------
 199
 200 DocStr(wxHelpProvider,
 201 "wx.HelpProvider is an abstract class used by a program
 202 implementing context-sensitive help to show the help text for the
 203 given window.
 204
 205 The current help provider must be explicitly set by the
 206 application using wx.HelpProvider.Set().", "");
 207
 208 class wxHelpProvider
 209 {
 210 public:
 211
 212     ~wxHelpProvider();
 213
 214
 215     %disownarg( wxHelpProvider *helpProvider );
 216     %newobject Set;
 217     DocDeclStr(
 218         static wxHelpProvider *, Set(wxHelpProvider *helpProvider),
 219         "Sset the current, application-wide help provider. Returns the previous
 220 one.  Unlike some other classes, the help provider is not created on
 221 demand. This must be explicitly done by the application.", "");
 222     %cleardisown( wxHelpProvider *helpProvider );
 223
 224     DocDeclStr(
 225         static wxHelpProvider *, Get(),
 226         "Return the current application-wide help provider.", "");
 227
 228
 229     DocDeclStr(
 230         wxString , GetHelp(const wxWindow *window),
 231         "Gets the help string for this window. Its interpretation is dependent
 232 on the help provider except that empty string always means that no
 233 help is associated with the window.", "");
 234
 235     DocDeclStr(
 236         bool , ShowHelp(wxWindow *window),
 237         "Shows help for the given window. Uses GetHelp internally if
 238 applicable. Returns True if it was done, or False if no help was
 239 available for this window.", "");
 240
 241     DocDeclStr(
 242         void , AddHelp(wxWindow *window, const wxString& text),
 243         "Associates the text with the given window.", "");
 244
 245     DocDeclStrName(
 246         void , AddHelp(wxWindowID id, const wxString& text),
 247         "This version associates the given text with all windows with this
 248 id. May be used to set the same help string for all Cancel buttons in
 249 the application, for example.", "",
 250         AddHelpById);
 251
 252     DocDeclStr(
 253         void , RemoveHelp(wxWindow* window),
 254         "Removes the association between the window pointer and the help
 255 text. This is called by the wx.Window destructor. Without this, the
 256 table of help strings will fill up and when window pointers are
 257 reused, the wrong help string will be found.", "");
 258
 259
 260     %pythonAppend Destroy "args[0].thisown = 0"
 261     %extend { void Destroy() { delete self; } }
 262 };
 263
 264
 265 //----------------------------------------------------------------------
 266
 267 DocStr(wxSimpleHelpProvider,
 268 "wx.SimpleHelpProvider is an implementation of `wx.HelpProvider` which
 269 supports only plain text help strings, and shows the string associated
 270 with the control (if any) in a tooltip.", "");
 271
 272 class wxSimpleHelpProvider : public wxHelpProvider
 273 {
 274 public:
 275     wxSimpleHelpProvider();
 276 };
 277
 278
 279 //----------------------------------------------------------------------
 280
 281 // TODO: Add this once the wxHelpController is in wxPython...
 282
 283 //  class WXDLLEXPORT wxHelpControllerHelpProvider : public wxSimpleHelpProvider
 284 //  {
 285 //  public:
 286 //      wxHelpControllerHelpProvider(wxHelpController* hc = NULL);
 287 //      void SetHelpController(wxHelpController* hc);
 288 //      wxHelpController* GetHelpController();
 289 //  };
 290
 291
 292
 293
 294 //----------------------------------------------------------------------
 295 //---------------------------------------------------------------------------