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 ImageList. Simply use PyImageList instead of 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 meth:~UltimateListCtrl.SetItemPyData` and meth:~UltimateListCtrl.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 @ 09 Apr 2012, 11.00 GMT

Version 0.8

Inheritance Diagram

Inheritance diagram for module ultimatelistctrl

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 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 Image.
MakeDisabledBitmap	Creates a disabled-looking bitmap starting from the input one.
to_list	Converts the input data into a Python list.

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:

• listCtrl – an instance of UltimateListCtrl;
• text – the text to analyze.

---

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 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 Image.

---

MakeDisabledBitmap(original)

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

Parameters:original – an instance of 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.