1 ///////////////////////////////////////////////////////////////////////////////
2 // Name: wx/univ/listbox.h
3 // Purpose: the universal listbox
4 // Author: Vadim Zeitlin
8 // Copyright: (c) 2000 Vadim Zeitlin <zeitlin@dptmaths.ens-cachan.fr>
9 // Licence: wxWindows licence
10 ///////////////////////////////////////////////////////////////////////////////
12 #ifndef _WX_UNIV_LISTBOX_H_
13 #define _WX_UNIV_LISTBOX_H_
15 #include "wx/scrolwin.h" // for wxScrollHelper
16 #include "wx/dynarray.h"
17 #include "wx/arrstr.h"
19 // ----------------------------------------------------------------------------
20 // the actions supported by this control
21 // ----------------------------------------------------------------------------
23 // change the current item
24 #define wxACTION_LISTBOX_SETFOCUS _T("setfocus") // select the item
25 #define wxACTION_LISTBOX_MOVEDOWN _T("down") // select item below
26 #define wxACTION_LISTBOX_MOVEUP _T("up") // select item above
27 #define wxACTION_LISTBOX_PAGEDOWN _T("pagedown") // go page down
28 #define wxACTION_LISTBOX_PAGEUP _T("pageup") // go page up
29 #define wxACTION_LISTBOX_START _T("start") // go to first item
30 #define wxACTION_LISTBOX_END _T("end") // go to last item
31 #define wxACTION_LISTBOX_FIND _T("find") // find item by 1st letter
33 // do something with the current item
34 #define wxACTION_LISTBOX_ACTIVATE _T("activate") // activate (choose)
35 #define wxACTION_LISTBOX_TOGGLE _T("toggle") // togglee selected state
36 #define wxACTION_LISTBOX_SELECT _T("select") // sel this, unsel others
37 #define wxACTION_LISTBOX_SELECTADD _T("selectadd") // add to selection
38 #define wxACTION_LISTBOX_UNSELECT _T("unselect") // unselect
39 #define wxACTION_LISTBOX_ANCHOR _T("selanchor") // anchor selection
41 // do something with the selection globally (not for single selection ones)
42 #define wxACTION_LISTBOX_SELECTALL _T("selectall") // select all items
43 #define wxACTION_LISTBOX_UNSELECTALL _T("unselectall") // unselect all items
44 #define wxACTION_LISTBOX_SELTOGGLE _T("togglesel") // invert the selection
45 #define wxACTION_LISTBOX_EXTENDSEL _T("extend") // extend to item
47 // ----------------------------------------------------------------------------
48 // wxListBox: a list of selectable items
49 // ----------------------------------------------------------------------------
51 class WXDLLEXPORT wxListBox
: public wxListBoxBase
, public wxScrollHelper
55 wxListBox() { Init(); }
56 wxListBox(wxWindow
*parent
,
58 const wxPoint
& pos
= wxDefaultPosition
,
59 const wxSize
& size
= wxDefaultSize
,
60 int n
= 0, const wxString choices
[] = (const wxString
*) NULL
,
62 const wxValidator
& validator
= wxDefaultValidator
,
63 const wxString
& name
= wxListBoxNameStr
)
67 Create(parent
, id
, pos
, size
, n
, choices
, style
, validator
, name
);
69 wxListBox(wxWindow
*parent
,
73 const wxArrayString
& choices
,
75 const wxValidator
& validator
= wxDefaultValidator
,
76 const wxString
& name
= wxListBoxNameStr
);
80 bool Create(wxWindow
*parent
,
82 const wxPoint
& pos
= wxDefaultPosition
,
83 const wxSize
& size
= wxDefaultSize
,
84 int n
= 0, const wxString choices
[] = (const wxString
*) NULL
,
86 const wxValidator
& validator
= wxDefaultValidator
,
87 const wxString
& name
= wxListBoxNameStr
);
88 bool Create(wxWindow
*parent
,
92 const wxArrayString
& choices
,
94 const wxValidator
& validator
= wxDefaultValidator
,
95 const wxString
& name
= wxListBoxNameStr
);
97 // implement the listbox interface defined by wxListBoxBase
99 virtual void Delete(int n
);
101 virtual int GetCount() const
102 { return (int)m_strings
->GetCount(); }
103 virtual wxString
GetString(int n
) const
104 { return m_strings
->Item(n
); }
105 virtual void SetString(int n
, const wxString
& s
);
106 virtual int FindString(const wxString
& s
) const
107 { return m_strings
->Index(s
); }
109 virtual bool IsSelected(int n
) const
110 { return m_selections
.Index(n
) != wxNOT_FOUND
; }
111 virtual void DoSetSelection(int n
, bool select
);
112 virtual int GetSelection() const;
113 virtual int GetSelections(wxArrayInt
& aSelections
) const;
116 virtual int DoAppendOnly(const wxString
& item
);
117 virtual int DoAppend(const wxString
& item
);
118 virtual void DoInsertItems(const wxArrayString
& items
, int pos
);
119 virtual void DoSetItems(const wxArrayString
& items
, void **clientData
);
121 virtual void DoSetFirstItem(int n
);
123 virtual void DoSetItemClientData(int n
, void* clientData
);
124 virtual void* DoGetItemClientData(int n
) const;
125 virtual void DoSetItemClientObject(int n
, wxClientData
* clientData
);
126 virtual wxClientData
* DoGetItemClientObject(int n
) const;
129 // override some more base class methods
130 virtual bool SetFont(const wxFont
& font
);
132 // the wxUniversal-specific methods
133 // --------------------------------
135 // the current item is the same as the selected one for wxLB_SINGLE
136 // listboxes but for the other ones it is just the focused item which may
137 // be selected or not
138 int GetCurrentItem() const { return m_current
; }
139 void SetCurrentItem(int n
);
141 // select the item which is diff items below the current one
142 void ChangeCurrent(int diff
);
144 // activate (i.e. send a LISTBOX_DOUBLECLICKED message) the specified or
145 // current (if -1) item
146 void Activate(int item
= -1);
148 // select or unselect the specified or current (if -1) item
149 void DoSelect(int item
= -1, bool sel
= true);
151 // more readable wrapper
152 void DoUnselect(int item
) { DoSelect(item
, false); }
154 // select an item and send a notification about it
155 void SelectAndNotify(int item
);
157 // ensure that the given item is visible by scrolling it into view
158 virtual void EnsureVisible(int n
);
160 // find the first item [strictly] after the current one which starts with
161 // the given string and make it the current one, return true if the current
163 bool FindItem(const wxString
& prefix
, bool strictlyAfter
= false);
164 bool FindNextItem(const wxString
& prefix
) { return FindItem(prefix
, true); }
166 // extend the selection to span the range from the anchor (see below) to
167 // the specified or current item
168 void ExtendSelection(int itemTo
= -1);
170 // make this item the new selection anchor: extending selection with
171 // ExtendSelection() will work with it
172 void AnchorSelection(int itemFrom
) { m_selAnchor
= itemFrom
; }
174 // get, calculating it if necessary, the number of items per page, the
175 // height of each line and the max width of an item
176 int GetItemsPerPage() const;
177 wxCoord
GetLineHeight() const;
178 wxCoord
GetMaxWidth() const;
180 // override the wxControl virtual methods
181 virtual bool PerformAction(const wxControlAction
& action
,
183 const wxString
& strArg
= wxEmptyString
);
186 virtual void OnInternalIdle();
190 virtual wxSize
DoGetBestClientSize() const;
191 virtual void DoSetSize(int x
, int y
,
192 int width
, int height
,
193 int sizeFlags
= wxSIZE_AUTO
);
195 virtual void DoDraw(wxControlRenderer
*renderer
);
196 virtual wxBorder
GetDefaultBorder() const;
198 // common part of all ctors
202 void OnSize(wxSizeEvent
& event
);
204 // common part of Clear() and DoSetItems(): clears everything
205 virtual void DoClear();
207 // refresh the given item(s) or everything
208 void RefreshItems(int from
, int count
);
209 void RefreshItem(int n
);
210 void RefreshFromItemToEnd(int n
);
213 // send an event of the given type (using m_current by default)
214 bool SendEvent(wxEventType type
, int item
= -1);
216 // calculate the number of items per page using our current size
217 void CalcItemsPerPage();
219 // can/should we have a horz scrollbar?
220 bool HasHorzScrollbar() const
221 { return (m_windowStyle
& wxLB_HSCROLL
) != 0; }
223 // redraw the items in the given range only: called from DoDraw()
224 virtual void DoDrawRange(wxControlRenderer
*renderer
,
225 int itemFirst
, int itemLast
);
227 // update the scrollbars and then ensure that the item is visible
228 void DoEnsureVisible(int n
);
230 // mark horz scrollbar for updating
231 void RefreshHorzScrollbar();
233 // update (show/hide/adjust) the scrollbars
234 void UpdateScrollbars();
236 // refresh the items specified by m_updateCount and m_updateFrom
239 // the array containing all items (it is sorted if the listbox has
241 wxArrayString
* m_strings
;
243 // this array contains the indices of the selected items (for the single
244 // selection listboxes only the first element of it is used and contains
245 // the current selection)
246 wxArrayInt m_selections
;
248 // and this one the client data (either void or wxClientData)
249 wxArrayPtrVoid m_itemsClientData
;
255 // the range of elements which must be updated: if m_updateCount is 0 no
256 // update is needed, if it is -1 everything must be updated, otherwise
257 // m_updateCount items starting from m_updateFrom have to be redrawn
261 // the height of one line in the listbox (all lines have the same height)
262 wxCoord m_lineHeight
;
264 // the maximal width of a listbox item and the item which has it
268 // the extents of horz and vert scrollbars
272 // the number of items per page
273 size_t m_itemsPerPage
;
275 // if the number of items has changed we may need to show/hide the
277 bool m_updateScrollbarX
, m_updateScrollbarY
,
278 m_showScrollbarX
, m_showScrollbarY
;
280 // if the current item has changed, we might need to scroll if it went out
282 bool m_currentChanged
;
284 // the anchor from which the selection is extended for the listboxes with
285 // wxLB_EXTENDED style - this is set to the last item which was selected
286 // by not extending the selection but by choosing it directly
289 DECLARE_EVENT_TABLE()
290 DECLARE_DYNAMIC_CLASS(wxListBox
)
293 // ----------------------------------------------------------------------------
294 // wxStdListboxInputHandler: handles mouse and kbd in a single or multi
296 // ----------------------------------------------------------------------------
298 class WXDLLEXPORT wxStdListboxInputHandler
: public wxStdInputHandler
301 // if pressing the mouse button in a multiselection listbox should toggle
302 // the item under mouse immediately, then specify true as the second
303 // parameter (this is the standard behaviour, under GTK the item is toggled
304 // only when the mouse is released in the multi selection listbox)
305 wxStdListboxInputHandler(wxInputHandler
*inphand
,
306 bool toggleOnPressAlways
= true);
308 // base class methods
309 virtual bool HandleKey(wxInputConsumer
*consumer
,
310 const wxKeyEvent
& event
,
312 virtual bool HandleMouse(wxInputConsumer
*consumer
,
313 const wxMouseEvent
& event
);
314 virtual bool HandleMouseMove(wxInputConsumer
*consumer
,
315 const wxMouseEvent
& event
);
318 // return the item under mouse, 0 if the mouse is above the listbox or
319 // GetCount() if it is below it
320 int HitTest(const wxListBox
*listbox
, const wxMouseEvent
& event
);
322 // parts of HitTest(): first finds the pseudo (because not in range) index
323 // of the item and the second one adjusts it if necessary - that is if the
324 // third one returns false
325 int HitTestUnsafe(const wxListBox
*listbox
, const wxMouseEvent
& event
);
326 int FixItemIndex(const wxListBox
*listbox
, int item
);
327 bool IsValidIndex(const wxListBox
*listbox
, int item
);
329 // init m_btnCapture and m_actionMouse
330 wxControlAction
SetupCapture(wxListBox
*lbox
,
331 const wxMouseEvent
& event
,
334 wxRenderer
*m_renderer
;
336 // the button which initiated the mouse capture (currently 0 or 1)
339 // the action to perform when the mouse moves while we capture it
340 wxControlAction m_actionMouse
;
342 // the ctor parameter toggleOnPressAlways (see comments near it)
343 bool m_toggleOnPressAlways
;
345 // do we track the mouse outside the window when it is captured?
346 bool m_trackMouseOutside
;
349 #endif // _WX_UNIV_LISTBOX_H_