.. wxPython Phoenix documentation

   This file was generated by Phoenix's sphinx generator and associated
   tools, do not edit by hand.

   Copyright: (c) 2011-2017 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):

            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 :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 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
====================================

================================================================================ ================================================================================
: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
===============================

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


