phoenix_title wx.ListBox

A listbox is used to select one or more of a list of strings.

The strings are displayed in a scrolling box, with the selected string(s) marked in reverse video. A listbox can be single selection (if an item is selected, the previous selection is removed) or multiple selection (clicking an item toggles the item on or off independently of other selections).

List box elements are numbered from zero and while the maximal number of elements is unlimited, it is usually better to use a virtual control, not requiring to add all the items to it at once, such as wx.dataview.DataViewCtrl or wx.ListCtrl with LC_VIRTUAL style, once more than a few hundreds items need to be displayed because this control is not optimized, neither from performance nor from user interface point of view, for large number of items.

Notice that the list box doesn’t support control characters other than TAB .

^^

styles Window Styles

This class supports the following styles:

  • wx.LB_SINGLE: Single-selection list.

  • wx.LB_MULTIPLE: Multiple-selection list: the user can toggle multiple items on and off. This is the same as wx.LB_EXTENDED in wxGTK2 port.

  • wx.LB_EXTENDED: Extended-selection list: the user can extend the selection by using SHIFT or CTRL keys together with the cursor movement keys or the mouse.

  • wx.LB_HSCROLL: Create horizontal scrollbar if contents are too wide (Windows only).

  • wx.LB_ALWAYS_SB: Always show a vertical scrollbar.

  • wx.LB_NEEDED_SB: Only create a vertical scrollbar if needed.

  • wx.LB_NO_SB: Don’t create vertical scrollbar (wxMSW and wxGTK only).

  • wx.LB_SORT: The listbox contents are sorted in alphabetical order. ^^

Note that

LB_SINGLE , LB_MULTIPLE and LB_EXTENDED styles are mutually exclusive and you can specify at most one of them (single selection is the default). See also Window Styles.

^^

events Events Emitted by this Class

Handlers bound for the following event types will receive a wx.CommandEvent parameter.

  • EVT_LISTBOX: Process a wxEVT_LISTBOX event, when an item on the list is selected or the selection changes.

  • EVT_LISTBOX_DCLICK: Process a wxEVT_LISTBOX_DCLICK event, when the listbox is double-clicked. On some platforms (notably wxGTK2) pressing the enter key is handled as an equivalent of a double-click. ^^

class_hierarchy Class Hierarchy

Inheritance diagram for class ListBox:

appearance Control Appearance


wxMSW

wxMSW

wxMAC

wxMAC

wxGTK

wxGTK


sub_classes Known Subclasses

wx.CheckListBox


method_summary Methods Summary

__init__

Default constructor.

Create

Creates the listbox for two-step construction.

Deselect

Deselects an item in the list box.

EnsureVisible

Ensure that the item with the given index is currently shown.

FindString

Finds an item whose label matches the given string.

GetClassDefaultAttributes

GetCount

Returns the number of items in the control.

GetCountPerPage

Return the number of items that can fit vertically in the visible area of the listbox.

GetSelection

Returns the index of the selected item or NOT_FOUND if no item is selected.

GetSelections

Fill an array of ints with the positions of the currently selected items.

GetString

Returns the label of the item with the given index.

GetTopItem

Return the index of the topmost visible item.

HitTest

Returns the item located at point, or NOT_FOUND if there is no item located at point.

InsertItems

Insert the given number of strings before the specified position.

IsSelected

Determines whether an item is selected.

IsSorted

Return True if the listbox has LB_SORT style.

MSWSetTabStops

SetFirstItem

Set the specified item to be the first visible item.

SetItemBackgroundColour

Set the background colour of an item in the ListBox.

SetItemFont

Set the font of an item in the ListBox.

SetItemForegroundColour

Set the foreground colour of an item in the ListBox.

SetSelection

Sets the selection to the given item n or removes the selection entirely if n == NOT_FOUND .

SetString

Sets the label for the given item.

SetStringSelection


property_summary Properties Summary

Count

See GetCount

CountPerPage

See GetCountPerPage

Selection

See GetSelection and SetSelection

Selections

See GetSelections

TopItem

See GetTopItem


api Class API

class wx.ListBox(Control, ItemContainer)

Possible constructors:

ListBox()

ListBox(parent, id=ID_ANY, pos=DefaultPosition, size=DefaultSize,
        choices=[], style=0, validator=DefaultValidator, name=ListBoxNameStr)

A listbox is used to select one or more of a list of strings.


Methods

__init__(self, *args, **kw)

overload Overloaded Implementations:



__init__ (self)

Default constructor.



__init__ (self, parent, id=ID_ANY, pos=DefaultPosition, size=DefaultSize, choices=[], style=0, validator=DefaultValidator, name=ListBoxNameStr)

Constructor, creating and showing a list box.

See the other wx.ListBox constructor; the only difference is that this overload takes a list of strings instead of a pointer to an array of String .





Create(self, parent, id=ID_ANY, pos=DefaultPosition, size=DefaultSize, choices=[], style=0, validator=DefaultValidator, name=ListBoxNameStr)

Creates the listbox for two-step construction.

See wx.ListBox for further details.

Parameters:
Return type:

bool



Deselect(self, n)

Deselects an item in the list box.

Parameters:

n (int) – The zero-based item to deselect.

Note

This applies to multiple selection listboxes only.



EnsureVisible(self, n)

Ensure that the item with the given index is currently shown.

This method scrolls the listbox only if necessary and doesn’t do anything if this item is already shown, unlike SetFirstItem .

Parameters:

n (int) –



FindString(self, string, caseSensitive=False)

Finds an item whose label matches the given string.

Parameters:
  • string (string) – String to find.

  • caseSensitive (bool) – Whether search is case sensitive (default is not).

Return type:

int

Returns:

The zero-based position of the item, or wx.NOT_FOUND if the string was not found.



static GetClassDefaultAttributes(variant=WINDOW_VARIANT_NORMAL)
Parameters:

variant (WindowVariant) –

Return type:

wx.VisualAttributes



GetCount(self)

Returns the number of items in the control.

Return type:

int

See also

IsEmpty



GetCountPerPage(self)

Return the number of items that can fit vertically in the visible area of the listbox.

Returns -1 if the number of items per page couldn’t be determined. On wxGTK this method can only determine the number of items per page if there is at least one item in the listbox.

Return type:

int

New in version 4.1/wxWidgets-3.1.0.



GetSelection(self)

Returns the index of the selected item or NOT_FOUND if no item is selected.

Return type:

int

Returns:

The position of the current selection.

Note

This method can be used with single selection list boxes only, you must use wx.ListBox.GetSelections for the list boxes with wx.LB_MULTIPLE style.

See also

SetSelection , GetStringSelection



GetSelections(self)

Fill an array of ints with the positions of the currently selected items.

Return type:

list of integers



GetString(self, n)

Returns the label of the item with the given index.

The index must be valid, i.e. less than the value returned by GetCount , otherwise an assert is triggered. Notably, this function can’t be called if the control is empty.

Parameters:

n (int) – The zero-based index.

Return type:

string

Returns:

The label of the item.



GetTopItem(self)

Return the index of the topmost visible item.

Returns NOT_FOUND if the method is not implemented for the current platform.

Return type:

int

New in version 4.1/wxWidgets-3.1.0.



HitTest(self, *args, **kw)

overload Overloaded Implementations:



HitTest (self, point)

Returns the item located at point, or NOT_FOUND if there is no item located at point.

It is currently implemented for wxMSW, Mac and wxGTK2 ports.

Parameters:

point (wx.Point) – Point of item (in client coordinates) to obtain

Return type:

int

Returns:

Item located at point, or wx.NOT_FOUND if unimplemented or the item does not exist.

New in version 2.7.0.



HitTest (self, x, y)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters:
  • x (int) –

  • y (int) –

Return type:

int





InsertItems(self, items, pos)

Insert the given number of strings before the specified position.

Parameters:
  • items (list of strings) – Labels of items to be inserted

  • pos (int) – Position before which to insert the items: if pos is 0 the items will be inserted in the beginning of the listbox



IsSelected(self, n)

Determines whether an item is selected.

Parameters:

n (int) – The zero-based item index.

Return type:

bool

Returns:

True if the given item is selected, False otherwise.



IsSorted(self)

Return True if the listbox has LB_SORT style.

This method is mostly meant for internal use only.

Return type:

bool



MSWSetTabStops(self, tabStops)


SetFirstItem(self, *args, **kw)

overload Overloaded Implementations:



SetFirstItem (self, n)

Set the specified item to be the first visible item.

Parameters:

n (int) – The zero-based item index that should be visible.



SetFirstItem (self, string)

Set the specified item to be the first visible item.

Parameters:

string (string) – The string that should be visible.





SetItemBackgroundColour(self, item, c)

Set the background colour of an item in the ListBox. Only valid on MSW and if the wx.LB_OWNERDRAW flag is set.



SetItemFont(self, item, f)

Set the font of an item in the ListBox. Only valid on MSW and if the wx.LB_OWNERDRAW flag is set.



SetItemForegroundColour(self, item, c)

Set the foreground colour of an item in the ListBox. Only valid on MSW and if the wx.LB_OWNERDRAW flag is set.



SetSelection(self, n)

Sets the selection to the given item n or removes the selection entirely if n == NOT_FOUND .

Note that this does not cause any command events to be emitted nor does it deselect any other items in the controls which support multiple selections.

Parameters:

n (int) – The string position to select, starting from zero.



SetString(self, n, string)

Sets the label for the given item.

Parameters:
  • n (int) – The zero-based item index.

  • string (string) – The label to set.



SetStringSelection(self, *args, **kw)

overload Overloaded Implementations:



SetStringSelection (self, s, select)

Parameters:
  • s (string) –

  • select (bool) –

Return type:

bool



SetStringSelection (self, s)

Parameters:

s (string) –

Return type:

bool




Properties

Count

See GetCount



CountPerPage

See GetCountPerPage



Selection

See GetSelection and SetSelection



Selections

See GetSelections



TopItem

See GetTopItem