added SetHoverBitmap() and implemented it under wxMSW; extended the docs

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

docs/changes.txt

@@ -25,6 +25,7 @@ All (GUI):
 - Added parent window parameter to wxHelpController constructor
   and added SetParentWindow/GetParentWindow.
 - wxMultiChoiceDialog uses now wxCheckListBox if possible, wxListBox if not.
+- Added wxBitmapButton::SetHoverBitmap()
 
 wxMSW:
 

docs/latex/wx/bbutton.tex

@@ -4,6 +4,7 @@ A bitmap button is a control that contains a bitmap.
 It may be placed on a \helpref{dialog box}{wxdialog} or \helpref{panel}{wxpanel}, or indeed
 almost any other window.
 
+
 \wxheading{Derived from}
 
 \helpref{wxButton}{wxbutton}\\
@@ -12,16 +13,37 @@ almost any other window.
 \helpref{wxEvtHandler}{wxevthandler}\\
 \helpref{wxObject}{wxobject}
 
+
 \wxheading{Include files}
 
 <wx/bmpbuttn.h>
 
+
 \wxheading{Remarks}
 
 A bitmap button can be supplied with a single bitmap, and wxWidgets will draw
 all button states using this bitmap. If the application needs more control, additional bitmaps for
 the selected state, unpressed focused state, and greyed-out state may be supplied.
 
+
+\wxheading{Button states}
+
+This class supports bitmaps for several different states:
+
+\twocolwidtha{5cm}
+\twocolitem{\windowstyle{normal}}{This is the bitmap shown in the default state,
+it must be always valid while all the other bitmaps are optional and don't have
+to be set.}
+\twocolitem{\windowstyle{disabled}}{Bitmap shown when the button is disabled.}
+\twocolitem{\windowstyle{selected}}{Bitmap shown when the button is pushed
+(e.g. while the user keeps the mouse button pressed on it)}
+\twocolitem{\windowstyle{focus}}{Bitmap shown when the button has keyboard
+focus but is not pressed.}
+\twocolitem{\windowstyle{hover}}{Bitmap shown when the mouse is over the
+button (but it is not pressed).}
+\end{twocollist}
+
+
 \wxheading{Window styles}
 
 \twocolwidtha{5cm}
@@ -42,6 +64,7 @@ don't have any minimal standard size by default.
 
 See also \helpref{window styles overview}{windowstyles}.
 
+
 \wxheading{Event handling}
 
 \twocolwidtha{7cm}
@@ -50,12 +73,16 @@ See also \helpref{window styles overview}{windowstyles}.
 when the button is clicked.}
 \end{twocollist}
 
+
 \wxheading{See also}
 
 \helpref{wxButton}{wxbutton}
 
+
+
 \latexignore{\rtfignore{\wxheading{Members}}}
 
+
 \membersection{wxBitmapButton::wxBitmapButton}\label{wxbitmapbuttonctor}
 
 \func{}{wxBitmapButton}{\void}
@@ -107,12 +134,14 @@ Note that the bitmap passed is smaller than the actual button created.
 
 \helpref{wxBitmapButton::Create}{wxbitmapbuttoncreate}, \helpref{wxValidator}{wxvalidator}
 
+
 \membersection{wxBitmapButton::\destruct{wxBitmapButton}}\label{wxbitmapbuttondtor}
 
 \func{}{\destruct{wxBitmapButton}}{\void}
 
 Destructor, destroying the button.
 
+
 \membersection{wxBitmapButton::Create}\label{wxbitmapbuttoncreate}
 
 \func{bool}{Create}{\param{wxWindow* }{parent}, \param{wxWindowID}{ id}, \param{const wxBitmap\& }{bitmap},\rtfsp
@@ -121,11 +150,13 @@ Destructor, destroying the button.
 
 Button creation function for two-step creation. For more details, see \helpref{wxBitmapButton::wxBitmapButton}{wxbitmapbuttonctor}.
 
+
 \membersection{wxBitmapButton::GetBitmapDisabled}\label{wxbitmapbuttongetbitmapdisabled}
 
-\constfunc{wxBitmap\&}{GetBitmapDisabled}{\void}
+\constfunc{const wxBitmap\&}{GetBitmapDisabled}{\void}
+\func{wxBitmap\&}{GetBitmapDisabled}{\void}
 
-Returns the bitmap for the disabled state.
+Returns the bitmap for the disabled state, may be invalid.
 
 \wxheading{Return value}
 
@@ -135,11 +166,13 @@ A reference to the disabled state bitmap.
 
 \helpref{wxBitmapButton::SetBitmapDisabled}{wxbitmapbuttonsetbitmapdisabled}
 
+
 \membersection{wxBitmapButton::GetBitmapFocus}\label{wxbitmapbuttongetbitmapfocus}
 
-\constfunc{wxBitmap\&}{GetBitmapFocus}{\void}
+\constfunc{const wxBitmap\&}{GetBitmapFocus}{\void}
+\func{wxBitmap\&}{GetBitmapFocus}{\void}
 
-Returns the bitmap for the focused state.
+Returns the bitmap for the focused state, may be invalid.
 
 \wxheading{Return value}
 
@@ -149,11 +182,25 @@ A reference to the focused state bitmap.
 
 \helpref{wxBitmapButton::SetBitmapFocus}{wxbitmapbuttonsetbitmapfocus}
 
+
+\membersection{wxBitmapButton::GetBitmapHover}\label{wxbitmapbuttongetbitmaphover}
+
+\constfunc{const wxBitmap\&}{GetBitmapHover}{\void}
+\func{wxBitmap\&}{GetBitmapHover}{\void}
+
+Returns the bitmap used when the mouse is over the button, may be invalid.
+
+\wxheading{See also}
+
+\helpref{wxBitmapButton::SetBitmapHover}{wxbitmapbuttonsetbitmaphover}
+
+
 \membersection{wxBitmapButton::GetBitmapLabel}\label{wxbitmapbuttongetbitmaplabel}
 
-\constfunc{wxBitmap\&}{GetBitmapLabel}{\void}
+\constfunc{const wxBitmap\&}{GetBitmapLabel}{\void}
+\func{wxBitmap\&}{GetBitmapLabel}{\void}
 
-Returns the label bitmap (the one passed to the constructor).
+Returns the label bitmap (the one passed to the constructor), always valid.
 
 \wxheading{Return value}
 
@@ -163,11 +210,13 @@ A reference to the button's label bitmap.
 
 \helpref{wxBitmapButton::SetBitmapLabel}{wxbitmapbuttonsetbitmaplabel}
 
+
 \membersection{wxBitmapButton::GetBitmapSelected}\label{wxbitmapbuttongetbitmapselected}
 
 \constfunc{wxBitmap\&}{GetBitmapSelected}{\void}
+\func{wxBitmap\&}{GetBitmapSelected}{\void}
 
-Returns the bitmap for the selected state.
+Returns the bitmap for the pushed button state, may be invalid.
 
 \wxheading{Return value}
 
@@ -177,6 +226,7 @@ A reference to the selected state bitmap.
 
 \helpref{wxBitmapButton::SetBitmapSelected}{wxbitmapbuttonsetbitmapselected}
 
+
 \membersection{wxBitmapButton::SetBitmapDisabled}\label{wxbitmapbuttonsetbitmapdisabled}
 
 \func{void}{SetBitmapDisabled}{\param{const wxBitmap\& }{bitmap}}
@@ -194,6 +244,7 @@ Sets the bitmap for the disabled button appearance.
 \helpref{wxBitmapButton::SetBitmapSelected}{wxbitmapbuttonsetbitmapselected},\rtfsp
 \helpref{wxBitmapButton::SetBitmapFocus}{wxbitmapbuttonsetbitmapfocus}
 
+
 \membersection{wxBitmapButton::SetBitmapFocus}\label{wxbitmapbuttonsetbitmapfocus}
 
 \func{void}{SetBitmapFocus}{\param{const wxBitmap\& }{bitmap}}
@@ -211,6 +262,19 @@ Sets the bitmap for the button appearance when it has the keyboard focus.
 \helpref{wxBitmapButton::SetBitmapSelected}{wxbitmapbuttonsetbitmapselected},\rtfsp
 \helpref{wxBitmapButton::SetBitmapDisabled}{wxbitmapbuttonsetbitmapdisabled}
 
+
+\membersection{wxBitmapButton::SetBitmapHover}\label{wxbitmapbuttonsetbitmaphover}
+
+\func{void}{SetBitmapHover}{\param{const wxBitmap\& }{bitmap}}
+
+Sets the bitmap to be shown when the mouse is over the button.
+
+\newsince{2.7.0} and the hover bitmap is currently only supported in wxMSW. 
+
+\wxheading{See also}
+
+\helpref{wxBitmapButton::GetBitmapHover}{wxbitmapbuttongetbitmaphover}
+
 \membersection{wxBitmapButton::SetBitmapLabel}\label{wxbitmapbuttonsetbitmaplabel}
 
 \func{void}{SetBitmapLabel}{\param{const wxBitmap\& }{bitmap}}
@@ -230,6 +294,7 @@ if no other bitmaps are provided.
 
 \helpref{wxBitmapButton::GetBitmapLabel}{wxbitmapbuttongetbitmaplabel}
 
+
 \membersection{wxBitmapButton::SetBitmapSelected}\label{wxbitmapbuttonsetbitmapselected}
 
 \func{void}{SetBitmapSelected}{\param{const wxBitmap\& }{bitmap}}

include/wx/bmpbuttn.h

@@ -44,16 +44,20 @@ public:
         { m_bmpFocus = focus; OnSetBitmap(); };
     void SetBitmapDisabled(const wxBitmap& disabled)
         { m_bmpDisabled = disabled; OnSetBitmap(); };
+    void SetBitmapHover(const wxBitmap& hover)
+        { m_bmpHover = hover; OnSetBitmap(); }
 
     // retrieve the bitmaps
     const wxBitmap& GetBitmapLabel() const { return m_bmpNormal; }
     const wxBitmap& GetBitmapSelected() const { return m_bmpSelected; }
     const wxBitmap& GetBitmapFocus() const { return m_bmpFocus; }
     const wxBitmap& GetBitmapDisabled() const { return m_bmpDisabled; }
+    const wxBitmap& GetBitmapHover() const { return m_bmpHover; }
     wxBitmap& GetBitmapLabel() { return m_bmpNormal; }
     wxBitmap& GetBitmapSelected() { return m_bmpSelected; }
     wxBitmap& GetBitmapFocus() { return m_bmpFocus; }
     wxBitmap& GetBitmapDisabled() { return m_bmpDisabled; }
+    wxBitmap& GetBitmapHover() { return m_bmpHover; }
 
     // set/get the margins around the button
     virtual void SetMargins(int x, int y) { m_marginX = x; m_marginY = y; }
@@ -78,7 +82,8 @@ protected:
     wxBitmap m_bmpNormal,
              m_bmpSelected,
              m_bmpFocus,
-             m_bmpDisabled;
+             m_bmpDisabled,
+             m_bmpHover;
 
     // the margins around the bitmap
     int m_marginX,

include/wx/msw/bmpbuttn.h

@@ -16,9 +16,7 @@
 #include "wx/bitmap.h"
 #include "wx/brush.h"
 
-#define wxDEFAULT_BUTTON_MARGIN 4
+class WXDLLEXPORT wxBitmapButton : public wxBitmapButtonBase
-
-class WXDLLEXPORT wxBitmapButton: public wxBitmapButtonBase
 {
 public:
     wxBitmapButton() { }
@@ -58,6 +56,9 @@ protected:
     // invalidate m_brushDisabled when system colours change
     void OnSysColourChanged(wxSysColourChangedEvent& event);
 
+    // change the currently bitmap if we have a hover one
+    void OnMouseEnterOrLeave(wxMouseEvent& event);
+
 
     // the brush we use to draw disabled buttons
     wxBrush m_brushDisabled;
@@ -67,5 +68,4 @@ protected:
     DECLARE_DYNAMIC_CLASS_NO_COPY(wxBitmapButton)
 };
 
-#endif
+#endif // _WX_BMPBUTTN_H_
-    // _WX_BMPBUTTN_H_

samples/widgets/button.cpp

@@ -333,6 +333,7 @@ void ButtonWidgetsPage::CreateButton()
         bbtn->SetBitmapSelected(CreateBitmap(_T("pushed")));
         bbtn->SetBitmapFocus(CreateBitmap(_T("focused")));
         bbtn->SetBitmapDisabled(CreateBitmap(_T("disabled")));
+        bbtn->SetBitmapHover(CreateBitmap(_T("hover")));
         m_button = bbtn;
     }
     else // normal button

src/msw/bmpbuttn.cpp

@@ -87,6 +87,8 @@ IMPLEMENT_DYNAMIC_CLASS(wxBitmapButton, wxButton)
 
 BEGIN_EVENT_TABLE(wxBitmapButton, wxBitmapButtonBase)
     EVT_SYS_COLOUR_CHANGED(wxBitmapButton::OnSysColourChanged)
+    EVT_ENTER_WINDOW(wxBitmapButton::OnMouseEnterOrLeave)
+    EVT_LEAVE_WINDOW(wxBitmapButton::OnMouseEnterOrLeave)
 END_EVENT_TABLE()
 
 /*
@@ -121,8 +123,8 @@ bool wxBitmapButton::Create(wxWindow *parent, wxWindowID id,
 
     if ( style & wxBU_AUTODRAW )
     {
-        m_marginX = wxDEFAULT_BUTTON_MARGIN;
+        m_marginX =
-        m_marginY = wxDEFAULT_BUTTON_MARGIN;
+        m_marginY = 4;
     }
 
     if (id == wxID_ANY)
@@ -194,6 +196,14 @@ void wxBitmapButton::OnSysColourChanged(wxSysColourChangedEvent& event)
     event.Skip();
 }
 
+void wxBitmapButton::OnMouseEnterOrLeave(wxMouseEvent& event)
+{
+    if ( IsEnabled() && m_bmpHover.Ok() )
+        Refresh();
+
+    event.Skip();
+}
+
 // VZ: should be at the very least less than wxDEFAULT_BUTTON_MARGIN
 #define FOCUS_MARGIN 3
 
@@ -217,10 +227,12 @@ bool wxBitmapButton::MSWOnDraw(WXDRAWITEMSTRUCT *item)
 
 
     // choose the bitmap to use depending on the button state
-    wxBitmap* bitmap;
+    wxBitmap *bitmap;
 
     if ( isSelected && m_bmpSelected.Ok() )
         bitmap = &m_bmpSelected;
+    else if ( m_bmpHover.Ok() && IsMouseInWindow() )
+        bitmap = &m_bmpHover;
     else if ((state & ODS_FOCUS) && m_bmpFocus.Ok())
         bitmap = &m_bmpFocus;
     else if ((state & ODS_DISABLED) && m_bmpDisabled.Ok())