Premultiply the alpha on wxMSW in the BitmapFromBuffer* functions so

[wxWidgets.git] / wxPython / src / _cshelp.i

diff --git a/wxPython/src/_cshelp.i b/wxPython/src/_cshelp.i
index 445db16569aeb1b1a74877380232fa5dd9bb82a9..9db181dfde7e942e42efae5da7e4dc7b994be437 100644 (file)
--- 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;
 
 %constant wxEventType wxEVT_HELP;
 %constant wxEventType wxEVT_DETAILED_HELP;
 


@@ -38,121 +34,146 @@ EVT_DETAILED_HELP_RANGE = wx.PyEventBinder( wxEVT_DETAILED_HELP, 2)
 //----------------------------------------------------------------------
 
 DocStr(wxHelpEvent,
 //----------------------------------------------------------------------
 
 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
+"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
     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:
 ");
 
 
 class wxHelpEvent : public wxCommandEvent
 {
 public:

+    // 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,
     DocCtorStr(
         wxHelpEvent(wxEventType type = wxEVT_NULL,
                     wxWindowID winid = 0,

-                    const wxPoint& pt = wxDefaultPosition),
-        "");
+                    const wxPoint& pt = wxDefaultPosition,
+                    Origin origin = Origin_Unknown ),
+        "", "");

     
 
     DocDeclStr(
         const wxPoint , GetPosition() const,
     
 
     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.");
+        "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),
     
     DocDeclStr(
         void , SetPosition(const wxPoint& pos),

-        "Sets the left-click position of the mouse, in screen coordinates.");
+        "Sets the left-click position of the mouse, in screen coordinates.", "");

     
 
     DocDeclStr(
         const wxString& , GetLink() const,
     
 
     DocDeclStr(
         const wxString& , GetLink() const,

-        "Get an optional link to further help");
+        "Get an optional link to further help", "");

     
     DocDeclStr(
         void , SetLink(const wxString& link),
     
     DocDeclStr(
         void , SetLink(const wxString& link),

-        "Set an optional link to further help");
+        "Set an optional link to further help", "");

     
 
     DocDeclStr(
         const wxString& , GetTarget() const,
     
 
     DocDeclStr(
         const wxString& , GetTarget() const,

-        "Get an optional target to display help in. E.g. a window specification");
+        "Get an optional target to display help in. E.g. a window specification", "");

     
     DocDeclStr(
         void , SetTarget(const wxString& target),
     
     DocDeclStr(
         void , SetTarget(const wxString& target),

-        "Set an optional target to display help in. E.g. a window specification");
+        "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),
+        "", "");
+        

 };
 
 //---------------------------------------------------------------------------
 
 
 DocStr(wxContextHelp,
 };
 
 //---------------------------------------------------------------------------
 
 
 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.
+"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:
 
 
 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.
+    * 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.DIALOG_EX_CONTEXTHELP on Windows).
-");       
+    * 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:
     DocCtorStr(
 
 class wxContextHelp : public wxObject {
 public:
     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(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();
 
     DocDeclStr(
         bool , BeginContextHelp(wxWindow* window = NULL),
     
     ~wxContextHelp();
 
     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.");
+        "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(),
     
     DocDeclStr(
         bool , EndContextHelp(),

-        "Ends context-sensitive help mode. Not normally called by the\n"
-        "application.");
+        "Ends context-sensitive help mode. Not normally called by the
+application.", "");

     
 };
 
     
 };
 


@@ -160,17 +181,20 @@ public:
 //----------------------------------------------------------------------
 
 DocStr(wxContextHelpButton,
 //----------------------------------------------------------------------
 
 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.
-");
+"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:
 
 class wxContextHelpButton : public wxBitmapButton {
 public:


@@ -181,7 +205,7 @@ public:
                             const wxPoint& pos = wxDefaultPosition,
                             const wxSize& size = wxDefaultSize,
                             long style = wxBU_AUTODRAW),
                             const wxPoint& pos = wxDefaultPosition,
                             const wxSize& size = wxDefaultSize,
                             long style = wxBU_AUTODRAW),

-        "Constructor, creating and showing a context help button.");
+        "Constructor, creating and showing a context help button.", "");

 };
 
 
 };
 
 


@@ -193,56 +217,71 @@ implementing context-sensitive help to show the help text for the
 given window.
 
 The current help provider must be explicitly set by the
 given window.
 
 The current help provider must be explicitly set by the

-application using wx.HelpProvider.Set().");
+application using wx.HelpProvider.Set().", "");

 
 class wxHelpProvider 
 {
 public:
 
 class wxHelpProvider 
 {
 public:

+    
+    ~wxHelpProvider();
+    
+    
+    %disownarg( wxHelpProvider *helpProvider );
+    %newobject Set;

     DocDeclStr(
         static wxHelpProvider *, Set(wxHelpProvider *helpProvider),
     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.");
+        "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(),
     
     DocDeclStr(
         static wxHelpProvider *, Get(),

-        "Return the current application-wide help provider.");
+        "Return the current application-wide help provider.", "");

     
 
     DocDeclStr(
         wxString , GetHelp(const wxWindow *window),
     
 
     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.");
+        "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),
     
     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.");
+        "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),
     
     DocDeclStr(
         void , AddHelp(wxWindow *window, const wxString& text),

-        "Associates the text with the given window.");
+        "Associates the text with the given window.", "");

 
     DocDeclStrName(
         void , AddHelp(wxWindowID id, const wxString& text),
 
     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.",
+        "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),
         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.");
+        "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.", "");

     
     
     
     

+    %pythonAppend Destroy "args[0].thisown = 0"

     %extend { void Destroy() { delete self; } }
 };
 
     %extend { void Destroy() { delete self; } }
 };
 


@@ -250,9 +289,9 @@ public:
 //----------------------------------------------------------------------
 
 DocStr(wxSimpleHelpProvider,
 //----------------------------------------------------------------------
 
 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.");
+"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
 {
 
 class wxSimpleHelpProvider : public wxHelpProvider
 {