]> git.saurik.com Git - wxWidgets.git/blob - interface/bmpbuttn.h
ODBC is not part of wx anymore
[wxWidgets.git] / 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 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.
36
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
42 all provided bitmaps. Has effect only under MS Windows.
43 @style{wxBU_LEFT}:
44 Left-justifies the bitmap label. Has effect only under MS Windows.
45 @style{wxBU_TOP}:
46 Aligns the bitmap label to the top of the button.
47 Has effect only under MS Windows.
48 @style{wxBU_RIGHT}:
49 Right-justifies the bitmap label. Has effect only under MS Windows.
50 @style{wxBU_BOTTOM}:
51 Aligns the bitmap label to the bottom of the button.
52 Has effect only under MS Windows.
53 @endStyleTable
54
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
58 @beginEventTable{wxCommandEvent}
59 @event{EVT_BUTTON(id, func)}:
60 Process a wxEVT_COMMAND_BUTTON_CLICKED event, when the button is clicked.
61 @endEventTable
62
63 @library{wxcore}
64 @category{ctrl}
65 @appearance{bitmapbutton.png}
66
67 @see wxButton
68 */
69 class wxBitmapButton : public wxButton
70 {
71 public:
72 /**
73 Default ctor.
74 */
75 wxBitmapButton();
76
77 /**
78 Constructor, creating and showing a button.
79
80 @param parent
81 Parent window. Must not be @NULL.
82 @param id
83 Button identifier. The value wxID_ANY indicates a default value.
84 @param bitmap
85 Bitmap to be displayed.
86 @param pos
87 Button position.
88 @param size
89 Button size. If wxDefaultSize is specified then the button is sized
90 appropriately for the bitmap.
91 @param style
92 Window style. See wxBitmapButton.
93 @param validator
94 Window validator.
95 @param name
96 Window name.
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
103 @see Create(), wxValidator
104 */
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,
111 const wxString& name = wxButtonNameStr);
112
113 /**
114 Destructor, destroying the button.
115 */
116 virtual ~wxBitmapButton();
117
118 /**
119 Button creation function for two-step creation.
120 For more details, see wxBitmapButton().
121 */
122 bool Create(wxWindow* parent, wxWindowID id,
123 const wxBitmap& bitmap,
124 const wxPoint& pos = wxDefaultPosition,
125 const wxSize& size = wxDefaultSize,
126 long style = wxBU_AUTODRAW,
127 const wxValidator& validator = wxDefaultValidator,
128 const wxString& name = wxButtonNameStr);
129
130 //@{
131 /**
132 Returns the bitmap for the disabled state, which may be invalid.
133
134 @returns A reference to the disabled state bitmap.
135
136 @see SetBitmapDisabled()
137 */
138 const wxBitmap& GetBitmapDisabled() const;
139 wxBitmap& GetBitmapDisabled();
140 //@}
141
142 //@{
143 /**
144 Returns the bitmap for the focused state, which may be invalid.
145
146 @returns A reference to the focused state bitmap.
147
148 @see SetBitmapFocus()
149 */
150 const wxBitmap& GetBitmapFocus() const;
151 wxBitmap& GetBitmapFocus();
152 //@}
153
154 //@{
155 /**
156 Returns the bitmap used when the mouse is over the button, which may be invalid.
157
158 @see SetBitmapHover()
159 */
160 const wxBitmap& GetBitmapHover();
161 wxBitmap& GetBitmapHover();
162 //@}
163
164 //@{
165 /**
166 Returns the label bitmap (the one passed to the constructor), always valid.
167
168 @returns A reference to the button's label bitmap.
169
170 @see SetBitmapLabel()
171 */
172 const wxBitmap& GetBitmapLabel();
173 wxBitmap& GetBitmapLabel();
174 //@}
175
176 /**
177 Returns the bitmap for the selected state.
178
179 @returns A reference to the selected state bitmap.
180
181 @see SetBitmapSelected()
182 */
183 const wxBitmap& GetBitmapSelected() const;
184
185 /**
186 Sets the bitmap for the disabled button appearance.
187
188 @param bitmap
189 The bitmap to set.
190
191 @see GetBitmapDisabled(), SetBitmapLabel(),
192 SetBitmapSelected(), SetBitmapFocus()
193 */
194 virtual void SetBitmapDisabled(const wxBitmap& bitmap);
195
196 /**
197 Sets the bitmap for the button appearance when it has the keyboard focus.
198
199 @param bitmap
200 The bitmap to set.
201
202 @see GetBitmapFocus(), SetBitmapLabel(),
203 SetBitmapSelected(), SetBitmapDisabled()
204 */
205 virtual void SetBitmapFocus(const wxBitmap& bitmap);
206
207 /**
208 Sets the bitmap to be shown when the mouse is over the button.
209
210 @wxsince{2.7.0}
211
212 The hover bitmap is currently only supported in wxMSW.
213
214 @see GetBitmapHover()
215 */
216 virtual void SetBitmapHover(const wxBitmap& bitmap);
217
218 /**
219 Sets the bitmap label for the button.
220
221 @param bitmap
222 The bitmap label to set.
223
224 @remarks This is the bitmap used for the unselected state, and for all
225 other states if no other bitmaps are provided.
226
227 @see GetBitmapLabel()
228 */
229 virtual void SetBitmapLabel(const wxBitmap& bitmap);
230
231 /**
232 Sets the bitmap for the selected (depressed) button appearance.
233
234 @param bitmap
235 The bitmap to set.
236 */
237 virtual void SetBitmapSelected(const wxBitmap& bitmap);
238 };
239