]>
Commit | Line | Data |
---|---|---|
1 | ///////////////////////////////////////////////////////////////////////////// | |
2 | // Name: combo.h | |
3 | // Purpose: interface of wxComboCtrl and wxComboPopup | |
4 | // Author: wxWidgets team | |
5 | // RCS-ID: $Id$ | |
6 | // Licence: wxWindows licence | |
7 | ///////////////////////////////////////////////////////////////////////////// | |
8 | ||
9 | /** | |
10 | @class wxComboPopup | |
11 | ||
12 | In order to use a custom popup with wxComboCtrl, an interface class must be | |
13 | derived from wxComboPopup. | |
14 | ||
15 | For more information on how to use it, see @ref comboctrl_custompopup. | |
16 | ||
17 | @library{wxcore} | |
18 | @category{ctrl} | |
19 | ||
20 | @see wxComboCtrl | |
21 | */ | |
22 | class wxComboPopup | |
23 | { | |
24 | public: | |
25 | /** | |
26 | Default constructor. It is recommended that internal variables are | |
27 | prepared in Init() instead (because m_combo is not valid in | |
28 | constructor). | |
29 | */ | |
30 | wxComboPopup(); | |
31 | ||
32 | /** | |
33 | The derived class must implement this to create the popup control. | |
34 | ||
35 | @return @true if the call succeeded, @false otherwise. | |
36 | */ | |
37 | virtual bool Create(wxWindow* parent) = 0; | |
38 | ||
39 | /** | |
40 | Utility function that hides the popup. | |
41 | */ | |
42 | void Dismiss(); | |
43 | ||
44 | /** | |
45 | The derived class may implement this to return adjusted size for the | |
46 | popup control, according to the variables given. | |
47 | ||
48 | @param minWidth | |
49 | Preferred minimum width. | |
50 | @param prefHeight | |
51 | Preferred height. May be -1 to indicate no preference. | |
52 | @param maxHeight | |
53 | Max height for window, as limited by screen size. | |
54 | ||
55 | @remarks This function is called each time popup is about to be shown. | |
56 | */ | |
57 | virtual wxSize GetAdjustedSize(int minWidth, int prefHeight, int maxHeight); | |
58 | ||
59 | /** | |
60 | Returns pointer to the associated parent wxComboCtrl. | |
61 | */ | |
62 | wxComboCtrl* GetComboCtrl() const; | |
63 | ||
64 | /** | |
65 | The derived class must implement this to return pointer to the | |
66 | associated control created in Create(). | |
67 | */ | |
68 | virtual wxWindow* GetControl() = 0; | |
69 | ||
70 | /** | |
71 | The derived class must implement this to return string representation | |
72 | of the value. | |
73 | */ | |
74 | virtual wxString GetStringValue() const = 0; | |
75 | ||
76 | /** | |
77 | The derived class must implement this to initialize its internal | |
78 | variables. This method is called immediately after construction | |
79 | finishes. m_combo member variable has been initialized before the call. | |
80 | */ | |
81 | virtual void Init(); | |
82 | ||
83 | /** | |
84 | Utility method that returns @true if Create has been called. | |
85 | ||
86 | Useful in conjunction with LazyCreate(). | |
87 | */ | |
88 | bool IsCreated() const; | |
89 | ||
90 | /** | |
91 | The derived class may implement this to return @true if it wants to | |
92 | delay call to Create() until the popup is shown for the first time. It | |
93 | is more efficient, but on the other hand it is often more convenient to | |
94 | have the control created immediately. | |
95 | ||
96 | @remarks Base implementation returns @false. | |
97 | */ | |
98 | virtual bool LazyCreate(); | |
99 | ||
100 | /** | |
101 | The derived class may implement this to do something when the parent | |
102 | wxComboCtrl gets double-clicked. | |
103 | */ | |
104 | virtual void OnComboDoubleClick(); | |
105 | ||
106 | /** | |
107 | The derived class may implement this to receive key events from the | |
108 | parent wxComboCtrl. | |
109 | ||
110 | Events not handled should be skipped, as usual. | |
111 | */ | |
112 | virtual void OnComboKeyEvent(wxKeyEvent& event); | |
113 | ||
114 | /** | |
115 | The derived class may implement this to do special processing when | |
116 | popup is hidden. | |
117 | */ | |
118 | virtual void OnDismiss(); | |
119 | ||
120 | /** | |
121 | The derived class may implement this to do special processing when | |
122 | popup is shown. | |
123 | */ | |
124 | virtual void OnPopup(); | |
125 | ||
126 | /** | |
127 | The derived class may implement this to paint the parent wxComboCtrl. | |
128 | ||
129 | Default implementation draws value as string. | |
130 | */ | |
131 | virtual void PaintComboControl(wxDC& dc, const wxRect& rect); | |
132 | ||
133 | /** | |
134 | The derived class must implement this to receive string value changes | |
135 | from wxComboCtrl. | |
136 | */ | |
137 | virtual void SetStringValue(const wxString& value); | |
138 | ||
139 | protected: | |
140 | /** | |
141 | Parent wxComboCtrl. This member variable is prepared automatically | |
142 | before Init() is called. | |
143 | */ | |
144 | wxComboCtrl* m_combo; | |
145 | }; | |
146 | ||
147 | ||
148 | ||
149 | /** | |
150 | Features enabled for wxComboCtrl. | |
151 | ||
152 | @see wxComboCtrl::GetFeatures() | |
153 | */ | |
154 | struct wxComboCtrlFeatures | |
155 | { | |
156 | enum | |
157 | { | |
158 | MovableButton = 0x0001, ///< Button can be on either side of control. | |
159 | BitmapButton = 0x0002, ///< Button may be replaced with bitmap. | |
160 | ButtonSpacing = 0x0004, ///< Button can have spacing from the edge | |
161 | ///< of the control. | |
162 | TextIndent = 0x0008, ///< wxComboCtrl::SetMargins() can be used. | |
163 | PaintControl = 0x0010, ///< Combo control itself can be custom painted. | |
164 | PaintWritable = 0x0020, ///< A variable-width area in front of writable | |
165 | ///< combo control's textctrl can be custom | |
166 | ///< painted. | |
167 | Borderless = 0x0040, ///< wxNO_BORDER window style works. | |
168 | ||
169 | All = MovableButton | BitmapButton | ButtonSpacing | | |
170 | TextIndent | PaintControl | PaintWritable | | |
171 | Borderless ///< All features. | |
172 | }; | |
173 | }; | |
174 | ||
175 | ||
176 | /** | |
177 | @class wxComboCtrl | |
178 | ||
179 | A combo control is a generic combobox that allows totally custom popup. In | |
180 | addition it has other customization features. For instance, position and | |
181 | size of the dropdown button can be changed. | |
182 | ||
183 | @section comboctrl_custompopup Setting Custom Popup for wxComboCtrl | |
184 | ||
185 | wxComboCtrl needs to be told somehow which control to use and this is done | |
186 | by SetPopupControl(). However, we need something more than just a wxControl | |
187 | in this method as, for example, we need to call | |
188 | SetStringValue("initial text value") and wxControl doesn't have such | |
189 | method. So we also need a wxComboPopup which is an interface which must be | |
190 | implemented by a control to be usable as a popup. | |
191 | ||
192 | We couldn't derive wxComboPopup from wxControl as this would make it | |
193 | impossible to have a class deriving from a wxWidgets control and from it, | |
194 | so instead it is just a mix-in. | |
195 | ||
196 | Here's a minimal sample of wxListView popup: | |
197 | ||
198 | @code | |
199 | #include <wx/combo.h> | |
200 | #include <wx/listctrl.h> | |
201 | ||
202 | class wxListViewComboPopup : public wxListView, public wxComboPopup | |
203 | { | |
204 | public: | |
205 | // Initialize member variables | |
206 | virtual void Init() | |
207 | { | |
208 | m_value = -1; | |
209 | } | |
210 | ||
211 | // Create popup control | |
212 | virtual bool Create(wxWindow* parent) | |
213 | { | |
214 | return wxListView::Create(parent,1,wxPoint(0,0),wxDefaultSize); | |
215 | } | |
216 | ||
217 | // Return pointer to the created control | |
218 | virtual wxWindow *GetControl() { return this; } | |
219 | ||
220 | // Translate string into a list selection | |
221 | virtual void SetStringValue(const wxString& s) | |
222 | { | |
223 | int n = wxListView::FindItem(-1,s); | |
224 | if ( n >= 0 && n < wxListView::GetItemCount() ) | |
225 | wxListView::Select(n); | |
226 | } | |
227 | ||
228 | // Get list selection as a string | |
229 | virtual wxString GetStringValue() const | |
230 | { | |
231 | if ( m_value >= 0 ) | |
232 | return wxListView::GetItemText(m_value); | |
233 | return wxEmptyString; | |
234 | } | |
235 | ||
236 | // Do mouse hot-tracking (which is typical in list popups) | |
237 | void OnMouseMove(wxMouseEvent& event) | |
238 | { | |
239 | // TODO: Move selection to cursor | |
240 | } | |
241 | ||
242 | // On mouse left up, set the value and close the popup | |
243 | void OnMouseClick(wxMouseEvent& WXUNUSED(event)) | |
244 | { | |
245 | m_value = wxListView::GetFirstSelected(); | |
246 | ||
247 | // TODO: Send event as well | |
248 | ||
249 | Dismiss(); | |
250 | } | |
251 | ||
252 | protected: | |
253 | ||
254 | int m_value; // current item index | |
255 | ||
256 | private: | |
257 | wxDECLARE_EVENT_TABLE(); | |
258 | }; | |
259 | ||
260 | wxBEGIN_EVENT_TABLE(wxListViewComboPopup, wxListView) | |
261 | EVT_MOTION(wxListViewComboPopup::OnMouseMove) | |
262 | EVT_LEFT_UP(wxListViewComboPopup::OnMouseClick) | |
263 | wxEND_EVENT_TABLE() | |
264 | @endcode | |
265 | ||
266 | Here's how you would create and populate it in a dialog constructor: | |
267 | ||
268 | @code | |
269 | wxComboCtrl* comboCtrl = new wxComboCtrl(this, wxID_ANY, wxEmptyString); | |
270 | ||
271 | wxListViewComboPopup* popupCtrl = new wxListViewComboPopup(); | |
272 | ||
273 | // It is important to call SetPopupControl() as soon as possible | |
274 | comboCtrl->SetPopupControl(popupCtrl); | |
275 | ||
276 | // Populate using wxListView methods | |
277 | popupCtrl->InsertItem(popupCtrl->GetItemCount(), "First Item"); | |
278 | popupCtrl->InsertItem(popupCtrl->GetItemCount(), "Second Item"); | |
279 | popupCtrl->InsertItem(popupCtrl->GetItemCount(), "Third Item"); | |
280 | @endcode | |
281 | ||
282 | @beginStyleTable | |
283 | @style{wxCB_READONLY} | |
284 | Text will not be editable. | |
285 | @style{wxCB_SORT} | |
286 | Sorts the entries in the list alphabetically. | |
287 | @style{wxTE_PROCESS_ENTER} | |
288 | The control will generate the event wxEVT_COMMAND_TEXT_ENTER | |
289 | (otherwise pressing Enter key is either processed internally by the | |
290 | control or used for navigation between dialog controls). Windows | |
291 | only. | |
292 | @style{wxCC_SPECIAL_DCLICK} | |
293 | Double-clicking triggers a call to popup's OnComboDoubleClick. | |
294 | Actual behaviour is defined by a derived class. For instance, | |
295 | wxOwnerDrawnComboBox will cycle an item. This style only applies if | |
296 | wxCB_READONLY is used as well. | |
297 | @style{wxCC_STD_BUTTON} | |
298 | Drop button will behave more like a standard push button. | |
299 | @endStyleTable | |
300 | ||
301 | @beginEventEmissionTable{wxCommandEvent} | |
302 | @event{EVT_TEXT(id, func)} | |
303 | Process a wxEVT_COMMAND_TEXT_UPDATED event, when the text changes. | |
304 | @event{EVT_TEXT_ENTER(id, func)} | |
305 | Process a wxEVT_COMMAND_TEXT_ENTER event, when RETURN is pressed in | |
306 | the combo control. | |
307 | @event{EVT_COMBOBOX_DROPDOWN(id, func)} | |
308 | Process a wxEVT_COMMAND_COMBOBOX_DROPDOWN event, which is generated | |
309 | when the popup window is shown (drops down). | |
310 | @event{EVT_COMBOBOX_CLOSEUP(id, func)} | |
311 | Process a wxEVT_COMMAND_COMBOBOX_CLOSEUP event, which is generated | |
312 | when the popup window of the combo control disappears (closes up). | |
313 | You should avoid adding or deleting items in this event. | |
314 | @endEventTable | |
315 | ||
316 | @library{wxbase} | |
317 | @category{ctrl} | |
318 | @appearance{comboctrl.png} | |
319 | ||
320 | @see wxComboBox, wxChoice, wxOwnerDrawnComboBox, wxComboPopup, | |
321 | wxCommandEvent | |
322 | */ | |
323 | class wxComboCtrl : public wxControl | |
324 | { | |
325 | public: | |
326 | /** | |
327 | Default constructor. | |
328 | */ | |
329 | wxComboCtrl(); | |
330 | ||
331 | /** | |
332 | Constructor, creating and showing a combo control. | |
333 | ||
334 | @param parent | |
335 | Parent window. Must not be @NULL. | |
336 | @param id | |
337 | Window identifier. The value wxID_ANY indicates a default value. | |
338 | @param value | |
339 | Initial selection string. An empty string indicates no selection. | |
340 | @param pos | |
341 | Window position. | |
342 | If ::wxDefaultPosition is specified then a default position is chosen. | |
343 | @param size | |
344 | Window size. | |
345 | If ::wxDefaultSize is specified then the window is sized appropriately. | |
346 | @param style | |
347 | Window style. See wxComboCtrl. | |
348 | @param validator | |
349 | Window validator. | |
350 | @param name | |
351 | Window name. | |
352 | ||
353 | @see Create(), wxValidator | |
354 | */ | |
355 | wxComboCtrl(wxWindow* parent, wxWindowID id = wxID_ANY, | |
356 | const wxString& value = wxEmptyString, | |
357 | const wxPoint& pos = wxDefaultPosition, | |
358 | const wxSize& size = wxDefaultSize, | |
359 | long style = 0, | |
360 | const wxValidator& validator = wxDefaultValidator, | |
361 | const wxString& name = wxComboBoxNameStr); | |
362 | ||
363 | /** | |
364 | Destructor, destroying the combo control. | |
365 | */ | |
366 | virtual ~wxComboCtrl(); | |
367 | ||
368 | /** | |
369 | Copies the selected text to the clipboard. | |
370 | */ | |
371 | virtual void Copy(); | |
372 | ||
373 | /** | |
374 | Creates the combo control for two-step construction. Derived classes | |
375 | should call or replace this function. See wxComboCtrl() for further | |
376 | details. | |
377 | */ | |
378 | bool Create(wxWindow* parent, wxWindowID id = wxID_ANY, | |
379 | const wxString& value = wxEmptyString, | |
380 | const wxPoint& pos = wxDefaultPosition, | |
381 | const wxSize& size = wxDefaultSize, | |
382 | long style = 0, | |
383 | const wxValidator& validator = wxDefaultValidator, | |
384 | const wxString& name = wxComboBoxNameStr); | |
385 | ||
386 | /** | |
387 | Copies the selected text to the clipboard and removes the selection. | |
388 | */ | |
389 | virtual void Cut(); | |
390 | ||
391 | /** | |
392 | Enables or disables popup animation, if any, depending on the value of | |
393 | the argument. | |
394 | */ | |
395 | void EnablePopupAnimation(bool enable = true); | |
396 | ||
397 | /** | |
398 | Returns disabled button bitmap that has been set with | |
399 | SetButtonBitmaps(). | |
400 | ||
401 | @return A reference to the disabled state bitmap. | |
402 | */ | |
403 | const wxBitmap& GetBitmapDisabled() const; | |
404 | ||
405 | /** | |
406 | Returns button mouse hover bitmap that has been set with | |
407 | SetButtonBitmaps(). | |
408 | ||
409 | @return A reference to the mouse hover state bitmap. | |
410 | */ | |
411 | const wxBitmap& GetBitmapHover() const; | |
412 | ||
413 | /** | |
414 | Returns default button bitmap that has been set with | |
415 | SetButtonBitmaps(). | |
416 | ||
417 | @return A reference to the normal state bitmap. | |
418 | */ | |
419 | const wxBitmap& GetBitmapNormal() const; | |
420 | ||
421 | /** | |
422 | Returns depressed button bitmap that has been set with | |
423 | SetButtonBitmaps(). | |
424 | ||
425 | @return A reference to the depressed state bitmap. | |
426 | */ | |
427 | const wxBitmap& GetBitmapPressed() const; | |
428 | ||
429 | /** | |
430 | Returns current size of the dropdown button. | |
431 | */ | |
432 | wxSize GetButtonSize(); | |
433 | ||
434 | /** | |
435 | Returns custom painted area in control. | |
436 | ||
437 | @see SetCustomPaintWidth(). | |
438 | */ | |
439 | int GetCustomPaintWidth() const; | |
440 | ||
441 | /** | |
442 | Returns features supported by wxComboCtrl. If needed feature is | |
443 | missing, you need to instead use wxGenericComboCtrl, which however may | |
444 | lack a native look and feel (but otherwise sports identical API). | |
445 | ||
446 | @return Value returned is a combination of the flags defined in | |
447 | wxComboCtrlFeatures. | |
448 | */ | |
449 | static int GetFeatures(); | |
450 | ||
451 | /** | |
452 | Returns the current hint string. | |
453 | ||
454 | See SetHint() for more information about hints. | |
455 | ||
456 | @since 2.9.1 | |
457 | */ | |
458 | virtual wxString GetHint() const; | |
459 | ||
460 | /** | |
461 | Returns the insertion point for the combo control's text field. | |
462 | ||
463 | @note Under Windows, this function always returns 0 if the combo | |
464 | control doesn't have the focus. | |
465 | */ | |
466 | virtual long GetInsertionPoint() const; | |
467 | ||
468 | /** | |
469 | Returns the last position in the combo control text field. | |
470 | */ | |
471 | virtual long GetLastPosition() const; | |
472 | ||
473 | /** | |
474 | Returns the margins used by the control. The @c x field of the returned | |
475 | point is the horizontal margin and the @c y field is the vertical one. | |
476 | ||
477 | @remarks If given margin cannot be accurately determined, its value | |
478 | will be set to -1. | |
479 | ||
480 | @see SetMargins() | |
481 | ||
482 | @since 2.9.1 | |
483 | */ | |
484 | wxPoint GetMargins() const; | |
485 | ||
486 | /** | |
487 | Returns current popup interface that has been set with | |
488 | SetPopupControl(). | |
489 | */ | |
490 | wxComboPopup* GetPopupControl(); | |
491 | ||
492 | /** | |
493 | Returns popup window containing the popup control. | |
494 | */ | |
495 | wxWindow* GetPopupWindow() const; | |
496 | ||
497 | /** | |
498 | Get the text control which is part of the combo control. | |
499 | */ | |
500 | wxTextCtrl* GetTextCtrl() const; | |
501 | ||
502 | /** | |
503 | Returns actual indentation in pixels. | |
504 | ||
505 | @deprecated Use GetMargins() instead. | |
506 | */ | |
507 | wxCoord GetTextIndent() const; | |
508 | ||
509 | /** | |
510 | Returns area covered by the text field (includes everything except | |
511 | borders and the dropdown button). | |
512 | */ | |
513 | const wxRect& GetTextRect() const; | |
514 | ||
515 | /** | |
516 | Returns text representation of the current value. For writable combo | |
517 | control it always returns the value in the text field. | |
518 | */ | |
519 | virtual wxString GetValue() const; | |
520 | ||
521 | /** | |
522 | Dismisses the popup window. | |
523 | ||
524 | @param generateEvent | |
525 | Set this to @true in order to generate | |
526 | wxEVT_COMMAND_COMBOBOX_CLOSEUP event. | |
527 | */ | |
528 | virtual void HidePopup(bool generateEvent=false); | |
529 | ||
530 | /** | |
531 | Returns @true if the popup is currently shown | |
532 | */ | |
533 | bool IsPopupShown() const; | |
534 | ||
535 | /** | |
536 | Returns @true if the popup window is in the given state. Possible | |
537 | values are: | |
538 | ||
539 | @beginTable | |
540 | @row2col{wxComboCtrl::Hidden, Popup window is hidden.} | |
541 | @row2col{wxComboCtrl::Animating, Popup window is being shown, but the | |
542 | popup animation has not yet finished.} | |
543 | @row2col{wxComboCtrl::Visible, Popup window is fully visible.} | |
544 | @endTable | |
545 | */ | |
546 | bool IsPopupWindowState(int state) const; | |
547 | ||
548 | /** | |
549 | Implement in a derived class to define what happens on dropdown button | |
550 | click. Default action is to show the popup. | |
551 | ||
552 | @note If you implement this to do something else than show the popup, | |
553 | you must then also implement DoSetPopupControl() to always return | |
554 | @NULL. | |
555 | */ | |
556 | virtual void OnButtonClick(); | |
557 | ||
558 | /** | |
559 | Pastes text from the clipboard to the text field. | |
560 | */ | |
561 | virtual void Paste(); | |
562 | ||
563 | /** | |
564 | Removes the text between the two positions in the combo control text | |
565 | field. | |
566 | ||
567 | @param from | |
568 | The first position. | |
569 | @param to | |
570 | The last position. | |
571 | */ | |
572 | virtual void Remove(long from, long to); | |
573 | ||
574 | /** | |
575 | Replaces the text between two positions with the given text, in the | |
576 | combo control text field. | |
577 | ||
578 | @param from | |
579 | The first position. | |
580 | @param to | |
581 | The second position. | |
582 | @param text | |
583 | The text to insert. | |
584 | */ | |
585 | virtual void Replace(long from, long to, const wxString& text); | |
586 | ||
587 | /** | |
588 | Sets custom dropdown button graphics. | |
589 | ||
590 | @param bmpNormal | |
591 | Default button image. | |
592 | @param pushButtonBg | |
593 | If @true, blank push button background is painted below the image. | |
594 | @param bmpPressed | |
595 | Depressed button image. | |
596 | @param bmpHover | |
597 | Button image when mouse hovers above it. This should be ignored on | |
598 | platforms and themes that do not generally draw different kind of | |
599 | button on mouse hover. | |
600 | @param bmpDisabled | |
601 | Disabled button image. | |
602 | */ | |
603 | void SetButtonBitmaps(const wxBitmap& bmpNormal, | |
604 | bool pushButtonBg = false, | |
605 | const wxBitmap& bmpPressed = wxNullBitmap, | |
606 | const wxBitmap& bmpHover = wxNullBitmap, | |
607 | const wxBitmap& bmpDisabled = wxNullBitmap); | |
608 | ||
609 | /** | |
610 | Sets size and position of dropdown button. | |
611 | ||
612 | @param width | |
613 | Button width. Value = 0 specifies default. | |
614 | @param height | |
615 | Button height. Value = 0 specifies default. | |
616 | @param side | |
617 | Indicates which side the button will be placed. Value can be wxLEFT | |
618 | or wxRIGHT. | |
619 | @param spacingX | |
620 | Horizontal spacing around the button. Default is 0. | |
621 | */ | |
622 | void SetButtonPosition(int width = -1, int height = -1, | |
623 | int side = wxRIGHT, int spacingX = 0); | |
624 | ||
625 | /** | |
626 | Set width, in pixels, of custom painted area in control without | |
627 | @c wxCB_READONLY style. In read-only wxOwnerDrawnComboBox, this is used | |
628 | to indicate area that is not covered by the focus rectangle. | |
629 | */ | |
630 | void SetCustomPaintWidth(int width); | |
631 | ||
632 | /** | |
633 | Sets a hint shown in an empty unfocused combo control. | |
634 | ||
635 | Notice that hints are known as <em>cue banners</em> under MSW or | |
636 | <em>placeholder strings</em> under OS X. | |
637 | ||
638 | @see wxTextEntry::SetHint() | |
639 | ||
640 | @since 2.9.1 | |
641 | */ | |
642 | virtual void SetHint(const wxString& hint); | |
643 | ||
644 | /** | |
645 | Sets the insertion point in the text field. | |
646 | ||
647 | @param pos | |
648 | The new insertion point. | |
649 | */ | |
650 | virtual void SetInsertionPoint(long pos); | |
651 | ||
652 | /** | |
653 | Sets the insertion point at the end of the combo control text field. | |
654 | */ | |
655 | virtual void SetInsertionPointEnd(); | |
656 | ||
657 | //@{ | |
658 | /** | |
659 | Attempts to set the control margins. When margins are given as wxPoint, | |
660 | x indicates the left and y the top margin. Use -1 to indicate that | |
661 | an existing value should be used. | |
662 | ||
663 | @return | |
664 | @true if setting of all requested margins was successful. | |
665 | ||
666 | @since 2.9.1 | |
667 | */ | |
668 | bool SetMargins(const wxPoint& pt); | |
669 | bool SetMargins(wxCoord left, wxCoord top = -1); | |
670 | //@} | |
671 | ||
672 | /** | |
673 | Set side of the control to which the popup will align itself. Valid | |
674 | values are @c wxLEFT, @c wxRIGHT and 0. The default value 0 means that | |
675 | the most appropriate side is used (which, currently, is always | |
676 | @c wxLEFT). | |
677 | */ | |
678 | void SetPopupAnchor(int anchorSide); | |
679 | ||
680 | /** | |
681 | Set popup interface class derived from wxComboPopup. This method should | |
682 | be called as soon as possible after the control has been created, | |
683 | unless OnButtonClick() has been overridden. | |
684 | */ | |
685 | void SetPopupControl(wxComboPopup* popup); | |
686 | ||
687 | /** | |
688 | Extends popup size horizontally, relative to the edges of the combo | |
689 | control. | |
690 | ||
691 | @param extLeft | |
692 | How many pixel to extend beyond the left edge of the control. | |
693 | Default is 0. | |
694 | @param extRight | |
695 | How many pixel to extend beyond the right edge of the control. | |
696 | Default is 0. | |
697 | ||
698 | @remarks Popup minimum width may override arguments. It is up to the | |
699 | popup to fully take this into account. | |
700 | */ | |
701 | void SetPopupExtents(int extLeft, int extRight); | |
702 | ||
703 | /** | |
704 | Sets preferred maximum height of the popup. | |
705 | ||
706 | @remarks Value -1 indicates the default. | |
707 | */ | |
708 | void SetPopupMaxHeight(int height); | |
709 | ||
710 | /** | |
711 | Sets minimum width of the popup. If wider than combo control, it will | |
712 | extend to the left. | |
713 | ||
714 | @remarks Value -1 indicates the default. Also, popup implementation may | |
715 | choose to ignore this. | |
716 | */ | |
717 | void SetPopupMinWidth(int width); | |
718 | ||
719 | /** | |
720 | Selects the text between the two positions, in the combo control text | |
721 | field. | |
722 | ||
723 | @param from | |
724 | The first position. | |
725 | @param to | |
726 | The second position. | |
727 | */ | |
728 | virtual void SetSelection(long from, long to); | |
729 | ||
730 | /** | |
731 | Sets the text for the text field without affecting the popup. Thus, | |
732 | unlike SetValue(), it works equally well with combo control using | |
733 | @c wxCB_READONLY style. | |
734 | */ | |
735 | void SetText(const wxString& value); | |
736 | ||
737 | /** | |
738 | Set a custom window style for the embedded wxTextCtrl. Usually you | |
739 | will need to use this during two-step creation, just before Create(). | |
740 | For example: | |
741 | ||
742 | @code | |
743 | wxComboCtrl* comboCtrl = new wxComboCtrl(); | |
744 | ||
745 | // Let's make the text right-aligned | |
746 | comboCtrl->SetTextCtrlStyle(wxTE_RIGHT); | |
747 | ||
748 | comboCtrl->Create(parent, wxID_ANY, wxEmptyString); | |
749 | @endcode | |
750 | */ | |
751 | void SetTextCtrlStyle( int style ); | |
752 | ||
753 | /** | |
754 | This will set the space in pixels between left edge of the control and | |
755 | the text, regardless whether control is read-only or not. Value -1 can | |
756 | be given to indicate platform default. | |
757 | ||
758 | @deprecated Use SetMargins() instead. | |
759 | */ | |
760 | void SetTextIndent(int indent); | |
761 | ||
762 | /** | |
763 | Sets the text for the combo control text field. | |
764 | ||
765 | @note For a combo control with @c wxCB_READONLY style the string must | |
766 | be accepted by the popup (for instance, exist in the dropdown | |
767 | list), otherwise the call to SetValue() is ignored. | |
768 | */ | |
769 | virtual void SetValue(const wxString& value); | |
770 | ||
771 | /** | |
772 | Same as SetValue(), but also sends wxCommandEvent of type | |
773 | wxEVT_COMMAND_TEXT_UPDATED if @a withEvent is @true. | |
774 | */ | |
775 | void SetValueWithEvent(const wxString& value, bool withEvent = true); | |
776 | ||
777 | /** | |
778 | Show the popup. | |
779 | */ | |
780 | virtual void ShowPopup(); | |
781 | ||
782 | /** | |
783 | Undoes the last edit in the text field. Windows only. | |
784 | */ | |
785 | virtual void Undo(); | |
786 | ||
787 | /** | |
788 | Enable or disable usage of an alternative popup window, which | |
789 | guarantees ability to focus the popup control, and allows common native | |
790 | controls to function normally. This alternative popup window is usually | |
791 | a wxDialog, and as such, when it is shown, its parent top-level window | |
792 | will appear as if the focus has been lost from it. | |
793 | */ | |
794 | void UseAltPopupWindow(bool enable = true); | |
795 | ||
796 | protected: | |
797 | ||
798 | /** | |
799 | This member function is not normally called in application code. | |
800 | Instead, it can be implemented in a derived class to create a custom | |
801 | popup animation. | |
802 | ||
803 | The parameters are the same as those for DoShowPopup(). | |
804 | ||
805 | @return @true if animation finishes before the function returns, | |
806 | @false otherwise. In the latter case you need to manually call | |
807 | DoShowPopup() after the animation ends. | |
808 | */ | |
809 | virtual bool AnimateShow(const wxRect& rect, int flags); | |
810 | ||
811 | /** | |
812 | This member function is not normally called in application code. | |
813 | Instead, it can be implemented in a derived class to return default | |
814 | wxComboPopup, incase @a popup is @NULL. | |
815 | ||
816 | @note If you have implemented OnButtonClick() to do something else than | |
817 | show the popup, then DoSetPopupControl() must always set @a popup | |
818 | to @NULL. | |
819 | */ | |
820 | virtual void DoSetPopupControl(wxComboPopup* popup); | |
821 | ||
822 | /** | |
823 | This member function is not normally called in application code. | |
824 | Instead, it must be called in a derived class to make sure popup is | |
825 | properly shown after a popup animation has finished (but only if | |
826 | AnimateShow() did not finish the animation within its function scope). | |
827 | ||
828 | @param rect | |
829 | Position to show the popup window at, in screen coordinates. | |
830 | @param flags | |
831 | Combination of any of the following: | |
832 | @beginTable | |
833 | @row2col{wxComboCtrl::ShowAbove, | |
834 | Popup is shown above the control instead of below.} | |
835 | @row2col{wxComboCtrl::CanDeferShow, | |
836 | Showing the popup can be deferred to happen sometime after | |
837 | ShowPopup() has finished. In this case, AnimateShow() must | |
838 | return false.} | |
839 | @endTable | |
840 | */ | |
841 | virtual void DoShowPopup(const wxRect& rect, int flags); | |
842 | }; | |
843 |