interface/bmpbuttn.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        bmpbuttn.h
   3 // Purpose:     documentation for wxBitmapButton class
   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     @seealso
  44     wxButton
  45 */
  46 class wxBitmapButton : public wxButton
  47 {
  48 public:
  49     //@{
  50     /**
  51         Constructor, creating and showing a button.
  52
  53         @param parent
  54             Parent window. Must not be @NULL.
  55         @param id
  56             Button identifier. The value wxID_ANY indicates a default value.
  57         @param bitmap
  58             Bitmap to be displayed.
  59         @param pos
  60             Button position.
  61         @param size
  62             Button size. If wxDefaultSize is specified then the button is
  63         sized
  64             appropriately for the bitmap.
  65         @param style
  66             Window style. See wxBitmapButton.
  67         @param validator
  68             Window validator.
  69         @param name
  70             Window name.
  71
  72         @remarks The bitmap parameter is normally the only bitmap you need to
  73                  provide, and wxWidgets will draw the button correctly
  74                  in its different states. If you want more control, call
  75                  any of the functions SetBitmapSelected(),
  76                  SetBitmapFocus(),
  77                  SetBitmapDisabled().
  78
  79         @see Create(), wxValidator
  80     */
  81     wxBitmapButton();
  82     wxBitmapButton(wxWindow* parent, wxWindowID id,
  83                    const wxBitmap& bitmap,
  84                    const wxPoint& pos = wxDefaultPosition,
  85                    const wxSize& size = wxDefaultSize,
  86                    long style = wxBU_AUTODRAW,
  87                    const wxValidator& validator = wxDefaultValidator,
  88                    const wxString& name = "button");
  89     //@}
  90
  91     /**
  92         Destructor, destroying the button.
  93     */
  94     ~wxBitmapButton();
  95
  96     /**
  97         Button creation function for two-step creation. For more details, see
  98         wxBitmapButton().
  99     */
 100     bool Create(wxWindow* parent, wxWindowID id,
 101                 const wxBitmap& bitmap,
 102                 const wxPoint& pos,
 103                 const wxSize& size = wxDefaultSize,
 104                 long style = 0,
 105                 const wxValidator& validator,
 106                 const wxString& name = "button");
 107
 108     //@{
 109     /**
 110         Returns the bitmap for the disabled state, may be invalid.
 111
 112         @returns A reference to the disabled state bitmap.
 113
 114         @see SetBitmapDisabled()
 115     */
 116     const wxBitmap GetBitmapDisabled();
 117     const wxBitmap&  GetBitmapDisabled();
 118     //@}
 119
 120     //@{
 121     /**
 122         Returns the bitmap for the focused state, may be invalid.
 123
 124         @returns A reference to the focused state bitmap.
 125
 126         @see SetBitmapFocus()
 127     */
 128     const wxBitmap GetBitmapFocus();
 129     const wxBitmap&  GetBitmapFocus();
 130     //@}
 131
 132     //@{
 133     /**
 134         Returns the bitmap used when the mouse is over the button, may be invalid.
 135
 136         @see SetBitmapHover()
 137     */
 138     const wxBitmap GetBitmapHover();
 139     const wxBitmap&  GetBitmapHover();
 140     //@}
 141
 142     //@{
 143     /**
 144         Returns the label bitmap (the one passed to the constructor), always valid.
 145
 146         @returns A reference to the button's label bitmap.
 147
 148         @see SetBitmapLabel()
 149     */
 150     const wxBitmap GetBitmapLabel();
 151     const wxBitmap&  GetBitmapLabel();
 152     //@}
 153
 154     /**
 155         Returns the bitmap for the selected state.
 156
 157         @returns A reference to the selected state bitmap.
 158
 159         @see SetBitmapSelected()
 160     */
 161     wxBitmap GetBitmapSelected() const;
 162
 163     /**
 164         Sets the bitmap for the disabled button appearance.
 165
 166         @param bitmap
 167             The bitmap to set.
 168
 169         @see GetBitmapDisabled(), SetBitmapLabel(),
 170              SetBitmapSelected(), SetBitmapFocus()
 171     */
 172     void SetBitmapDisabled(const wxBitmap& bitmap);
 173
 174     /**
 175         Sets the bitmap for the button appearance when it has the keyboard focus.
 176
 177         @param bitmap
 178             The bitmap to set.
 179
 180         @see GetBitmapFocus(), SetBitmapLabel(),
 181              SetBitmapSelected(), SetBitmapDisabled()
 182     */
 183     void SetBitmapFocus(const wxBitmap& bitmap);
 184
 185     /**
 186         Sets the bitmap to be shown when the mouse is over the button.
 187         This function is new since wxWidgets version 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 };