.. wxPython Phoenix documentation This file was generated by Phoenix's sphinx generator and associated tools, do not edit by hand. Copyright: (c) 2011-2020 by Total Control Software License: wxWindows License .. include:: headings.inc .. module:: wx.lib.agw.ultimatelistctrl .. currentmodule:: wx.lib.agw.ultimatelistctrl .. highlight:: python .. _wx.lib.agw.ultimatelistctrl: ========================================================================================================================================== |phoenix_title| **wx.lib.agw.ultimatelistctrl** ========================================================================================================================================== Description =========== UltimateListCtrl is a class that mimics the behaviour of :class:`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 :class:`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 :class:`wx.ImageList`. Simply use :class:`PyImageList` instead of :class:`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 :meth:`~UltimateListCtrl.SetItemPyData` and :meth:`~UltimateListCtrl.GetItemPyData`: the data can be any Python object and not necessarily an integer as in :class:`ListCtrl`; * CheckBox-type items and subitems; * RadioButton-type items and subitems; * Overflowing items/subitems, a la :class:`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 :class:`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 :meth:`ListCtrl.SortItems`.) ``ULC_SORT_DESCENDING`` 0x8000 Sort in descending order. (You must still supply a comparison callback in :meth:`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 ==================================== ================================================================================ ================================================================================ :func:`~wx.lib.agw.ultimatelistctrl.CheckVariableRowHeight` Checks whether a `text` contains multiline strings and if the `listCtrl` window :func:`~wx.lib.agw.ultimatelistctrl.CreateListItem` Creates a new instance of :class:`UltimateListItem`. :func:`~wx.lib.agw.ultimatelistctrl.GetdragcursorBitmap` Returns the drag and drop cursor image as a :class:`wx.Bitmap`. :func:`~wx.lib.agw.ultimatelistctrl.GetdragcursorData` Returns the drag and drop cursor image as a decompressed stream of characters. :func:`~wx.lib.agw.ultimatelistctrl.GetdragcursorImage` Returns the drag and drop cursor image as a :class:`wx.Image`. :func:`~wx.lib.agw.ultimatelistctrl.MakeDisabledBitmap` Creates a disabled-looking bitmap starting from the input one. :func:`~wx.lib.agw.ultimatelistctrl.to_list` Converts the input data into a Python list. ================================================================================ ================================================================================ | |class_summary| Classes Summary =============================== ================================================================================ ================================================================================ `~wx.lib.agw.ultimatelistctrl.ColWidthInfo` A simple class which holds information about :class:`UltimateListCtrl` columns. `~wx.lib.agw.ultimatelistctrl.CommandListEvent` A list event holds information about events associated with :class:`UltimateListCtrl` `~wx.lib.agw.ultimatelistctrl.GeometryInfo` A simple class which holds items geometries for :class:`UltimateListCtrl` not in `~wx.lib.agw.ultimatelistctrl.PyImageList` A :class:`PyImageList` contains a list of images. Images can have masks for `~wx.lib.agw.ultimatelistctrl.SelectionStore` SelectionStore is used to store the selected items in the virtual `~wx.lib.agw.ultimatelistctrl.UltimateListCtrl` UltimateListCtrl is a class that mimics the behaviour of :class:`ListCtrl`, with almost `~wx.lib.agw.ultimatelistctrl.UltimateListEvent` A list event holds information about events associated with :class:`UltimateListCtrl` `~wx.lib.agw.ultimatelistctrl.UltimateListHeaderData` A simple class which holds information about :class:`UltimateListItem` visual `~wx.lib.agw.ultimatelistctrl.UltimateListHeaderWindow` This class holds the header window for :class:`UltimateListCtrl`. `~wx.lib.agw.ultimatelistctrl.UltimateListItem` This class stores information about a :class:`UltimateListCtrl` item or column. `~wx.lib.agw.ultimatelistctrl.UltimateListItemAttr` Represents the attributes (colour, font, ...) of a :class:`UltimateListCtrl` `~wx.lib.agw.ultimatelistctrl.UltimateListItemData` A simple class which holds information about :class:`UltimateListItem` visual `~wx.lib.agw.ultimatelistctrl.UltimateListLineData` A simple class which holds line geometries for :class:`UltimateListCtrl`. `~wx.lib.agw.ultimatelistctrl.UltimateListMainWindow` This is the main widget implementation of :class:`UltimateListCtrl`. `~wx.lib.agw.ultimatelistctrl.UltimateListRenameTimer` Timer used for enabling in-place edit. `~wx.lib.agw.ultimatelistctrl.UltimateListTextCtrl` Control used for in-place edit. ================================================================================ ================================================================================ | .. toctree:: :maxdepth: 1 :hidden: wx.lib.agw.ultimatelistctrl.ColWidthInfo wx.lib.agw.ultimatelistctrl.CommandListEvent wx.lib.agw.ultimatelistctrl.GeometryInfo wx.lib.agw.ultimatelistctrl.PyImageList wx.lib.agw.ultimatelistctrl.SelectionStore wx.lib.agw.ultimatelistctrl.UltimateListCtrl wx.lib.agw.ultimatelistctrl.UltimateListEvent wx.lib.agw.ultimatelistctrl.UltimateListHeaderData wx.lib.agw.ultimatelistctrl.UltimateListHeaderWindow wx.lib.agw.ultimatelistctrl.UltimateListItem wx.lib.agw.ultimatelistctrl.UltimateListItemAttr wx.lib.agw.ultimatelistctrl.UltimateListItemData wx.lib.agw.ultimatelistctrl.UltimateListLineData wx.lib.agw.ultimatelistctrl.UltimateListMainWindow wx.lib.agw.ultimatelistctrl.UltimateListRenameTimer wx.lib.agw.ultimatelistctrl.UltimateListTextCtrl Functions ------------ .. function:: CheckVariableRowHeight(listCtrl, text) Checks whether a `text` contains multiline strings and if the `listCtrl` window style is compatible with multiline strings. :param `listCtrl`: an instance of :class:`UltimateListCtrl`; :param `text`: the text to analyze. .. function:: CreateListItem(itemOrId, col) Creates a new instance of :class:`UltimateListItem`. :param `itemOrId`: can be an instance of :class:`UltimateListItem` or an integer; :param `col`: the item column. .. function:: GetdragcursorBitmap() Returns the drag and drop cursor image as a :class:`wx.Bitmap`. .. function:: GetdragcursorData() Returns the drag and drop cursor image as a decompressed stream of characters. .. function:: GetdragcursorImage() Returns the drag and drop cursor image as a :class:`wx.Image`. .. function:: MakeDisabledBitmap(original) Creates a disabled-looking bitmap starting from the input one. :param `original`: an instance of :class:`wx.Bitmap` to be greyed-out. .. function:: to_list(input) Converts the input data into a Python list. :param `input`: can be an integer or a Python list (in which case nothing will be done to `input`.