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
  56         @param id
  57         Button identifier. The value wxID_ANY indicates a default value.
  58
  59         @param bitmap
  60         Bitmap to be displayed.
  61
  62         @param pos
  63         Button position.
  64
  65         @param size
  66         Button size. If wxDefaultSize is specified then the button is sized
  67         appropriately for the bitmap.
  68
  69         @param style
  70         Window style. See wxBitmapButton.
  71
  72         @param validator
  73         Window validator.
  74
  75         @param name
  76         Window name.
  77
  78         @remarks The bitmap parameter is normally the only bitmap you need to
  79                    provide, and wxWidgets will draw the button correctly
  80                    in its different states. If you want more control,
  81                    call any of the functions
  82                    SetBitmapSelected(),
  83                    SetBitmapFocus(),
  84                    SetBitmapDisabled().
  85
  86         @sa Create(), wxValidator
  87     */
  88     wxBitmapButton();
  89     wxBitmapButton(wxWindow* parent, wxWindowID id,
  90                    const wxBitmap& bitmap,
  91                    const wxPoint& pos = wxDefaultPosition,
  92                    const wxSize& size = wxDefaultSize,
  93                    long style = wxBU_AUTODRAW,
  94                    const wxValidator& validator = wxDefaultValidator,
  95                    const wxString& name = "button");
  96     //@}
  97
  98     /**
  99         Destructor, destroying the button.
 100     */
 101     ~wxBitmapButton();
 102
 103     /**
 104         Button creation function for two-step creation. For more details, see
 105         wxBitmapButton().
 106     */
 107     bool Create(wxWindow* parent, wxWindowID id,
 108                 const wxBitmap& bitmap,
 109                 const wxPoint& pos,
 110                 const wxSize& size = wxDefaultSize,
 111                 long style = 0,
 112                 const wxValidator& validator,
 113                 const wxString& name = "button");
 114
 115     //@{
 116     /**
 117         Returns the bitmap for the disabled state, may be invalid.
 118
 119         @returns A reference to the disabled state bitmap.
 120
 121         @sa SetBitmapDisabled()
 122     */
 123     const wxBitmap GetBitmapDisabled();
 124     wxBitmap GetBitmapDisabled();
 125     //@}
 126
 127     //@{
 128     /**
 129         Returns the bitmap for the focused state, may be invalid.
 130
 131         @returns A reference to the focused state bitmap.
 132
 133         @sa SetBitmapFocus()
 134     */
 135     const wxBitmap GetBitmapFocus();
 136     wxBitmap GetBitmapFocus();
 137     //@}
 138
 139     //@{
 140     /**
 141         Returns the bitmap used when the mouse is over the button, may be invalid.
 142
 143         @sa SetBitmapHover()
 144     */
 145     const wxBitmap GetBitmapHover();
 146     wxBitmap GetBitmapHover();
 147     //@}
 148
 149     //@{
 150     /**
 151         Returns the label bitmap (the one passed to the constructor), always valid.
 152
 153         @returns A reference to the button's label bitmap.
 154
 155         @sa SetBitmapLabel()
 156     */
 157     const wxBitmap GetBitmapLabel();
 158     wxBitmap GetBitmapLabel();
 159     //@}
 160
 161     /**
 162         Returns the bitmap for the selected state.
 163
 164         @returns A reference to the selected state bitmap.
 165
 166         @sa SetBitmapSelected()
 167     */
 168     wxBitmap GetBitmapSelected();
 169
 170     /**
 171         Sets the bitmap for the disabled button appearance.
 172
 173         @param bitmap
 174         The bitmap to set.
 175
 176         @sa GetBitmapDisabled(), SetBitmapLabel(),
 177               SetBitmapSelected(), SetBitmapFocus()
 178     */
 179     void SetBitmapDisabled(const wxBitmap& bitmap);
 180
 181     /**
 182         Sets the bitmap for the button appearance when it has the keyboard focus.
 183
 184         @param bitmap
 185         The bitmap to set.
 186
 187         @sa GetBitmapFocus(), SetBitmapLabel(),
 188               SetBitmapSelected(), SetBitmapDisabled()
 189     */
 190     void SetBitmapFocus(const wxBitmap& bitmap);
 191
 192     /**
 193         Sets the bitmap to be shown when the mouse is over the button.
 194
 195         This function is new since wxWidgets version 2.7.0 and the hover bitmap is
 196         currently only supported in wxMSW.
 197
 198         @sa GetBitmapHover()
 199     */
 200     void SetBitmapHover(const wxBitmap& bitmap);
 201
 202     /**
 203         Sets the bitmap label for the button.
 204
 205         @param bitmap
 206         The bitmap label to set.
 207
 208         @remarks This is the bitmap used for the unselected state, and for all
 209                    other states if no other bitmaps are provided.
 210
 211         @sa GetBitmapLabel()
 212     */
 213     void SetBitmapLabel(const wxBitmap& bitmap);
 214
 215     /**
 216         Sets the bitmap for the selected (depressed) button appearance.
 217
 218         @param bitmap
 219         The bitmap to set.
 220     */
 221     void SetBitmapSelected(const wxBitmap& bitmap);
 222 };