How can I learn more about list controls

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?

0 0

Post a comment