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.
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. |
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.
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.
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.
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.
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.
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. |
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?
Post a comment