preparation work for implementing images support in wxButton: move wxBitmapButton methods to the base class (enhancing/completing them in the process); there are no functionality changes yet (hopefully)

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@61051 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

interface/wx/button.h

@@ -36,6 +36,34 @@
            Process a wxEVT_COMMAND_BUTTON_CLICKED event, when the button is clicked.
     @endEventTable
 
+
+    Since version 2.9.1 wxButton supports showing both text and an image, see
+    SetBitmap() and SetBitmapLabel(), SetBitmapDisabled() &c methods. In the
+    previous wxWidgets versions this functionality was only available in (the
+    now trivial) wxBitmapButton class which was only capable of showing an
+    image without text.
+
+    A button may have either a single image for all states or different images
+    for the following states:
+    @li @b normal: the default state
+    @li @b disabled: bitmap shown when the button is disabled.
+    @li @b pressed: bitmap shown when the button is pushed (e.g. while the user
+        keeps the mouse button pressed on it)
+    @li @b focus: bitmap shown when the button has keyboard focus (but is not
+        pressed as in this case the button is in the pressed state)
+    @li @b current: bitmap shown when the mouse is over the button (but it is
+        not pressed although it may have focus). Notice that if current bitmap
+        is not specified but the current platform UI uses hover images for the
+        buttons (such as Windows XP or GTK+), then the focus bitmap is used for
+        hover state as well. This makes it possible to set focus bitmap only to
+        get reasonably good behaviour on all platforms.
+
+    All of the bitmaps must be of the same size and the normal bitmap must be
+    set first (to a valid bitmap), before setting any other ones.
+
+    The position of the image inside the button be configured using
+    SetBitmapPosition(). By default the image is on the left of the text.
+
     @library{wxcore}
     @category{ctrl}
     @appearance{button.png}
@@ -87,11 +115,6 @@ public:
              const wxValidator& validator = wxDefaultValidator,
              const wxString& name = wxButtonNameStr);
 
-    /**
-        Destructor, destroying the button.
-    */
-    virtual ~wxButton();
-
     /**
         Button creation function for two-step creation.
         For more details, see wxButton().
@@ -104,6 +127,69 @@ public:
                 const wxValidator& validator = wxDefaultValidator,
                 const wxString& name = wxButtonNameStr);
 
+    /**
+        Return the bitmap shown by the button.
+
+        The returned bitmap may be invalid only if the button doesn't show any
+        images.
+
+        @see SetBitmap()
+
+        @since 2.9.1
+     */
+    wxBitmap GetBitmap() const;
+
+    /**
+        Returns the bitmap used when the mouse is over the button, which may be
+        invalid.
+
+        @see SetBitmapCurrent()
+
+        @since 2.9.1 (available as wxBitmapButton::GetBitmapHover() in previous
+            versions)
+    */
+    wxBitmap GetBitmapCurrent() const;
+
+    /**
+        Returns the bitmap for the disabled state, which may be invalid.
+
+        @see SetBitmapDisabled()
+
+        @since 2.9.1 (available in wxBitmapButton only in previous versions)
+    */
+    wxBitmap GetBitmapDisabled() const;
+
+    /**
+        Returns the bitmap for the focused state, which may be invalid.
+
+        @see SetBitmapFocus()
+
+        @since 2.9.1 (available in wxBitmapButton only in previous versions)
+    */
+    wxBitmap GetBitmapFocus() const;
+
+    /**
+        Returns the bitmap for the normal state.
+
+        This is exactly the same as GetBitmap() but uses a name
+        backwards-compatible with wxBitmapButton.
+
+        @see SetBitmap(), SetBitmapLabel()
+
+        @since 2.9.1 (available in wxBitmapButton only in previous versions)
+    */
+    wxBitmap GetBitmapLabel() const;
+
+    /**
+        Returns the bitmap for the pressed state, which may be invalid.
+
+        @see SetBitmapPressed()
+
+        @since 2.9.1 (available as wxBitmapButton::GetBitmapSelected() in
+            previous versions)
+    */
+    wxBitmap GetBitmapPressed() const;
+
     /**
         Returns the default size for the buttons. It is advised to make all the dialog
         buttons of the same size and this function allows to retrieve the (platform and
@@ -118,6 +204,109 @@ public:
     */
     wxString GetLabel() const;
 
+    /**
+        Sets the bitmap to display in the button.
+
+        The bitmap is displayed together with the button label. This method
+        sets up a single bitmap which is used in all button states, use
+        SetBitmapDisabled(), SetBitmapPressed(), SetBitmapCurrent() or
+        SetBitmapFocus() to change the individual images used in different
+        states.
+
+        @param bitmap
+            The bitmap to display in the button. May be invalid to remove any
+            currently displayed bitmap.
+        @param dir
+            The position of the bitmap inside the button. By default it is
+            positioned to the left of the text, near to the left button border.
+            Other possible values include wxRIGHT, wxTOP and wxBOTTOM.
+
+        @see SetBitmapPosition(), SetBitmapMargins()
+
+        @since 2.9.1
+     */
+    void SetBitmap(const wxBitmap& bitmap, wxDirection dir = wxLEFT);
+
+    /**
+        Sets the bitmap to be shown when the mouse is over the button.
+
+        @see GetBitmapCurrent()
+
+        @since 2.9.1 (available as wxBitmapButton::SetBitmapHover() in previous
+            versions)
+    */
+    void SetBitmapCurrent(const wxBitmap& bitmap);
+
+    /**
+        Sets the bitmap for the disabled button appearance.
+
+        @see GetBitmapDisabled(), SetBitmapLabel(),
+             SetBitmapPressed(), SetBitmapFocus()
+
+        @since 2.9.1 (available in wxBitmapButton only in previous versions)
+    */
+    void SetBitmapDisabled(const wxBitmap& bitmap);
+
+    /**
+        Sets the bitmap for the button appearance when it has the keyboard
+        focus.
+
+        @see GetBitmapFocus(), SetBitmapLabel(),
+             SetBitmapPressed(), SetBitmapDisabled()
+
+        @since 2.9.1 (available in wxBitmapButton only in previous versions)
+    */
+    void SetBitmapFocus(const wxBitmap& bitmap);
+
+    /**
+        Sets the bitmap label for the button.
+
+        @remarks This is the bitmap used for the unselected state, and for all
+                 other states if no other bitmaps are provided.
+
+        @see SetBitmap(), GetBitmapLabel()
+
+        @since 2.9.1 (available in wxBitmapButton only in previous versions)
+    */
+    void SetBitmapLabel(const wxBitmap& bitmap);
+
+    /**
+        Sets the bitmap for the selected (depressed) button appearance.
+
+        @since 2.9.1 (available as wxBitmapButton::SetBitmapSelected() in
+            previous versions)
+    */
+    void SetBitmapPressed(const wxBitmap& bitmap);
+
+    /**
+        Set the margins between the bitmap and the text of the button.
+
+        This method is currently only implemented under MSW. If it is not
+        called, default margin is used around the bitmap.
+
+        @see SetBitmap(), SetBitmapPosition()
+
+        @since 2.9.1
+     */
+    //@{
+    void SetBitmapMargins(wxCoord x, wxCoord y);
+    void SetBitmapMargins(const wxSize& sz);
+    //@}
+
+    /**
+        Set the position at which the bitmap is displayed.
+
+        This method should only be called if the button does have an associated
+        bitmap.
+
+        @since 2.9.1
+
+        @param dir
+            Direction in which the bitmap should be positioned, one of wxLEFT,
+            wxRIGHT, wxTOP or wxBOTTOM.
+     */
+    void SetBitmapPosition(wxDirection dir);
+
     /**
         This sets the button to be the default item in its top-level window
         (e.g. the panel or the dialog box containing it).