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, parent):

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

        list = ULC.UltimateListCtrl(self, wx.ID_ANY, agwStyle=ULC.ULC_REPORT | ULC.ULC_VRULES | ULC.ULC_HRULES | ULC.ULC_SINGLE_SEL | ULC.ULC_HAS_VARIABLE_ROW_HEIGHT)

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

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

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

        choice = wx.Choice(list, -1, choices=["one", "two"])
        index = list.InsertStringItem(sys.maxsize, "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

if __name__ == “__main__”:
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 when 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).
`ULC_NO_ITEM_DRAG`	0x200000000	Disable item dragging

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

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.

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.