interface/wx/bmpbuttn.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        bmpbuttn.h
   3 // Purpose:     interface of wxBitmapButton
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxBitmapButton
  11
  12     A bitmap button is a control that contains a bitmap.
  13     It may be placed on a wxDialog or a wxPanel, or indeed almost any other window.
  14
  15     @remarks
  16     A bitmap button can be supplied with a single bitmap, and wxWidgets will draw
  17     all button states using this bitmap. If the application needs more control,
  18     additional bitmaps for the selected state, unpressed focused state, and greyed-out
  19     state may be supplied.
  20
  21     @section bitmapbutton_states Button states
  22
  23     This class supports bitmaps for several different states:
  24     @li @b normal: this is the bitmap shown in the default state, it must be always
  25         valid while all the other bitmaps are optional and don't have to be set.
  26     @li @b disabled: bitmap shown when the button is disabled.
  27     @li @b selected: bitmap shown when the button is pushed (e.g. while the user
  28         keeps the mouse button pressed on it)
  29     @li @b focus: bitmap shown when the button has keyboard focus but is not pressed.
  30     @li @b hover: bitmap shown when the mouse is over the button (but it is not pressed).
  31         Notice that if hover bitmap is not specified but the current platform UI uses
  32         hover images for the buttons (such as Windows XP or GTK+), then the focus bitmap
  33         is used for hover state as well. This makes it possible to set focus bitmap only
  34         to get reasonably good behaviour on all platforms.
  35
  36     @beginStyleTable
  37     @style{wxBU_AUTODRAW}
  38            If this is specified, the button will be drawn automatically using
  39            the label bitmap only, providing a 3D-look border. If this style is
  40            not specified, the button will be drawn without borders and using
  41            all provided bitmaps. Has effect only under MS Windows.
  42     @style{wxBU_LEFT}
  43            Left-justifies the bitmap label. Has effect only under MS Windows.
  44     @style{wxBU_TOP}
  45            Aligns the bitmap label to the top of the button.
  46            Has effect only under MS Windows.
  47     @style{wxBU_RIGHT}
  48            Right-justifies the bitmap label. Has effect only under MS Windows.
  49     @style{wxBU_BOTTOM}
  50            Aligns the bitmap label to the bottom of the button.
  51            Has effect only under MS Windows.
  52     @endStyleTable
  53
  54     Note that the wxBU_EXACTFIT style supported by wxButton is not used by this
  55     class as bitmap buttons don't have any minimal standard size by default.
  56
  57     @beginEventEmissionTable{wxCommandEvent}
  58     @event{EVT_BUTTON(id, func)}
  59            Process a wxEVT_COMMAND_BUTTON_CLICKED event, when the button is clicked.
  60     @endEventTable
  61
  62     @library{wxcore}
  63     @category{ctrl}
  64     @appearance{bitmapbutton.png}
  65
  66     @see wxButton
  67 */
  68 class wxBitmapButton : public wxButton
  69 {
  70 public:
  71     /**
  72         Default ctor.
  73     */
  74     wxBitmapButton();
  75
  76     /**
  77         Constructor, creating and showing a button.
  78
  79         @param parent
  80             Parent window. Must not be @NULL.
  81         @param id
  82             Button identifier. The value wxID_ANY indicates a default value.
  83         @param bitmap
  84             Bitmap to be displayed.
  85         @param pos
  86             Button position.
  87             If ::wxDefaultPosition is specified then a default position is chosen.
  88         @param size
  89             Button size.
  90             If ::wxDefaultSize is specified then the button is sized appropriately
  91             for the bitmap.
  92         @param style
  93             Window style. See wxBitmapButton.
  94         @param validator
  95             Window validator.
  96         @param name
  97             Window name.
  98
  99         @remarks The bitmap parameter is normally the only bitmap you need to provide,
 100                  and wxWidgets will draw the button correctly in its different states.
 101                  If you want more control, call any of the functions SetBitmapSelected(),
 102                  SetBitmapFocus(), SetBitmapDisabled().
 103
 104         @see Create(), wxValidator
 105     */
 106     wxBitmapButton(wxWindow* parent, wxWindowID id,
 107                    const wxBitmap& bitmap,
 108                    const wxPoint& pos = wxDefaultPosition,
 109                    const wxSize& size = wxDefaultSize,
 110                    long style = wxBU_AUTODRAW,
 111                    const wxValidator& validator = wxDefaultValidator,
 112                    const wxString& name = wxButtonNameStr);
 113
 114     /**
 115         Destructor, destroying the button.
 116     */
 117     virtual ~wxBitmapButton();
 118
 119     /**
 120         Button creation function for two-step creation.
 121         For more details, see wxBitmapButton().
 122     */
 123     bool Create(wxWindow* parent, wxWindowID id,
 124                 const wxBitmap& bitmap,
 125                 const wxPoint& pos = wxDefaultPosition,
 126                 const wxSize& size = wxDefaultSize,
 127                 long style = wxBU_AUTODRAW,
 128                 const wxValidator& validator = wxDefaultValidator,
 129                 const wxString& name = wxButtonNameStr);
 130
 131     //@{
 132     /**
 133         Returns the bitmap for the disabled state, which may be invalid.
 134
 135         @return A reference to the disabled state bitmap.
 136
 137         @see SetBitmapDisabled()
 138     */
 139     const wxBitmap& GetBitmapDisabled() const;
 140     wxBitmap& GetBitmapDisabled();
 141     //@}
 142
 143     //@{
 144     /**
 145         Returns the bitmap for the focused state, which may be invalid.
 146
 147         @return A reference to the focused state bitmap.
 148
 149         @see SetBitmapFocus()
 150     */
 151     const wxBitmap& GetBitmapFocus() const;
 152     wxBitmap& GetBitmapFocus();
 153     //@}
 154
 155     //@{
 156     /**
 157         Returns the bitmap used when the mouse is over the button, which may be invalid.
 158
 159         @see SetBitmapHover()
 160     */
 161     const wxBitmap& GetBitmapHover() const;
 162     wxBitmap& GetBitmapHover();
 163     //@}
 164
 165     //@{
 166     /**
 167         Returns the label bitmap (the one passed to the constructor), always valid.
 168
 169         @return A reference to the button's label bitmap.
 170
 171         @see SetBitmapLabel()
 172     */
 173     const wxBitmap& GetBitmapLabel() const;
 174     wxBitmap& GetBitmapLabel();
 175     //@}
 176
 177     /**
 178         Returns the bitmap for the selected state.
 179
 180         @return A reference to the selected state bitmap.
 181
 182         @see SetBitmapSelected()
 183     */
 184     const wxBitmap& GetBitmapSelected() const;
 185
 186     /**
 187         Sets the bitmap for the disabled button appearance.
 188
 189         @param bitmap
 190             The bitmap to set.
 191
 192         @see GetBitmapDisabled(), SetBitmapLabel(),
 193              SetBitmapSelected(), SetBitmapFocus()
 194     */
 195     virtual void SetBitmapDisabled(const wxBitmap& bitmap);
 196
 197     /**
 198         Sets the bitmap for the button appearance when it has the keyboard focus.
 199
 200         @param bitmap
 201             The bitmap to set.
 202
 203         @see GetBitmapFocus(), SetBitmapLabel(),
 204              SetBitmapSelected(), SetBitmapDisabled()
 205     */
 206     virtual void SetBitmapFocus(const wxBitmap& bitmap);
 207
 208     /**
 209         Sets the bitmap to be shown when the mouse is over the button.
 210
 211         @since 2.7.0
 212
 213         The hover bitmap is currently only supported in wxMSW.
 214
 215         @see GetBitmapHover()
 216     */
 217     virtual void SetBitmapHover(const wxBitmap& bitmap);
 218
 219     /**
 220         Sets the bitmap label for the button.
 221
 222         @param bitmap
 223             The bitmap label to set.
 224
 225         @remarks This is the bitmap used for the unselected state, and for all
 226                  other states if no other bitmaps are provided.
 227
 228         @see GetBitmapLabel()
 229     */
 230     virtual void SetBitmapLabel(const wxBitmap& bitmap);
 231
 232     /**
 233         Sets the bitmap for the selected (depressed) button appearance.
 234
 235         @param bitmap
 236             The bitmap to set.
 237     */
 238     virtual void SetBitmapSelected(const wxBitmap& bitmap);
 239 };
 240