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, 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

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.