1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
|
.. wxPython Phoenix documentation
This file was generated by Phoenix's sphinx generator and associated
tools, do not edit by hand.
Copyright: (c) 2011-2018 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 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`.
|
