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