X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/d14a1e28567de23c586bc80017073d0c39f8d18f..3cebfef17b54f9dacc386f090827b8badb2773d2:/wxPython/src/_cshelp.i diff --git a/wxPython/src/_cshelp.i b/wxPython/src/_cshelp.i index f39727a654..445db16569 100644 --- a/wxPython/src/_cshelp.i +++ b/wxPython/src/_cshelp.i @@ -37,74 +37,223 @@ EVT_DETAILED_HELP_RANGE = wx.PyEventBinder( wxEVT_DETAILED_HELP, 2) //---------------------------------------------------------------------- -// A help event is sent when the user clicks on a window in context-help mode. +DocStr(wxHelpEvent, +"A help event is sent when the user has requested +context-sensitive help. This can either be caused by the +application requesting context-sensitive help mode via +wx.ContextHelp, or (on MS Windows) by the system generating a +WM_HELP message when the user pressed F1 or clicked on the query +button in a dialog caption. + +A help event is sent to the window that the user clicked on, and +is propagated up the window hierarchy until the event is +processed or there are no more event handlers. The application +should call event.GetId to check the identity of the clicked-on +window, and then either show some suitable help or call +event.Skip if the identifier is unrecognised. Calling Skip is +important because it allows wxWindows to generate further events +for ancestors of the clicked-on window. Otherwise it would be +impossible to show help for container windows, since processing +would stop after the first window found. + + Events + EVT_HELP Sent when the user has requested context- + sensitive help. + EVT_HELP_RANGE Allows to catch EVT_HELP for a range of IDs +"); + class wxHelpEvent : public wxCommandEvent { public: - wxHelpEvent(wxEventType type = wxEVT_NULL, - wxWindowID winid = 0, - const wxPoint& pt = wxDefaultPosition); + DocCtorStr( + wxHelpEvent(wxEventType type = wxEVT_NULL, + wxWindowID winid = 0, + const wxPoint& pt = wxDefaultPosition), + ""); + + + DocDeclStr( + const wxPoint , GetPosition() const, + "Returns the left-click position of the mouse, in screen\n" + "coordinates. This allows the application to position the help\n" + "appropriately."); + + DocDeclStr( + void , SetPosition(const wxPoint& pos), + "Sets the left-click position of the mouse, in screen coordinates."); + + + DocDeclStr( + const wxString& , GetLink() const, + "Get an optional link to further help"); + + DocDeclStr( + void , SetLink(const wxString& link), + "Set an optional link to further help"); + + + DocDeclStr( + const wxString& , GetTarget() const, + "Get an optional target to display help in. E.g. a window specification"); + + DocDeclStr( + void , SetTarget(const wxString& target), + "Set an optional target to display help in. E.g. a window specification"); + +}; - // Position of event (in screen coordinates) - const wxPoint& GetPosition() const; - void SetPosition(const wxPoint& pos); +//--------------------------------------------------------------------------- - // Optional link to further help - const wxString& GetLink() const; - void SetLink(const wxString& link); - // Optional target to display help in. E.g. a window specification - const wxString& GetTarget() const; - void SetTarget(const wxString& target); -}; +DocStr(wxContextHelp, +"This class changes the cursor to a query and puts the application +into a 'context-sensitive help mode'. When the user left-clicks +on a window within the specified window, a EVT_HELP event is sent +to that control, and the application may respond to it by popping +up some help. -//--------------------------------------------------------------------------- +There are a couple of ways to invoke this behaviour implicitly: + + * Use the wx.DIALOG_EX_CONTEXTHELP extended style for a + dialog (Windows only). This will put a question mark in the + titlebar, and Windows will put the application into + context-sensitive help mode automatically, with further + programming. + + * Create a wx.ContextHelpButton, whose predefined behaviour + is to create a context help object. Normally you will write + your application so that this button is only added to a + dialog for non-Windows platforms (use + wx.DIALOG_EX_CONTEXTHELP on Windows). +"); class wxContextHelp : public wxObject { public: - wxContextHelp(wxWindow* window = NULL, bool doNow = TRUE); + DocCtorStr( + wxContextHelp(wxWindow* window = NULL, bool doNow = True), + "Constructs a context help object, calling BeginContextHelp if\n" + "doNow is true (the default).\n" + "\n" + "If window is None, the top window is used."); + ~wxContextHelp(); - bool BeginContextHelp(wxWindow* window = NULL); - bool EndContextHelp(); + DocDeclStr( + bool , BeginContextHelp(wxWindow* window = NULL), + "Puts the application into context-sensitive help mode. window is\n" + "the window which will be used to catch events; if NULL, the top\n" + "window will be used.\n" + "\n" + "Returns true if the application was successfully put into\n" + "context-sensitive help mode. This function only returns when the\n" + "event loop has finished."); + + DocDeclStr( + bool , EndContextHelp(), + "Ends context-sensitive help mode. Not normally called by the\n" + "application."); + }; //---------------------------------------------------------------------- +DocStr(wxContextHelpButton, +"Instances of this class may be used to add a question mark button +that when pressed, puts the application into context-help +mode. It does this by creating a wx.ContextHelp object which +itself generates a EVT_HELP event when the user clicks on a +window. + +On Windows, you may add a question-mark icon to a dialog by use +of the wx.DIALOG_EX_CONTEXTHELP extra style, but on other +platforms you will have to add a button explicitly, usually next +to OK, Cancel or similar buttons. +"); + class wxContextHelpButton : public wxBitmapButton { public: - %addtofunc wxContextHelpButton "self._setOORInfo(self)" - - wxContextHelpButton(wxWindow* parent, wxWindowID id = wxID_CONTEXT_HELP, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxBU_AUTODRAW); + %pythonAppend wxContextHelpButton "self._setOORInfo(self)" + + DocCtorStr( + wxContextHelpButton(wxWindow* parent, wxWindowID id = wxID_CONTEXT_HELP, + const wxPoint& pos = wxDefaultPosition, + const wxSize& size = wxDefaultSize, + long style = wxBU_AUTODRAW), + "Constructor, creating and showing a context help button."); }; //---------------------------------------------------------------------- +DocStr(wxHelpProvider, +"wx.HelpProvider is an abstract class used by a program +implementing context-sensitive help to show the help text for the +given window. + +The current help provider must be explicitly set by the +application using wx.HelpProvider.Set()."); + class wxHelpProvider { public: - static wxHelpProvider *Set(wxHelpProvider *helpProvider); - static wxHelpProvider *Get(); - - // Virtuals... - wxString GetHelp(const wxWindow *window); - bool ShowHelp(wxWindow *window); - void AddHelp(wxWindow *window, const wxString& text); - %name(AddHelpById)void AddHelp(wxWindowID id, const wxString& text); - + DocDeclStr( + static wxHelpProvider *, Set(wxHelpProvider *helpProvider), + "Sset the current, application-wide help provider. Returns the\n" + "previous one. Unlike some other classes, the help provider is\n" + "not created on demand. This must be explicitly done by the\n" + "application."); + + DocDeclStr( + static wxHelpProvider *, Get(), + "Return the current application-wide help provider."); + + + DocDeclStr( + wxString , GetHelp(const wxWindow *window), + "Gets the help string for this window. Its interpretation is\n" + "dependent on the help provider except that empty string always\n" + "means that no help is associated with the window."); + + DocDeclStr( + bool , ShowHelp(wxWindow *window), + "Shows help for the given window. Uses GetHelp internally if\n" + "applicable.\n" + "\n" + "Returns true if it was done, or false if no help was available\n" + "for this window."); + + DocDeclStr( + void , AddHelp(wxWindow *window, const wxString& text), + "Associates the text with the given window."); + + DocDeclStrName( + void , AddHelp(wxWindowID id, const wxString& text), + "This version associates the given text with all windows with this\n" + "id. May be used to set the same help string for all Cancel\n" + "buttons in the application, for example.", + AddHelpById); + + DocDeclStr( + void , RemoveHelp(wxWindow* window), + "Removes the association between the window pointer and the help\n" + "text. This is called by the wx.Window destructor. Without this,\n" + "the table of help strings will fill up and when window pointers\n" + "are reused, the wrong help string will be found."); + + %extend { void Destroy() { delete self; } } - }; //---------------------------------------------------------------------- +DocStr(wxSimpleHelpProvider, +"wx.SimpleHelpProvider is an implementation of wx.HelpProvider +which supports only plain text help strings, and shows the string +associated with the control (if any) in a tooltip."); + class wxSimpleHelpProvider : public wxHelpProvider { public: