How can I learn more about list controls

Wed, 11 Jan 2012 | wxPython

Sometimes, you'll need to determine which item is selected in a list from someplace else in your program, or you'll need to change which item is currently selected programmatically in response to a user event, or to something happening internally in your program.

There are several related methods for finding the index of an item in the list, given some other piece of information about the item, as displayed in table 13.7.

Table 13.8 displays possible components of the flags return value from Hit-Test(). If applicable, more than one flag may be returned.

Table 13.7 Methods for finding items in a list
Method	Description
FindItem(start, str, partial = False)	Finds the first item whose label matches str. If the start index is -1, then the search starts at the beginning, otherwise the search starts at the start index. If partial is True then the test is a "starts with" test, rather than a whole string test. The return value is the index of the matching string.
FindItemAtPos(start, point, direction)	Finds the first item near point, a wx.Point referencing a postion relative to the upper left corner of the list control. The direction parameter tells wxPython what direction to move in from the starting point to find the item. Possible values are wx.list_find_down, wx.list_find_left, wx.LIST_FIND_RIGHT, and wx.LIST_FIND_UP.
FindItemData(start, data)	Finds the item whose data (set with SetitemData()) matches the data parameter. The start parameter behaves as in Finditem().
HitTest(point)	Returns a Python tuple of the form (index, flags). The index is the item in the list control which is at the given point, or -1 if there is no such item. The flags parameter contains further information about the point and the item. It is a bitmask with values described in table 13.8.

Table 13.8 Flags for the HitTest() method
Flag	Description
wx.LISTjHITTESTjABOVE	The point is above the client area of the list
wx.LISTjHITTESTjBELOW	The point is below the client area of the list
wx.LISTjHITTESTjNOWHERE	The point is in the client area of the list, but not part of any item. Usually this is because it is after the end of the list.
wx.LISTjHITTESTjONITEM	The point is anywhere in the bounding rectangle of the item returned in the index value.
wx.LISTjHITTESTjONITEMICON	The point is specifically in the icon portion of the item returned in the index value.
wx.LISTjHITTESTjONITEMLABEL	The point is specifically in the label portion of the item returned in the index value.
wx.LISTjHITTESTjONITEMRIGHT	The point is in the blank area to the right of the item
wx.LISTjHITTESTjONITEMSTATEICON	The point is inside the state icon of an item. This assumes that the list is in tree mode, and there is a user defined state.
wx.LISTjHITTESTjTOLEFT	The point is to the left of the client area of the list
wx.LISTjHITTESTjTORIGHT	The point is to the right of the client area of the list

To go in the other direction, there are a few methods that will give you information about the item, given the index. The methods Getltem() and GetltemText() were discussed earlier. Others are listed in Table 13.9.

Table 13.9 Item informational methods of the list control
Method	Description
GetltemPosition(item)	Returns the position of the item as a wx.Point. Only interesting in icon or small icon mode. The point returned is the upper left corner of the item placement.
GetItemRect(item, code= wx.LIST_RECT_BOUNDS)	Returns a wx.Rect with the bounding rectangle of the item at index item. The code parameter is optional. The default value is wx.list_rect_bounds, and causes wxPython to return the entire bounding rectangle for the items. Other values for the parameter are wx.list_rect_icon, which causes the return value to be only the bounding rectangle of the icon part, and wx.list_rect_label which returns the rectangle around the label.
GetNextItem(item, geometry= wx.LIST ALL, state= wx.LIST_STATE_DONTCARE )	Returns the next item in the list after the given item index, based on the geometry and state parameters. The geometry and state parameters each have several values listed in tables which follow.
SetItemPosition(item, pos)	Moves the item at index item to the wx.Point passed in the pos parameter. Only meaningful for a list in icon or small icon view.

Table 13.10 lists values of the geometry parameter for GetNextItem(). The geometry parameter is only used under MS Windows.

Table 13.10 Values for the geometry parameter of GetNextitem()
Value	Description
wx.LIST_NEXT_ABOVE	Find the next item in the given state that is above the start item in the display.
wx.LIST_NEXT_ALL	Find the next item in the given state by index order in the list.
wx.LIST_NEXT_BELOW	Find the next item in the given state that is below the start item in the display.
wx.LIST_NEXT_LEFT	Find the next item in the given state that is to the left of the start item in the display.
wx.LIST_NEXT_RIGHT	Find the next item in the given state that is to the right of the start item in the display.

Table 13.11 displays the possible values of the state parameter from the GetNext-Item() method.

Table 13.11 Values of the State parameter for GetNextitem()
Value	Description
wx.LIST_STATE_CUT	Find only items that are selected for a clipboard cut and paste.
wx.LIST_STATE_DONTCARE	Find any item, regardless of its current state.
wx.LIST_STATE_DROPHILITED	Find only items that are currently drop targets.
wx.LIST_STATE_FOCUSED	Find only items that have the focus.
wx.LIST_STATE_SELECTED	Find only items that are currently selected.

Table 13.12 displays the methods used for changing the text display of an item with a few getter and setter methods that control the font and color of the item.

Table 13.12 Display properties of the list control
Methods	Description
GetBackgroundColour() SetBackgroundColour(col)	Manages the background color for the entire list control. The col parameter is a wx.colour, or the string name of a color.
GetItemBackgroundColour(item) SetItemBackgroundColour(item, col)	Manages the background color for the item at index item. This property is only used in report mode.
GetItemTextColour(item) SetItemTextColour(item, col)	Manages the text color for the item at index item. This property is only used in report mode.
GetTextColour() SetTextColour(col)	Manages the text color for the entire list.

Table 13.13 displays other methods of list controls that don't merit their own section, but are also useful.

Table 13.13 Other useful methods of the list control
Methods	Description
GetItemSpacing()	Returns a wx.size item with the space in pixels between icons.
GetSelectedItemCount()	Returns the number of items in the list control that are currently selected.
GetTopItemO	Returns the index of the item at the top of the visible portion of the display. Only meaningful in list and report mode.

Table 13.13 Other useful methods of the list control (continued)
Methods	Description
GetViewRect()	Returns a wx.Rect corresponding to the smallest rectangle needed to span all items wthout scrolling. Only meaningful in icon and small icon mode.
ScrollList(dx, dy)	Causes the control to scroll. The dy parameter is the vertical amount in pixels. The dx parameter is the horizontal amount. For icon, small icon, or report view, the unit is pixels. If the list control is in list mode, then the unit is columns of the list display.

These tables cover much of the functionality of a list control. However, so far, all the list controls we've seen are limited by the fact that all their data must exist in the program memory at all times. In the next section, we'll discuss a mechanism for providing list data only as it is needed for display.

Was this article helpful?

Python Programming Studio

» wxPython