Phoenix Logo

phoenix_title wx.lib.agw.ultimatelistctrl

Description

UltimateListCtrl is a class that mimics the behaviour of 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 ListCtrl behaviour this class supports:

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 ListCtrl;
  • CheckBox-type items and subitems;
  • RadioButton-type items and subitems;
  • Overflowing items/subitems, a la 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 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)
        self.SetSizer(sizer)


# our normal wxApp-derived class, as usual

app = wx.App(0)

frame = MyFrame(None)
app.SetTopWindow(frame)
frame.Show()

app.MainLoop()

Window Styles

This class supports the following window styles:

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 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 ListCtrl.SortItems.)
ULC_SORT_DESCENDING 0x8000 Sort in descending order. (You must still supply a comparison callback in 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 Processing

This class processes the following events:

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.

Supported Platforms

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

License And Version

UltimateListCtrl is distributed under the wxPython license.

Latest Revision: Andrea Gavana @ 27 Dec 2012, 21.00 GMT

Version 0.8

function_summary Functions Summary

CheckVariableRowHeight Checks whether a text contains multiline strings and if the listCtrl window
CreateListItem Creates a new instance of UltimateListItem.
GetdragcursorBitmap Returns the drag and drop cursor image as a wx.Bitmap.
GetdragcursorData Returns the drag and drop cursor image as a decompressed stream of characters.
GetdragcursorImage Returns the drag and drop cursor image as a wx.Image.
MakeDisabledBitmap Creates a disabled-looking bitmap starting from the input one.
to_list Converts the input data into a Python list.

class_summary Classes Summary

ColWidthInfo A simple class which holds information about UltimateListCtrl columns.
CommandListEvent A list event holds information about events associated with UltimateListCtrl
GeometryInfo A simple class which holds items geometries for UltimateListCtrl not in
PyImageList A PyImageList contains a list of images. Images can have masks for
SelectionStore SelectionStore is used to store the selected items in the virtual
UltimateListCtrl UltimateListCtrl is a class that mimics the behaviour of ListCtrl, with almost
UltimateListEvent A list event holds information about events associated with UltimateListCtrl
UltimateListHeaderData A simple class which holds information about UltimateListItem visual
UltimateListHeaderWindow This class holds the header window for UltimateListCtrl.
UltimateListItem This class stores information about a UltimateListCtrl item or column.
UltimateListItemAttr Represents the attributes (colour, font, ...) of a UltimateListCtrl
UltimateListItemData A simple class which holds information about UltimateListItem visual
UltimateListLineData A simple class which holds line geometries for UltimateListCtrl.
UltimateListMainWindow This is the main widget implementation of UltimateListCtrl.
UltimateListRenameTimer Timer used for enabling in-place edit.
UltimateListTextCtrl Control used for in-place edit.

Functions



CheckVariableRowHeight(listCtrl, text)

Checks whether a text contains multiline strings and if the listCtrl window style is compatible with multiline strings.

Parameters:


CreateListItem(itemOrId, col)

Creates a new instance of UltimateListItem.

Parameters:
  • itemOrId – can be an instance of UltimateListItem or an integer;
  • col – the item column.


GetdragcursorBitmap()

Returns the drag and drop cursor image as a wx.Bitmap.



GetdragcursorData()

Returns the drag and drop cursor image as a decompressed stream of characters.



GetdragcursorImage()

Returns the drag and drop cursor image as a wx.Image.



MakeDisabledBitmap(original)

Creates a disabled-looking bitmap starting from the input one.

Parameters:original – an instance of wx.Bitmap to be greyed-out.


to_list(input)

Converts the input data into a Python list.

Parameters:input – can be an integer or a Python list (in which case nothing will be done to input.