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