AGW Logo

agw_title ultimatelistctrl

description Description

UltimateListCtrl is a class that mimics the behaviour of wx.ListCtrl, with almost the same base functionalities plus some more enhancements. This class does not rely on the native control, as it is a full owner-drawn list control.

In addition to the standard wx.ListCtrl behaviour this class supports:

appearance Appearance

  • Multiple images for items/subitems;
  • Images can be of any size and not limited to a single specific pair of width, height as it is the case of wx.ImageList. Simply use PyImageList instead of wx.ImageList to add your images.
  • Font, colour, background, custom renderers and formatting for items and subitems;
  • Ability to add persistent data to an item using SetItemPyData and GetItemPyData: the data can be any Python object and not necessarily an integer as in wx.ListCtrl;
  • CheckBox-type items and subitems;
  • RadioButton-type items and subitems;
  • Overflowing items/subitems, a la wx.grid.Grid, i.e. an item/subitem may overwrite neighboring items/subitems if its text would not normally fit in the space allotted to it;
  • Hyperlink-type items and subitems: they look like an hyperlink, with the proper mouse cursor on hovering;
  • Multiline text items and subitems;
  • Variable row heights depending on the item/subitem kind/text/window;
  • User defined item/subitem renderers: these renderer classes must implement the methods DrawSubItem, GetLineHeight and GetSubItemWidth (see the demo);
  • Enabling/disabling items (together with their plain or grayed out icons);
  • Whatever non-toplevel widget can be attached next to an item/subitem;
  • Column headers are fully customizable in terms of icons, colour, font, alignment etc...;
  • Column headers can have their own checkbox/radiobutton;
  • Column footers are fully customizable in terms of icons, colour, font, alignment etc...;
  • Column footers can have their own checkbox/radiobutton;
  • Ability to hide/show columns;
  • Default selection style, gradient (horizontal/vertical) selection style and Windows Vista selection style.

And a lot more. Check the demo for an almost complete review of the functionalities.

usage Usage

Usage example:

import sys

import wx
import wx.lib.agw.ultimatelistctrl as ULC

class MyFrame(wx.Frame):

    def __init__(self):

        wx.Frame.__init__(self, parent, -1, "UltimateListCtrl Demo")

        list = ULC.UltimateListCtrl(self, wx.ID_ANY, agwStyle=wx.LC_REPORT|wx.LC_VRULES|wx.LC_HRULES|wx.LC_SINGLE_SEL)

        list.InsertColumn(0, "Column 1")
        list.InsertColumn(1, "Column 2")

        index = list.InsertStringItem(sys.maxint, "Item 1")
        list.SetStringItem(index, 1, "Sub-item 1")

        index = list.InsertStringItem(sys.maxint, "Item 2")
        list.SetStringItem(index, 1, "Sub-item 2")

        choice = wx.Choice(list, -1, choices=["one", "two"])
        index = list.InsertStringItem(sys.maxint, "A widget")

        list.SetItemWindow(index, 1, choice, expand=True)

        sizer = wx.BoxSizer(wx.VERTICAL)
        sizer.Add(list, 1, wx.EXPAND)

# our normal wxApp-derived class, as usual

app = wx.PySimpleApp()

frame = MyFrame(None)


This code snippet can be downloaded, see this example script.


Some of the AGW snippets of code in the documentation use images and external files (to create bitmaps or access external data). As these files are not provided in these snippets, you should make the approriate modifications to the code to actually run it.

styles Window Styles

This class supports the following window styles:

Window styles for ultimatelistctrl
Window Styles Hex Value Description
ULC_VRULES 0x1 Draws light vertical rules between rows in report mode.
ULC_HRULES 0x2 Draws light horizontal rules between rows in report mode.
ULC_ICON 0x4 Large icon view, with optional labels.
ULC_SMALL_ICON 0x8 Small icon view, with optional labels.
ULC_LIST 0x10 Multicolumn list view, with optional small icons. Columns are computed automatically, i.e. you don’t set columns as in ULC_REPORT. In other words, the list wraps, unlike a wx.ListBox.
ULC_REPORT 0x20 Single or multicolumn report view, with optional header.
ULC_ALIGN_TOP 0x40 Icons align to the top. Win32 default, Win32 only.
ULC_ALIGN_LEFT 0x80 Icons align to the left.
ULC_AUTOARRANGE 0x100 Icons arrange themselves. Win32 only.
ULC_VIRTUAL 0x200 The application provides items text on demand. May only be used with ULC_REPORT.
ULC_EDIT_LABELS 0x400 Labels are editable: the application will be notified when editing starts.
ULC_NO_HEADER 0x800 No header in report mode.
ULC_NO_SORT_HEADER 0x1000 No Docs.
ULC_SINGLE_SEL 0x2000 Single selection (default is multiple).
ULC_SORT_ASCENDING 0x4000 Sort in ascending order. (You must still supply a comparison callback in wx.ListCtrl.SortItems.)
ULC_SORT_DESCENDING 0x8000 Sort in descending order. (You must still supply a comparison callback in wx.ListCtrl.SortItems.)
ULC_TILE 0x10000 Each item appears as a full-sized icon with a label of one or more lines beside it (partially implemented).
ULC_NO_HIGHLIGHT 0x20000 No highlight when an item is selected.
ULC_STICKY_HIGHLIGHT 0x40000 Items are selected by simply hovering on them, with no need to click on them.
ULC_STICKY_NOSELEVENT 0x80000 Don’t send a selection event when using ULC_STICKY_HIGHLIGHT style.
ULC_SEND_LEFTCLICK 0x100000 Send a left click event when an item is selected.
ULC_HAS_VARIABLE_ROW_HEIGHT 0x200000 The list has variable row heights.
ULC_AUTO_CHECK_CHILD 0x400000 When a column header has a checkbox associated, auto-check all the subitems in that column.
ULC_AUTO_TOGGLE_CHILD 0x800000 When a column header has a checkbox associated, toggle all the subitems in that column.
ULC_AUTO_CHECK_PARENT 0x1000000 Only meaningful foe checkbox-type items: when an item is checked/unchecked its column header item is checked/unchecked as well.
ULC_SHOW_TOOLTIPS 0x2000000 Show tooltips for ellipsized items/subitems (text too long to be shown in the available space) containing the full item/subitem text.
ULC_HOT_TRACKING 0x4000000 Enable hot tracking of items on mouse motion.
ULC_BORDER_SELECT 0x8000000 Changes border colour whan an item is selected, instead of highlighting the item.
ULC_TRACK_SELECT 0x10000000 Enables hot-track selection in a list control. Hot track selection means that an item is automatically selected when the cursor remains over the item for a certain period of time. The delay is retrieved on Windows using the win32api call win32gui.SystemParametersInfo(win32con.SPI_GETMOUSEHOVERTIME), and is defaulted to 400ms on other platforms. This style applies to all views of UltimateListCtrl.
ULC_HEADER_IN_ALL_VIEWS 0x20000000 Show column headers in all view modes.
ULC_NO_FULL_ROW_SELECT 0x40000000 When an item is selected, the only the item in the first column is highlighted.
ULC_FOOTER 0x80000000 Show a footer too (only when header is present).
ULC_USER_ROW_HEIGHT 0x100000000 Allows to set a custom row height (one value for all the items, only in report mode).

events Events Processing

This class processes the following events:

Events processing for ultimatelistctrl
Event Name Description
EVT_LIST_BEGIN_DRAG Begin dragging with the left mouse button.
EVT_LIST_BEGIN_RDRAG Begin dragging with the right mouse button.
EVT_LIST_BEGIN_LABEL_EDIT Begin editing a label. This can be prevented by calling Veto().
EVT_LIST_END_LABEL_EDIT Finish editing a label. This can be prevented by calling Veto().
EVT_LIST_DELETE_ITEM An item was deleted.
EVT_LIST_DELETE_ALL_ITEMS All items were deleted.
EVT_LIST_KEY_DOWN A key has been pressed.
EVT_LIST_INSERT_ITEM An item has been inserted.
EVT_LIST_COL_CLICK A column (m_col) has been left-clicked.
EVT_LIST_COL_RIGHT_CLICK A column (m_col) has been right-clicked.
EVT_LIST_COL_BEGIN_DRAG The user started resizing a column - can be vetoed.
EVT_LIST_COL_END_DRAG The user finished resizing a column.
EVT_LIST_COL_DRAGGING The divider between columns is being dragged.
EVT_LIST_ITEM_SELECTED The item has been selected.
EVT_LIST_ITEM_DESELECTED The item has been deselected.
EVT_LIST_ITEM_RIGHT_CLICK The right mouse button has been clicked on an item.
EVT_LIST_ITEM_MIDDLE_CLICK The middle mouse button has been clicked on an item.
EVT_LIST_ITEM_ACTIVATED The item has been activated (ENTER or double click).
EVT_LIST_ITEM_FOCUSED The currently focused item has changed.
EVT_LIST_CACHE_HINT Prepare cache for a virtual list control.
EVT_LIST_ITEM_CHECKING An item/subitem is being checked.
EVT_LIST_ITEM_CHECKED An item/subitem has been checked.
EVT_LIST_COL_CHECKING A column header is being checked.
EVT_LIST_COL_CHECKED A column header has being checked.
EVT_LIST_FOOTER_CHECKING A column footer is being checked.
EVT_LIST_FOOTER_CHECKED A column footer has being checked.
EVT_LIST_ITEM_HYPERLINK An hyperlink item has been clicked.
EVT_LIST_FOOTER_CLICK The user left-clicked on a column footer.
EVT_LIST_FOOTER_RIGHT_CLICK The user right-clicked on a column footer.
EVT_LIST_ITEM_LEFT_CLICK Send a left-click event after an item is selected.
EVT_LIST_END_DRAG Notify an end-drag operation.

platforms Supported Platforms

UltimateListCtrl has been tested on the following platforms:
  • Windows (Windows XP);

license License And Version

UltimateListCtrl is distributed under the wxPython license.

Latest Revision: Andrea Gavana @ 09 Feb 2012, 21.00 GMT

Version 0.8

Module author: Andrea Gavana <>

hierarchy Inheritance Diagram

Inheritance diagram for module: ultimatelistctrl

Inheritance diagram of ultimatelistctrl.ColWidthInfo, ultimatelistctrl.CommandListEvent, ultimatelistctrl.GeometryInfo, ultimatelistctrl.PyImageList, ultimatelistctrl.SelectionStore, ultimatelistctrl.UltimateListCtrl, ultimatelistctrl.UltimateListEvent, ultimatelistctrl.UltimateListHeaderData, ultimatelistctrl.UltimateListHeaderWindow, ultimatelistctrl.UltimateListItem, ultimatelistctrl.UltimateListItemAttr, ultimatelistctrl.UltimateListItemData, ultimatelistctrl.UltimateListLineData, ultimatelistctrl.UltimateListMainWindow, ultimatelistctrl.UltimateListRenameTimer, ultimatelistctrl.UltimateListTextCtrl

svn_main SVN Revisions

A graphical representation of the SVN commits in the last year.

Click on any date in the picture to jump to that particular revision page, containing information about committers, log messages and SVN diffs.


Revision Graph For ultimatelistctrl

2to3 Python 3 Issues (via 2to3)

No issues have been detected by