/////////////////////////////////////////////////////////////////////////////
// Name: listbox.h
-// Purpose: documentation for wxListBox class
+// Purpose: interface of wxListBox
// Author: wxWidgets team
// RCS-ID: $Id$
// Licence: wxWindows license
List box elements are numbered from zero. Their number may be limited
under some platforms.
- A listbox callback gets an event wxEVT_COMMAND_LISTBOX_SELECTED for single
- clicks, and
- wxEVT_COMMAND_LISTBOX_DOUBLE_CLICKED for double clicks.
+ A listbox callback gets an event wxEVT_COMMAND_LISTBOX_SELECTED for
+ single clicks, and wxEVT_COMMAND_LISTBOX_DOUBLECLICKED for double clicks.
@beginStyleTable
- @style{wxLB_SINGLE}:
+ @style{wxLB_SINGLE}
Single-selection list.
- @style{wxLB_MULTIPLE}:
+ @style{wxLB_MULTIPLE}
Multiple-selection list: the user can toggle multiple items on and
off.
- @style{wxLB_EXTENDED}:
+ @style{wxLB_EXTENDED}
Extended-selection list: the user can select multiple items using
the SHIFT key and the mouse or special key combinations.
- @style{wxLB_HSCROLL}:
+ @style{wxLB_HSCROLL}
Create horizontal scrollbar if contents are too wide (Windows only).
- @style{wxLB_ALWAYS_SB}:
+ @style{wxLB_ALWAYS_SB}
Always show a vertical scrollbar.
- @style{wxLB_NEEDED_SB}:
+ @style{wxLB_NEEDED_SB}
Only create a vertical scrollbar if needed.
- @style{wxLB_SORT}:
+ @style{wxLB_SORT}
The listbox contents are sorted in alphabetical order.
@endStyleTable
- @beginEventTable
- @event{EVT_LISTBOX(id\, func)}:
+ @beginEventTable{wxCommandEvent}
+ @event{EVT_LISTBOX(id, func)}
Process a wxEVT_COMMAND_LISTBOX_SELECTED event, when an item on the
list is selected or the selection changes.
- @event{EVT_LISTBOX_DCLICK(id\, func)}:
- Process a wxEVT_COMMAND_LISTBOX_DOUBLECLICKED event, when the
+ @event{EVT_LISTBOX_DCLICK(id, func)}
+ Process a wxEVT_COMMAND_LISTBOXDOUBLECLICKED event, when the
listbox is double-clicked.
@endEventTable
@library{wxcore}
@category{ctrl}
- @appearance{listbox.png}
+ <!-- @appearance{listbox.png} -->
- @seealso
- wxChoice, wxComboBox, wxListCtrl, wxCommandEvent
+ @see wxChoice, wxComboBox, wxListCtrl, wxCommandEvent
*/
class wxListBox : public wxControlWithItems
{
public:
- //@{
/**
- Constructor, creating and showing a list box.
-
- @param parent
- Parent window. Must not be @NULL.
-
- @param id
- Window identifier. The value wxID_ANY indicates a default value.
-
- @param pos
- Window position.
-
- @param size
- Window size. If wxDefaultSize is specified then the window is sized
- appropriately.
-
+ Default constructor.
+ */
+ wxListBox();
+
+ /**
+ Constructor
+
@param n
- Number of strings with which to initialise the control.
-
- @param choices
- An array of strings with which to initialise the control.
-
+ Number of strings with which to initialise the control.
@param style
- Window style. See wxListBox.
-
- @param validator
- Window validator.
-
- @param name
- Window name.
-
- @sa Create(), wxValidator
+ Window style. See wxListBox.
*/
- wxListBox();
+
wxListBox(wxWindow* parent, wxWindowID id,
const wxPoint& pos = wxDefaultPosition,
const wxSize& size = wxDefaultSize,
int n = 0,
- const wxString choices[] = @NULL,
+ const wxString choices[] = NULL,
long style = 0,
const wxValidator& validator = wxDefaultValidator,
const wxString& name = "listBox");
+
+ /**
+ Constructor
+
+ @param choices
+ An array of strings with which to initialise the control.
+ @param style
+ Window style. See wxListBox.
+ */
+
wxListBox(wxWindow* parent, wxWindowID id,
const wxPoint& pos,
const wxSize& size,
long style = 0,
const wxValidator& validator = wxDefaultValidator,
const wxString& name = "listBox");
- //@}
/**
Destructor, destroying the list box.
const wxPoint& pos = wxDefaultPosition,
const wxSize& size = wxDefaultSize,
int n,
- const wxString choices[] = @NULL,
+ const wxString choices[] = NULL,
long style = 0,
const wxValidator& validator = wxDefaultValidator,
const wxString& name = "listBox");
/**
Deselects an item in the list box.
-
+
@param n
- The zero-based item to deselect.
-
+ The zero-based item to deselect.
+
@remarks This applies to multiple selection listboxes only.
*/
void Deselect(int n);
/**
Fill an array of ints with the positions of the currently selected items.
-
+
@param selections
- A reference to an wxArrayInt instance that is used to store the result of the
- query.
-
- @returns The number of selections.
-
+ A reference to an wxArrayInt instance that is used to store the result of
+ the query.
+
+ @return The number of selections.
+
@remarks Use this with a multiple selection listbox.
-
- @sa wxControlWithItems::GetSelection, wxControlWithItems::GetStringSelection,
- wxControlWithItems::SetSelection
+
+ @see wxControlWithItems::GetSelection, wxControlWithItems::GetStringSelection,
+ wxControlWithItems::SetSelection
*/
- int GetSelections(wxArrayInt& selections);
+ int GetSelections(wxArrayInt& selections) const;
/**
Returns the item located at @e point, or @c wxNOT_FOUND if there
is no item located at @e point.
-
- This function is new since wxWidgets version 2.7.0. It is currently implemented
- for wxMSW, wxMac and wxGTK2
- ports.
-
+
+ It is currently implemented for wxMSW, wxMac and wxGTK2 ports.
+
@param point
- Point of item (in client coordinates) to obtain
-
- @returns Item located at point, or wxNOT_FOUND if unimplemented or the
- item does not exist.
+ Point of item (in client coordinates) to obtain
+
+ @return Item located at point, or wxNOT_FOUND if unimplemented or the
+ item does not exist.
+
+ @since 2.7.0
*/
- int HitTest(const wxPoint point);
+ int HitTest(const wxPoint point) const;
- //@{
/**
Insert the given number of strings before the specified position.
-
+
@param nItems
- Number of items in the array items
-
+ Number of items in the array items
@param items
- Labels of items to be inserted
-
+ Labels of items to be inserted
@param pos
- Position before which to insert the items: for example, if pos is 0 the items
- will be inserted in the beginning of the listbox
+ Position before which to insert the items: if pos is 0 the
+ items will be inserted in the beginning of the listbox
*/
- void InsertItems(int nItems, const wxString items,
+ void InsertItems(int nItems, const wxString *items,
unsigned int pos);
- void InsertItems(const wxArrayString& nItems,
+
+ /**
+ Insert the given number of strings before the specified position.
+
+ @param items
+ Labels of items to be inserted
+ @param pos
+ Position before which to insert the items: if pos is 0 the
+ items will be inserted in the beginning of the listbox
+ */
+ void InsertItems(const wxArrayString& items,
unsigned int pos);
- //@}
/**
Determines whether an item is selected.
-
+
@param n
- The zero-based item index.
-
- @returns @true if the given item is selected, @false otherwise.
+ The zero-based item index.
+
+ @return @true if the given item is selected, @false otherwise.
*/
- bool IsSelected(int n);
+ bool IsSelected(int n) const;
- //@{
/**
Clears the list box and adds the given strings to it.
-
+
@param n
- The number of strings to set.
-
+ The number of strings to set.
+ @param choices
+ An array of strings to set.
+ @param clientData
+ Options array of client data pointers
+ */
+ void Set(int n, const wxString* choices, void **clientData = NULL);
+
+ /**
+ Clears the list box and adds the given strings to it. You may
+ free the array from the calling program after this method
+ has been called.
+
@param choices
- An array of strings to set.
-
+ An array of strings to set.
@param clientData
- Options array of client data pointers
-
- @remarks You may free the array from the calling program after this
- function has been called.
+ Options array of client data pointers
*/
- void Set(int n, const wxString* choices, void clientData = @NULL);
void Set(const wxArrayString& choices,
- void clientData = @NULL);
- //@}
+ void **clientData = NULL);
- //@{
/**
Set the specified item to be the first visible item.
-
+
@param n
- The zero-based item index.
-
- @param string
- The string that should be visible.
+ The zero-based item index that should be visible.
*/
void SetFirstItem(int n);
+
+ /**
+ Set the specified item to be the first visible item.
+
+ @param string
+ The string that should be visible.
+ */
void SetFirstItem(const wxString& string);
- //@}
};
+
projects / wxWidgets.git / blobdiff