X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/2b9048c56f0aa04b2adbb7813f9698abdda15184..89d1e2eeab15869685246c20dc260432ea548ea6:/wxPython/src/_cshelp.i diff --git a/wxPython/src/_cshelp.i b/wxPython/src/_cshelp.i index 21fbcbfda9..91b1d230e2 100644 --- a/wxPython/src/_cshelp.i +++ b/wxPython/src/_cshelp.i @@ -20,10 +20,6 @@ //---------------------------------------------------------------------- -enum { - wxFRAME_EX_CONTEXTHELP, - wxDIALOG_EX_CONTEXTHELP, -}; %constant wxEventType wxEVT_HELP; %constant wxEventType wxEVT_DETAILED_HELP; @@ -37,74 +33,270 @@ 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 + ============== ========================================= + +:see: `wx.ContextHelp`, `wx.ContextHelpButton` +"); + class wxHelpEvent : public wxCommandEvent { public: - wxHelpEvent(wxEventType type = wxEVT_NULL, - wxWindowID winid = 0, - const wxPoint& pt = wxDefaultPosition); + // how was this help event generated? + enum Origin + { + Origin_Unknown, // unrecognized event source + Origin_Keyboard, // event generated from F1 key press + Origin_HelpButton // event from [?] button on the title bar (Windows) + }; + + DocCtorStr( + wxHelpEvent(wxEventType type = wxEVT_NULL, + wxWindowID winid = 0, + const wxPoint& pt = wxDefaultPosition, + Origin origin = Origin_Unknown ), + "", ""); + + + DocDeclStr( + const wxPoint , GetPosition() const, + "Returns the left-click position of the mouse, in screen +coordinates. This allows the application to position the help +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", ""); + + // optional indication of the event source + DocDeclStr( + Origin , GetOrigin() const, + "Optiononal indication of the source of the event.", ""); + + DocDeclStr( + void , SetOrigin(Origin origin), + "", ""); + + %property(Link, GetLink, SetLink, doc="See `GetLink` and `SetLink`"); + %property(Origin, GetOrigin, SetOrigin, doc="See `GetOrigin` and `SetOrigin`"); + %property(Position, GetPosition, SetPosition, doc="See `GetPosition` and `SetPosition`"); + %property(Target, GetTarget, SetTarget, doc="See `GetTarget` and `SetTarget`"); +}; - // 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.WS_EX_CONTEXTHELP extended style for a dialog or frame + (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.WS_EX_CONTEXTHELP`` on + Windows). + +:see: `wx.ContextHelpButton` +", ""); + +MustHaveApp(wxContextHelp); 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 doNow is +true (the default). + +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 the +window which will be used to catch events; if NULL, the top window +will be used. + +Returns true if the application was successfully put into +context-sensitive help mode. This function only returns when the event +loop has finished.", ""); + + DocDeclStr( + bool , EndContextHelp(), + "Ends context-sensitive help mode. Not normally called by the +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. + +:see: `wx.ContextHelp`, `wx.ContextHelpButton` +", ""); + +MustHaveApp(wxContextHelpButton); + class wxContextHelpButton : public wxBitmapButton { public: %pythonAppend wxContextHelpButton "self._setOORInfo(self)" - wxContextHelpButton(wxWindow* parent, wxWindowID id = wxID_CONTEXT_HELP, - const wxPoint& pos = wxDefaultPosition, - const wxSize& size = wxDefaultSize, - long style = wxBU_AUTODRAW); + 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); - + + ~wxHelpProvider(); + + + %disownarg( wxHelpProvider *helpProvider ); + %newobject Set; + DocDeclStr( + static wxHelpProvider *, Set(wxHelpProvider *helpProvider), + "Sset the current, application-wide help provider. Returns the previous +one. Unlike some other classes, the help provider is not created on +demand. This must be explicitly done by the application.", ""); + %cleardisown( wxHelpProvider *helpProvider ); + + 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 dependent +on the help provider except that empty string always means that no +help is associated with the window.", ""); + + DocDeclStr( + bool , ShowHelp(wxWindow *window), + "Shows help for the given window. Uses GetHelp internally if +applicable. Returns True if it was done, or False if no help was +available for this window.", ""); + + DocDeclStr( + virtual bool , ShowHelpAtPoint(wxWindowBase *window, + const wxPoint& pt, + wxHelpEvent::Origin origin), + "Show help for the given window (uses window.GetHelpAtPoint() +internally if applicable), return true if it was done or false if no +help available 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 +id. May be used to set the same help string for all Cancel buttons in +the application, for example.", "", + AddHelpById); + + DocDeclStr( + void , RemoveHelp(wxWindow* window), + "Removes the association between the window pointer and the help +text. This is called by the wx.Window destructor. Without this, the +table of help strings will fill up and when window pointers are +reused, the wrong help string will be found.", ""); + + + %pythonPrepend Destroy "args[0].this.own(False)" %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: