]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/odcombo.h
add 3 parameter scope guard; improve its documentation
[wxWidgets.git] / interface / wx / odcombo.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: odcombo.h
3 // Purpose: interface of wxOwnerDrawnComboBox
4 // Author: wxWidgets team
5 // RCS-ID: $Id$
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
8
9
10 enum wxOwnerDrawnComboBoxPaintingFlags
11 {
12 /**
13 Combo control is being painted, instead of a list item.
14 Argument item may be @c wxNOT_FOUND in this case.
15 */
16 wxODCB_PAINTING_CONTROL = 0x0001,
17
18 /**
19 An item with selection background is being painted.
20 DC text colour should already be correct.
21 */
22 wxODCB_PAINTING_SELECTED = 0x0002
23 };
24
25 /**
26 @class wxOwnerDrawnComboBox
27
28 wxOwnerDrawnComboBox is a combobox with owner-drawn list items.
29 In essence, it is a wxComboCtrl with wxVListBox popup and wxControlWithItems
30 interface.
31
32 Implementing item drawing and measuring is similar to wxVListBox.
33 Application needs to subclass wxOwnerDrawnComboBox and implement
34 OnDrawItem(), OnMeasureItem() and OnMeasureItemWidth().
35
36 @beginStyleTable
37 @style{wxODCB_DCLICK_CYCLES}
38 Double-clicking cycles item if wxCB_READONLY is also used.
39 Synonymous with wxCC_SPECIAL_DCLICK.
40 @style{wxODCB_STD_CONTROL_PAINT}
41 Control itself is not custom painted using OnDrawItem. Even if this
42 style is not used, writable wxOwnerDrawnComboBox is never custom
43 painted unless SetCustomPaintWidth() is called.
44 @endStyleTable
45
46 @see wxComboCtrl window styles and @ref overview_windowstyles.
47
48 @beginEventTable{wxCommandEvent}
49 @event{EVT_COMBOBOX(id, func)}
50 Process a wxEVT_COMMAND_COMBOBOX_SELECTED event, when an item on
51 the list is selected. Note that calling GetValue() returns the new
52 value of selection.
53 @endEventTable
54
55 @see Events emitted by wxComboCtrl.
56
57 @library{wxadv}
58 @category{ctrl}
59 <!-- @appearance{ownerdrawncombobox.png} -->
60
61 @see wxComboCtrl, wxComboBox, wxVListBox, wxCommandEvent
62 */
63 class wxOwnerDrawnComboBox : public wxComboCtrl
64 {
65 public:
66 /**
67 Default constructor.
68 */
69 wxOwnerDrawnComboBox();
70
71 //@{
72 /**
73 Constructor, creating and showing a owner-drawn combobox.
74
75 @param parent
76 Parent window. Must not be @NULL.
77 @param id
78 Window identifier. The value @c wxID_ANY indicates a default value.
79 @param value
80 Initial selection string. An empty string indicates no selection.
81 @param pos
82 Window position.
83 @param size
84 Window size.
85 If ::wxDefaultSize is specified then the window is sized appropriately.
86 @param n
87 Number of strings with which to initialise the control.
88 @param choices
89 An array of strings with which to initialise the control.
90 @param style
91 Window style. See wxOwnerDrawnComboBox.
92 @param validator
93 Window validator.
94 @param name
95 Window name.
96
97 @see Create(), wxValidator
98 */
99 wxOwnerDrawnComboBox(wxWindow* parent, wxWindowID id,
100 const wxString& value = "",
101 const wxPoint& pos = wxDefaultPosition,
102 const wxSize& size = wxDefaultSize,
103 int n = 0,
104 const wxString[] choices = NULL,
105 long style = 0,
106 const wxValidator& validator = wxDefaultValidator,
107 const wxString& name = "comboBox");
108 /**
109 Constructor, creating and showing a owner-drawn combobox.
110
111 @param parent
112 Parent window. Must not be @NULL.
113 @param id
114 Window identifier. The value @c wxID_ANY indicates a default value.
115 @param value
116 Initial selection string. An empty string indicates no selection.
117 @param pos
118 Window position.
119 @param size
120 Window size.
121 If ::wxDefaultSize is specified then the window is sized appropriately.
122 @param choices
123 An array of strings with which to initialise the control.
124 @param style
125 Window style. See wxOwnerDrawnComboBox.
126 @param validator
127 Window validator.
128 @param name
129 Window name.
130
131 @see Create(), wxValidator
132 */
133 wxOwnerDrawnComboBox(wxWindow* parent, wxWindowID id,
134 const wxString& value,
135 const wxPoint& pos,
136 const wxSize& size,
137 const wxArrayString& choices,
138 long style = 0,
139 const wxValidator& validator = wxDefaultValidator,
140 const wxString& name = "comboBox");
141 //@}
142
143 /**
144 Destructor, destroying the owner-drawn combobox.
145 */
146 virtual ~wxOwnerDrawnComboBox();
147
148 //@{
149 /**
150 Creates the combobox for two-step construction.
151 See wxOwnerDrawnComboBox() for further details.
152
153 @remarks Derived classes should call or replace this function.
154 */
155 bool Create(wxWindow* parent, wxWindowID id,
156 const wxString& value = "",
157 const wxPoint& pos = wxDefaultPosition,
158 const wxSize& size = wxDefaultSize,
159 int n, const wxString choices[],
160 long style = 0,
161 const wxValidator& validator = wxDefaultValidator,
162 const wxString& name = "comboBox");
163 bool Create(wxWindow* parent, wxWindowID id,
164 const wxString& value,
165 const wxPoint& pos,
166 const wxSize& size,
167 const wxArrayString& choices,
168 long style = 0,
169 const wxValidator& validator = wxDefaultValidator,
170 const wxString& name = "comboBox");
171 //@}
172
173 /**
174 Returns index to the widest item in the list.
175 */
176 virtual int GetWidestItem();
177
178 /**
179 Returns width of the widest item in the list.
180 */
181 virtual int GetWidestItemWidth();
182
183 /**
184 This method is used to draw the items background and, maybe, a border around it.
185
186 The base class version implements a reasonable default behaviour which consists
187 in drawing the selected item with the standard background colour and drawing a
188 border around the item if it is either selected or current.
189
190 @remarks flags has the same meaning as with OnDrawItem().
191 */
192 void OnDrawBackground(wxDC& dc, const wxRect& rect, int item,
193 int flags) const;
194
195 /**
196 The derived class may implement this function to actually draw the item
197 with the given index on the provided DC.
198
199 If function is not implemented, the item text is simply drawn, as if the control
200 was a normal combobox.
201
202 @param dc
203 The device context to use for drawing
204 @param rect
205 The bounding rectangle for the item being drawn (DC clipping
206 region is set to this rectangle before calling this function)
207 @param item
208 The index of the item to be drawn
209 @param flags
210 A combination of the ::wxOwnerDrawnComboBoxPaintingFlags enumeration values.
211 */
212 void OnDrawItem(wxDC& dc, const wxRect& rect, int item,
213 int flags) const;
214
215 /**
216 The derived class may implement this method to return the height of the
217 specified item (in pixels).
218
219 The default implementation returns text height, as if this control was
220 a normal combobox.
221 */
222 wxCoord OnMeasureItem(size_t item) const;
223
224 /**
225 The derived class may implement this method to return the width of the
226 specified item (in pixels). If -1 is returned, then the item text width
227 is used.
228
229 The default implementation returns -1.
230 */
231 wxCoord OnMeasureItemWidth(size_t item) const;
232 };
233