interface/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     @wxheader{bmpbuttn.h}
  12
  13     A bitmap button is a control that contains a bitmap.
  14     It may be placed on a @ref overview_wxdialog "dialog box" or panel(), or indeed
  15     almost any other window.
  16
  17     @beginStyleTable
  18     @style{wxBU_AUTODRAW}:
  19            If this is specified, the button will be drawn automatically using
  20            the label bitmap only, providing a 3D-look border. If this style is
  21            not specified, the button will be drawn without borders and using
  22            all provided bitmaps. WIN32 only.
  23     @style{wxBU_LEFT}:
  24            Left-justifies the bitmap label. WIN32 only.
  25     @style{wxBU_TOP}:
  26            Aligns the bitmap label to the top of the button. WIN32 only.
  27     @style{wxBU_RIGHT}:
  28            Right-justifies the bitmap label. WIN32 only.
  29     @style{wxBU_BOTTOM}:
  30            Aligns the bitmap label to the bottom of the button. WIN32 only.
  31     @endStyleTable
  32
  33     @beginEventTable
  34     @event{EVT_BUTTON(id, func)}:
  35            Process a wxEVT_COMMAND_BUTTON_CLICKED event, when the button is
  36            clicked.
  37     @endEventTable
  38
  39     @library{wxcore}
  40     @category{ctrl}
  41     @appearance{bitmapbutton.png}
  42
  43     @see wxButton
  44 */
  45 class wxBitmapButton : public wxButton
  46 {
  47 public:
  48     //@{
  49     /**
  50         Constructor, creating and showing a button.
  51
  52         @param parent
  53             Parent window. Must not be @NULL.
  54         @param id
  55             Button identifier. The value wxID_ANY indicates a default value.
  56         @param bitmap
  57             Bitmap to be displayed.
  58         @param pos
  59             Button position.
  60         @param size
  61             Button size. If wxDefaultSize is specified then the button is
  62         sized
  63             appropriately for the bitmap.
  64         @param style
  65             Window style. See wxBitmapButton.
  66         @param validator
  67             Window validator.
  68         @param name
  69             Window name.
  70
  71         @remarks The bitmap parameter is normally the only bitmap you need to
  72                  provide, and wxWidgets will draw the button correctly
  73                  in its different states. If you want more control, call
  74                  any of the functions SetBitmapSelected(),
  75                  SetBitmapFocus(),
  76                  SetBitmapDisabled().
  77
  78         @see Create(), wxValidator
  79     */
  80     wxBitmapButton();
  81     wxBitmapButton(wxWindow* parent, wxWindowID id,
  82                    const wxBitmap& bitmap,
  83                    const wxPoint& pos = wxDefaultPosition,
  84                    const wxSize& size = wxDefaultSize,
  85                    long style = wxBU_AUTODRAW,
  86                    const wxValidator& validator = wxDefaultValidator,
  87                    const wxString& name = "button");
  88     //@}
  89
  90     /**
  91         Destructor, destroying the button.
  92     */
  93     ~wxBitmapButton();
  94
  95     /**
  96         Button creation function for two-step creation. For more details, see
  97         wxBitmapButton().
  98     */
  99     bool Create(wxWindow* parent, wxWindowID id,
 100                 const wxBitmap& bitmap,
 101                 const wxPoint& pos,
 102                 const wxSize& size = wxDefaultSize,
 103                 long style = 0,
 104                 const wxValidator& validator,
 105                 const wxString& name = "button");
 106
 107     //@{
 108     /**
 109         Returns the bitmap for the disabled state, may be invalid.
 110
 111         @returns A reference to the disabled state bitmap.
 112
 113         @see SetBitmapDisabled()
 114     */
 115     const wxBitmap GetBitmapDisabled();
 116     const wxBitmap&  GetBitmapDisabled();
 117     //@}
 118
 119     //@{
 120     /**
 121         Returns the bitmap for the focused state, may be invalid.
 122
 123         @returns A reference to the focused state bitmap.
 124
 125         @see SetBitmapFocus()
 126     */
 127     const wxBitmap GetBitmapFocus();
 128     const wxBitmap&  GetBitmapFocus();
 129     //@}
 130
 131     //@{
 132     /**
 133         Returns the bitmap used when the mouse is over the button, may be invalid.
 134
 135         @see SetBitmapHover()
 136     */
 137     const wxBitmap GetBitmapHover();
 138     const wxBitmap&  GetBitmapHover();
 139     //@}
 140
 141     //@{
 142     /**
 143         Returns the label bitmap (the one passed to the constructor), always valid.
 144
 145         @returns A reference to the button's label bitmap.
 146
 147         @see SetBitmapLabel()
 148     */
 149     const wxBitmap GetBitmapLabel();
 150     const wxBitmap&  GetBitmapLabel();
 151     //@}
 152
 153     /**
 154         Returns the bitmap for the selected state.
 155
 156         @returns A reference to the selected state bitmap.
 157
 158         @see SetBitmapSelected()
 159     */
 160     wxBitmap GetBitmapSelected() const;
 161
 162     /**
 163         Sets the bitmap for the disabled button appearance.
 164
 165         @param bitmap
 166             The bitmap to set.
 167
 168         @see GetBitmapDisabled(), SetBitmapLabel(),
 169              SetBitmapSelected(), SetBitmapFocus()
 170     */
 171     void SetBitmapDisabled(const wxBitmap& bitmap);
 172
 173     /**
 174         Sets the bitmap for the button appearance when it has the keyboard focus.
 175
 176         @param bitmap
 177             The bitmap to set.
 178
 179         @see GetBitmapFocus(), SetBitmapLabel(),
 180              SetBitmapSelected(), SetBitmapDisabled()
 181     */
 182     void SetBitmapFocus(const wxBitmap& bitmap);
 183
 184     /**
 185         Sets the bitmap to be shown when the mouse is over the button.
 186
 187         @wxsince{2.7.0} and the hover bitmap is
 188         currently only supported in wxMSW.
 189
 190         @see GetBitmapHover()
 191     */
 192     void SetBitmapHover(const wxBitmap& bitmap);
 193
 194     /**
 195         Sets the bitmap label for the button.
 196
 197         @param bitmap
 198             The bitmap label to set.
 199
 200         @remarks This is the bitmap used for the unselected state, and for all
 201                  other states if no other bitmaps are provided.
 202
 203         @see GetBitmapLabel()
 204     */
 205     void SetBitmapLabel(const wxBitmap& bitmap);
 206
 207     /**
 208         Sets the bitmap for the selected (depressed) button appearance.
 209
 210         @param bitmap
 211             The bitmap to set.
 212     */
 213     void SetBitmapSelected(const wxBitmap& bitmap);
 214 };
 215