phoenix_title wx.lib.agw.ultimatelistctrl.UltimateListMainWindow

This is the main widget implementation of UltimateListCtrl.


class_hierarchy Class Hierarchy

Inheritance diagram for class UltimateListMainWindow:

super_classes Known Superclasses

wx.ScrolledWindow


method_summary Methods Summary

__init__

Default class constructor.

AutoCheckChild

Checks/unchecks all the items.

AutoToggleChild

Toggles all the items.

CacheLineData

Saves the current line attributes.

ChangeCurrent

Changes the current line to the specified one.

CheckItem

Actually checks/uncheks an item, sending (eventually) the two

DeleteAllItems

Deletes all items in the UltimateListCtrl.

DeleteColumn

Deletes the specified column.

DeleteEverything

Deletes all items in the UltimateListCtrl, resetting column widths to zero.

DeleteItem

Deletes the specified item.

DeleteItemWindow

Deletes the window associated to an item (if any).

DoDeleteAllItems

Actually performs the deletion of all the items.

DoGetBestSize

Gets the size which best suits the window: for a control, it would be the

DragFinish

A drag and drop operation has just finished.

DrawCheckbox

Draws the item checkbox/radiobutton image.

DrawDnDArrow

Draws a drag and drop visual representation of an arrow.

DrawImage

Draws one of the item images.

EditLabel

Starts editing an item label.

EnableItem

Enables/disables an item.

EnableSelectionGradient

Globally enables/disables drawing of gradient selections.

EnableSelectionVista

Globally enables/disables drawing of Windows Vista selections.

EnsureVisible

Ensures this item is visible.

FindItem

Find an item whose label matches this string.

FindItemAtPos

Find an item nearest this position.

FindItemData

Find an item whose data matches this data.

GetBackgroundImage

Returns the UltimateListCtrl background image (if any).

GetCheckboxImageSize

Returns the checkbox/radiobutton image size.

GetCheckedItemCount

Returns the number of checked items in the given column.

GetColumn

Returns information about this column.

GetColumnCount

Returns the total number of columns in the UltimateListCtrl.

GetColumnCustomRenderer

Returns the custom renderer used to draw the column header

GetColumnWidth

Returns the column width for the input column.

GetControlBmp

Returns a native looking checkbox or radio button bitmap.

GetCountPerPage

Returns the number of items that can fit vertically in the visible area

GetDisabledTextColour

Returns the items disabled colour.

GetDummyLine

Returns a dummy line.

GetFirstGradientColour

Returns the first gradient colour for gradient-style selections.

GetGradientStyle

Returns the gradient style for gradient-style selections.

GetHeaderWidth

Returns the header window width, in pixels.

GetHighlightBrush

Returns the brush to use for the item highlighting.

GetHyperTextFont

Returns the font used to render an hypertext item.

GetHyperTextNewColour

Returns the colour used to render a non-visited hypertext item.

GetHyperTextVisitedColour

Returns the colour used to render a visited hypertext item.

GetImageSize

Returns the image size for the item.

GetItem

Returns the information about the input item.

GetItemCount

Returns the number of items in the UltimateListCtrl.

GetItemCustomRenderer

Returns the custom renderer used to draw the input item (if any).

GetItemKind

Returns the item kind.

GetItemOverFlow

Returns if the item is in the overflow state.

GetItemPosition

Returns the position of the item, in icon or small icon view.

GetItemRect

Returns the rectangle representing the item’s size and position, in physical

GetItemSpacing

Returns the spacing between item texts and icons, in pixels.

GetItemState

Returns the item state flags for the input item.

GetItemText

Returns the item text.

GetItemTextSize

Returns the item width, in pixels, considering only the item text.

GetItemVisited

Returns whether an hypertext item was visited.

GetItemWidthWithImage

Returns the item width, in pixels, considering the item text and its images.

GetItemWindow

Returns the window associated to the item (if any).

GetItemWindowEnabled

Returns whether the window associated to the item is enabled.

GetLine

Returns the line data for the given index.

GetLineCheckboxRect

Returns the line client rectangle for the item checkbox image only.

GetLineHeight

Returns the line height for a specific item.

GetLineHighlightRect

Returns the line client rectangle when the line is highlighted.

GetLineIconRect

Returns the line client rectangle for the item image only.

GetLineLabelRect

Returns the line client rectangle for the item text only.

GetLineRect

Returns the line client rectangle.

GetLineSize

Returns the size of the total line client rectangle.

GetLineY

Returns the line y position.

GetListCtrl

Returns the parent widget, an instance of UltimateListCtrl.

GetMainWindowOfCompositeControl

Returns the UltimateListMainWindow parent.

GetNextActiveItem

Returns the next active item. Used Internally at present.

GetNextItem

Searches for an item with the given geometry or state, starting from item

GetRuleColour

Returns the colour to be used for drawing the horizontal and vertical rules.

GetSecondGradientColour

Returns the second gradient colour for gradient-style selections.

GetSelectedItemCount

Returns the number of selected items in UltimateListCtrl.

GetSubItemRect

Returns the rectangle representing the size and position, in physical coordinates,

GetTextLength

Returns the text width for the input string.

GetTotalWidth

Returns the total width of the columns in UltimateListCtrl.

GetUserLineHeight

Returns the custom value for the UltimateListMainWindow item height, if previously set with

GetViewRect

Returns the rectangle taken by all items in the control. In other words,

GetVisibleLinesRange

Returns the range of visible items on screen.

GetWaterMark

Returns the UltimateListCtrl watermark image (if any), displayed in the

HandleHyperLink

Handles the hyperlink items, sending the EVT_LIST_ITEM_HYPERLINK event.

HasAGWFlag

Returns True if the window has the given flag bit set.

HasCurrent

Returns True if the current item has been set, either programmatically

HasFocus

Returns True if the window has focus.

HasFooter

Returns True if the footer window is shown.

HasHeader

Returns True if the header window is shown.

HideWindows

Hides the windows associated to the items. Used internally.

HighlightAll

Highlights/unhighlights all the lines in UltimateListCtrl.

HighlightLine

Highlights a line in UltimateListCtrl.

HighlightLines

Highlights a range of lines in UltimateListCtrl.

HitTest

HitTest method for a UltimateListCtrl.

HitTestLine

HitTest method for a UltimateListCtrl line.

Init

Initializes the UltimateListMainWindow widget.

InReportView

Returns True if the window is in report mode.

InsertColumn

Inserts a column into UltimateListCtrl.

InsertItem

Inserts an item into UltimateListCtrl.

InTileView

Returns True if the window is in tile mode (partially implemented).

IsColumnShown

Returns True if the input column is shown, False if it is hidden.

IsEmpty

Returns True if the window has no items in it.

IsHighlighted

Returns True if the input line is highlighted.

IsItemChecked

Returns whether an item is checked or not.

IsItemEnabled

Returns whether an item is enabled or not.

IsItemHyperText

Returns whether an item is hypertext or not.

IsSingleSel

Returns True if we are in single selection mode, False if multi selection.

IsVirtual

Returns True if the window has the ULC_VIRTUAL style set.

MoveToFocus

Brings the current item into view.

MoveToItem

Scrolls the input item into view.

OnArrowChar

Handles the keyboard arrows key events.

OnChar

Handles the wx.EVT_CHAR event for UltimateListMainWindow.

OnChildFocus

Handles the wx.EVT_CHILD_FOCUS event for UltimateListMainWindow.

OnCompareItems

Returns whether 2 lines have the same index.

OnEraseBackground

Handles the wx.EVT_ERASE_BACKGROUND event for UltimateListMainWindow.

OnHoverTimer

Handles the wx.EVT_TIMER event for UltimateListMainWindow.

OnKeyDown

Handles the wx.EVT_KEY_DOWN event for UltimateListMainWindow.

OnKeyUp

Handles the wx.EVT_KEY_UP event for UltimateListMainWindow.

OnKillFocus

Handles the wx.EVT_KILL_FOCUS event for UltimateListMainWindow.

OnMouse

Handles the wx.EVT_MOUSE_EVENTS event for UltimateListMainWindow.

OnPaint

Handles the wx.EVT_PAINT event for UltimateListMainWindow.

OnRenameAccept

Called by UltimateListTextCtrl, to accept the changes and to send the

OnRenameCancelled

Called by UltimateListTextCtrl, to cancel the changes and to send the

OnRenameTimer

The timer for renaming has expired. Start editing.

OnScroll

Handles the wx.EVT_SCROLLWIN event for UltimateListMainWindow.

OnSetFocus

Handles the wx.EVT_SET_FOCUS event for UltimateListMainWindow.

PaintWaterMark

Draws a watermark at the bottom right of UltimateListCtrl.

RecalculatePositions

Recalculates all the items positions, and sets the scrollbars positions

RefreshAfter

Redraws all the lines after the input one.

RefreshAll

Refreshes the entire UltimateListCtrl.

RefreshLine

Redraws the input line.

RefreshLines

Redraws a range of lines in UltimateListCtrl.

RefreshSelected

Redraws the selected lines.

ResetCurrent

Resets the current item to None.

ResetLineDimensions

Resets the line dimensions, so that client rectangles and positions are

ResetTextControl

Called by UltimateListTextCtrl when it marks itself for deletion.

ResetVisibleLinesRange

Forces us to recalculate the range of visible lines.

ResizeColumns

If ULC_AUTOSIZE_FILL was passed to UltimateListCtrl.SetColumnWidth() then

ReverseHighlight

Toggles the line state and refreshes it.

ScrollList

Scrolls the UltimateListCtrl.

SendNotify

Actually sends a UltimateListEvent.

SetBackgroundImage

Sets the UltimateListCtrl background image.

SetColumn

Sets information about this column.

SetColumnCustomRenderer

Associate a custom renderer to this column’s header

SetColumnWidth

Sets the column width.

SetDisabledTextColour

Sets the items disabled colour.

SetFirstGradientColour

Sets the first gradient colour for gradient-style selections.

SetFont

Overridden base class virtual to reset the line height when the font changes.

SetGradientStyle

Sets the gradient style for gradient-style selections.

SetHyperTextFont

Sets the font used to render hypertext items.

SetHyperTextNewColour

Sets the colour used to render a non-visited hypertext item.

SetHyperTextVisitedColour

Sets the colour used to render a visited hypertext item.

SetImageList

Sets the image list associated with the control.

SetImageListCheck

Sets the checkbox/radiobutton image list.

SetItem

Sets information about the item.

SetItemCount

This method can only be used with virtual UltimateListCtrl. It is used to

SetItemCustomRenderer

Associate a custom renderer to this item.

SetItemHyperText

Sets whether the item is hypertext or not.

SetItemKind

Sets the item kind.

SetItemOverFlow

Sets the item in the overflow/non overflow state.

SetItemSpacing

Sets the spacing between item texts and icons.

SetItemState

Sets the item state flags for the input item.

SetItemStateAll

Sets the item state flags for all the items.

SetItemText

Sets the item text.

SetItemVisited

Sets whether an hypertext item was visited.

SetItemWindow

Sets the window for the given item.

SetItemWindowEnabled

Enables/disables the window associated to the item.

SetReportView

Sets whether UltimateListCtrl is in report view or not.

SetSecondGradientColour

Sets the second gradient colour for gradient-style selections.

SetUserLineHeight

Sets a custom value for the UltimateListMainWindow item height.

SetWaterMark

Sets the UltimateListCtrl watermark image to be displayed in the bottom

SortItems

Call this function to sort the items in the UltimateListCtrl. Sorting is done

TileBackground

Tiles the background image to fill all the available area.

UpdateCurrent

Updates the current line selection.


api Class API

class UltimateListMainWindow(wx.ScrolledWindow)

This is the main widget implementation of UltimateListCtrl.


Methods

__init__(self, parent, id, pos=wx.DefaultPosition, size=wx.DefaultSize, style=0, agwStyle=0, name="listctrlmainwindow")

Default class constructor.

Parameters
  • parent – parent window. Must not be None;

  • id – window identifier. A value of -1 indicates a default value;

  • pos – the control position. A value of (-1, -1) indicates a default position, chosen by either the windowing system or wxPython, depending on platform;

  • size – the control size. A value of (-1, -1) indicates a default size, chosen by either the windowing system or wxPython, depending on platform;

  • style – the underlying ScrolledWindow window style;

  • agwStyle

    the AGW-specific window style; can be almost any combination of the following bits:

    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

  • name – the window name.



AutoCheckChild(self, isChecked, column)

Checks/unchecks all the items.

Parameters
  • isCheckedTrue to check the items, False to uncheck them;

  • column – the column to which the items belongs to.

Note

This method is meaningful only for checkbox-like and radiobutton-like items.



AutoToggleChild(self, column)

Toggles all the items.

Parameters

column – the column to which the items belongs to.

Note

This method is meaningful only for checkbox-like and radiobutton-like items.



CacheLineData(self, line)

Saves the current line attributes.

Parameters

line – an instance of UltimateListLineData.

Note

This method is used only if the UltimateListCtrl has the ULC_VIRTUAL style set.



ChangeCurrent(self, current)

Changes the current line to the specified one.

Parameters

current – an integer specifying the index of the current line.



CheckItem(self, item, checked=True, sendEvent=True)

Actually checks/uncheks an item, sending (eventually) the two events EVT_LIST_ITEM_CHECKING / EVT_LIST_ITEM_CHECKED.

Parameters
  • item – an instance of UltimateListItem;

  • checkedTrue to check an item, False to uncheck it;

  • sendEventTrue to send a {UltimateListEvent}, False otherwise.

Note

This method is meaningful only for checkbox-like and radiobutton-like items.



DeleteAllItems(self)

Deletes all items in the UltimateListCtrl.

Note

This function does not send the EVT_LIST_DELETE_ITEM event because deleting many items from the control would be too slow then (unlike DeleteItem).



DeleteColumn(self, col)

Deletes the specified column.

Parameters

col – the index of the column to delete.



DeleteEverything(self)

Deletes all items in the UltimateListCtrl, resetting column widths to zero.



DeleteItem(self, lindex)

Deletes the specified item.

Parameters

lindex – the index of the item to delete.

Note

This function sends the EVT_LIST_DELETE_ITEM event for the item being deleted.



DeleteItemWindow(self, item)

Deletes the window associated to an item (if any).

Parameters

item – an instance of UltimateListItem.



DoDeleteAllItems(self)

Actually performs the deletion of all the items.



DoGetBestSize(self)

Gets the size which best suits the window: for a control, it would be the minimal size which doesn’t truncate the control, for a panel - the same size as it would have after a call to Fit().



DragFinish(self, event)

A drag and drop operation has just finished.

Parameters

event – a MouseEvent event to be processed.



DrawCheckbox(self, dc, x, y, kind, checked, enabled)

Draws the item checkbox/radiobutton image.

Parameters
  • dc – an instance of wx.DC;

  • x – the x position where to draw the image;

  • y – the y position where to draw the image;

  • kind – may be one of the following integers:

    Item Kind

    Description

    0

    A normal item

    1

    A checkbox-like item

    2

    A radiobutton-type item

  • checkedTrue if the item is checked, False otherwise;

  • enabledTrue if the item is enabled, False if it is disabled.



DrawDnDArrow(self)

Draws a drag and drop visual representation of an arrow.



DrawImage(self, index, dc, x, y, enabled)

Draws one of the item images.

Parameters
  • index – the index of the image inside the image list;

  • dc – an instance of wx.DC;

  • x – the x position where to draw the image;

  • y – the y position where to draw the image;

  • enabledTrue if the item is enabled, False if it is disabled.



EditLabel(self, item)

Starts editing an item label.

Parameters

item – an instance of UltimateListItem.



EnableItem(self, item, enable=True)

Enables/disables an item.

Parameters
  • item – an instance of UltimateListItem;

  • enableTrue to enable the item, False otherwise.



EnableSelectionGradient(self, enable=True)

Globally enables/disables drawing of gradient selections.

Parameters

enableTrue to enable gradient-style selections, False to disable it.

Note

Calling this method disables any Vista-style selection previously enabled.



EnableSelectionVista(self, enable=True)

Globally enables/disables drawing of Windows Vista selections.

Parameters

enableTrue to enable Vista-style selections, False to disable it.

Note

Calling this method disables any gradient-style selection previously enabled.



EnsureVisible(self, index)

Ensures this item is visible.

Parameters

index – the index of the item to scroll into view.



FindItem(self, start, string, partial=False)

Find an item whose label matches this string.

Parameters
  • start – the starting point of the input string or the beginning if start is -1;

  • string – the string to look for matches;

  • partial – if True then this method will look for items which begin with string.

Note

The string comparison is case insensitive.



FindItemAtPos(self, pt)

Find an item nearest this position.

Parameters

pt – an instance of wx.Point.



FindItemData(self, start, data)

Find an item whose data matches this data.

Parameters
  • start – the starting point of the input data or the beginning if start is -1;

  • data – the data to look for matches.



GetBackgroundImage(self)

Returns the UltimateListCtrl background image (if any).

Note

At present, the background image can only be used in “tile” mode.

Todo

Support background images also in stretch and centered modes.



GetCheckboxImageSize(self)

Returns the checkbox/radiobutton image size.



GetCheckedItemCount(self, col=0)

Returns the number of checked items in the given column.

Parameters

col – an integer specifying the column index.

Returns

the number of checked items.

Return type

int



GetColumn(self, col)

Returns information about this column.

Parameters

col – an integer specifying the column index.



GetColumnCount(self)

Returns the total number of columns in the UltimateListCtrl.



GetColumnCustomRenderer(self, col)

Returns the custom renderer used to draw the column header

Parameters

col – the column index.



GetColumnWidth(self, col)

Returns the column width for the input column.

Parameters

col – an integer specifying the column index.



GetControlBmp(self, checkbox=True, checked=False, enabled=True, x=16, y=16)

Returns a native looking checkbox or radio button bitmap.

Parameters
  • checkboxTrue to get a checkbox image, False for a radiobutton one;

  • checkedTrue if the control is marked, False if it is not;

  • enabledTrue if the control is enabled, False if it is not;

  • x – the width of the bitmap, in pixels;

  • y – the height of the bitmap, in pixels.



GetCountPerPage(self)

Returns the number of items that can fit vertically in the visible area of the UltimateListCtrl (list or report view) or the total number of items in the list control (icon or small icon view).



GetDisabledTextColour(self)

Returns the items disabled colour.



GetDummyLine(self)

Returns a dummy line.

Note

This method is used only if the UltimateListCtrl has the ULC_VIRTUAL style set.



GetFirstGradientColour(self)

Returns the first gradient colour for gradient-style selections.



GetGradientStyle(self)

Returns the gradient style for gradient-style selections.

Returns

0 for horizontal gradient-style selections, 1 for vertical gradient-style selections.



GetHeaderWidth(self)

Returns the header window width, in pixels.



GetHighlightBrush(self)

Returns the brush to use for the item highlighting.



GetHyperTextFont(self)

Returns the font used to render an hypertext item.



GetHyperTextNewColour(self)

Returns the colour used to render a non-visited hypertext item.



GetHyperTextVisitedColour(self)

Returns the colour used to render a visited hypertext item.



GetImageSize(self, index)

Returns the image size for the item.

Parameters

index – the image index.



GetItem(self, item, col=0)

Returns the information about the input item.

Parameters
  • item – an instance of UltimateListItem;

  • col – the column to which the item belongs to.



GetItemCount(self)

Returns the number of items in the UltimateListCtrl.



GetItemCustomRenderer(self, item)

Returns the custom renderer used to draw the input item (if any).

Parameters

item – an instance of UltimateListItem.



GetItemKind(self, item)

Returns the item kind.

Parameters

item – an instance of UltimateListItem.

See also

SetItemKind for a list of valid item kinds.



GetItemOverFlow(self, item)

Returns if the item is in the overflow state.

An item/subitem may overwrite neighboring items/subitems if its text would not normally fit in the space allotted to it.

Parameters

item – an instance of UltimateListItem.



GetItemPosition(self, item)

Returns the position of the item, in icon or small icon view.

Parameters

item – the row in which the item lives.



GetItemRect(self, item)

Returns the rectangle representing the item’s size and position, in physical coordinates.

Parameters

item – the row in which the item lives.



GetItemSpacing(self, isSmall=False)

Returns the spacing between item texts and icons, in pixels.

Parameters

isSmallTrue if using a wx.IMAGE_LIST_SMALL image list, False if using a wx.IMAGE_LIST_NORMAL image list.



GetItemState(self, item, stateMask)

Returns the item state flags for the input item.

Parameters
  • item – the index of the item;

  • stateMask – the bitmask for the state flag.

See also

SetItemStateAll for a list of valid state flags.



GetItemText(self, item)

Returns the item text.

Parameters

item – an instance of UltimateListItem.



GetItemTextSize(self, item)

Returns the item width, in pixels, considering only the item text.

Parameters

item – an instance of UltimateListItem.



GetItemVisited(self, item)

Returns whether an hypertext item was visited.

Parameters

item – an instance of UltimateListItem.



GetItemWidthWithImage(self, item)

Returns the item width, in pixels, considering the item text and its images.

Parameters

item – an instance of UltimateListItem.



GetItemWindow(self, item)

Returns the window associated to the item (if any).

Parameters

item – an instance of UltimateListItem.



GetItemWindowEnabled(self, item)

Returns whether the window associated to the item is enabled.

Parameters

item – an instance of UltimateListItem.



GetLine(self, n)

Returns the line data for the given index.

Parameters

n – the line index.



GetLineCheckboxRect(self, line)

Returns the line client rectangle for the item checkbox image only.

Parameters

line – an instance of UltimateListLineData.



GetLineHeight(self, item=None)

Returns the line height for a specific item.

Parameters

item – if not None, an instance of UltimateListItem.



GetLineHighlightRect(self, line)

Returns the line client rectangle when the line is highlighted.

Parameters

line – an instance of UltimateListLineData.



GetLineIconRect(self, line)

Returns the line client rectangle for the item image only.

Parameters

line – an instance of UltimateListLineData.



GetLineLabelRect(self, line, col=0)

Returns the line client rectangle for the item text only. Note this is the full column width unless an image or checkbox exists. It is not the width of the text itself

Parameters

line – an instance of UltimateListLineData.



GetLineRect(self, line)

Returns the line client rectangle.

Parameters

line – an instance of UltimateListLineData.



GetLineSize(self, line)

Returns the size of the total line client rectangle.

Parameters

line – an instance of UltimateListLineData.



GetLineY(self, line)

Returns the line y position.

Parameters

line – an instance of UltimateListLineData.



GetListCtrl(self)

Returns the parent widget, an instance of UltimateListCtrl.



GetMainWindowOfCompositeControl(self)

Returns the UltimateListMainWindow parent.



GetNextActiveItem(self, item, down=True)

Returns the next active item. Used Internally at present.

Parameters
  • item – an instance of UltimateListItem;

  • downTrue to search downwards for an active item, False to search upwards.



GetNextItem(self, item, geometry=ULC_NEXT_ALL, state=ULC_STATE_DONTCARE)

Searches for an item with the given geometry or state, starting from item but excluding the item itself.

Parameters
  • item – the item at which starting the search. If set to -1, the first item that matches the specified flags will be returned.

  • geometry – can be one of:

    Geometry Flag

    Hex Value

    Description

    ULC_NEXT_ABOVE

    0x0

    Searches for an item above the specified item

    ULC_NEXT_ALL

    0x1

    Searches for subsequent item by index

    ULC_NEXT_BELOW

    0x2

    Searches for an item below the specified item

    ULC_NEXT_LEFT

    0x3

    Searches for an item to the left of the specified item

    ULC_NEXT_RIGHT

    0x4

    Searches for an item to the right of the specified item

  • state – any combination of the following bits:

    State Bits

    Hex Value

    Description

    ULC_STATE_DONTCARE

    0x0

    Don’t care what the state is

    ULC_STATE_DROPHILITED

    0x1

    The item is highlighted to receive a drop event

    ULC_STATE_FOCUSED

    0x2

    The item has the focus

    ULC_STATE_SELECTED

    0x4

    The item is selected

    ULC_STATE_CUT

    0x8

    The item is in the cut state

    ULC_STATE_DISABLED

    0x10

    The item is disabled

    ULC_STATE_FILTERED

    0x20

    The item has been filtered

    ULC_STATE_INUSE

    0x40

    The item is in use

    ULC_STATE_PICKED

    0x80

    The item has been picked

    ULC_STATE_SOURCE

    0x100

    The item is a drag and drop source

Returns

The first item with given state following item or -1 if no such item found.

Note

This function may be used to find all selected items in the control like this:

item = -1

while 1:
    item = listctrl.GetNextItem(item, ULC_NEXT_ALL, ULC_STATE_SELECTED)

    if item == -1:
        break

    # This item is selected - do whatever is needed with it

    wx.LogMessage("Item %ld is selected."%item)


GetRuleColour(self)

Returns the colour to be used for drawing the horizontal and vertical rules.



GetSecondGradientColour(self)

Returns the second gradient colour for gradient-style selections.



GetSelectedItemCount(self)

Returns the number of selected items in UltimateListCtrl.



GetSubItemRect(self, item, subItem)

Returns the rectangle representing the size and position, in physical coordinates, of the given subitem, i.e. the part of the row item in the column subItem.

Parameters
  • item – the row in which the item lives;

  • subItem – the column in which the item lives. If set equal to the special value ULC_GETSUBITEMRECT_WHOLEITEM the return value is the same as for GetItemRect.

Note

This method is only meaningful when the UltimateListCtrl is in the report mode.



GetTextLength(self, s)

Returns the text width for the input string.

Parameters

s – the string to measure.



GetTotalWidth(self)

Returns the total width of the columns in UltimateListCtrl.



GetUserLineHeight(self)

Returns the custom value for the UltimateListMainWindow item height, if previously set with SetUserLineHeight.

Note

This method can be used only with ULC_REPORT and ULC_USER_ROW_HEIGHT styles set.



GetViewRect(self)

Returns the rectangle taken by all items in the control. In other words, if the controls client size were equal to the size of this rectangle, no scrollbars would be needed and no free space would be left.

Note

This function only works in the icon and small icon views, not in list or report views.



GetVisibleLinesRange(self)

Returns the range of visible items on screen.

Note

This method can be used only if UltimateListCtrl has the ULC_REPORT style set.



GetWaterMark(self)

Returns the UltimateListCtrl watermark image (if any), displayed in the bottom right part of the window.

Todo

Better support for this is needed.



Handles the hyperlink items, sending the EVT_LIST_ITEM_HYPERLINK event.

Parameters

item – an instance of UltimateListItem.



HasAGWFlag(self, flag)

Returns True if the window has the given flag bit set.

Parameters

flag – the bit to check.

See also

UltimateListCtrl.SetSingleStyle() for a list of valid flags.



HasCurrent(self)

Returns True if the current item has been set, either programmatically or by user intervention.



HasFocus(self)

Returns True if the window has focus.



HasFooter(self)

Returns True if the footer window is shown.



HasHeader(self)

Returns True if the header window is shown.



HideWindows(self)

Hides the windows associated to the items. Used internally.



HighlightAll(self, on=True)

Highlights/unhighlights all the lines in UltimateListCtrl.

Parameters

onTrue to highlight all the lines, False to unhighlight them.



HighlightLine(self, line, highlight=True)

Highlights a line in UltimateListCtrl.

Parameters
  • line – an instance of UltimateListLineData;

  • highlightTrue to highlight the line, False otherwise.



HighlightLines(self, lineFrom, lineTo, highlight=True)

Highlights a range of lines in UltimateListCtrl.

Parameters
  • lineFrom – an integer representing the first line to highlight;

  • lineTo – an integer representing the last line to highlight;

  • highlightTrue to highlight the lines, False otherwise.



HitTest(self, x, y)

HitTest method for a UltimateListCtrl.

Parameters
  • x – the mouse x position;

  • y – the mouse y position.

See also

HitTestLine for a list of return flags.



HitTestLine(self, line, x, y)

HitTest method for a UltimateListCtrl line.

Parameters
  • line – an instance of UltimateListLineData;

  • x – the mouse x position;

  • y – the mouse y position.

Returns

a tuple of values, representing the item hit and a hit flag. The hit flag can be one of the following bits:

HitTest Flag

Hex Value

Description

ULC_HITTEST_ABOVE

0x1

Above the client area

ULC_HITTEST_BELOW

0x2

Below the client area

ULC_HITTEST_NOWHERE

0x4

In the client area but below the last item

ULC_HITTEST_ONITEM

0x2a0

Anywhere on the item (text, icon, checkbox image)

ULC_HITTEST_ONITEMICON

0x20

On the bitmap associated with an item

ULC_HITTEST_ONITEMLABEL

0x80

On the label (string) associated with an item

ULC_HITTEST_ONITEMSTATEICON

0x200

On the state icon for a list view item that is in a user-defined state

ULC_HITTEST_TOLEFT

0x400

To the left of the client area

ULC_HITTEST_TORIGHT

0x800

To the right of the client area

ULC_HITTEST_ONITEMCHECK

0x1000

On the item checkbox (if any)



Init(self)

Initializes the UltimateListMainWindow widget.



InReportView(self)

Returns True if the window is in report mode.



InsertColumn(self, col, item)

Inserts a column into UltimateListCtrl.

Parameters
  • col – the column index at which we wish to insert a new column;

  • item – an instance of UltimateListItem.

Returns

the index at which the column has been inserted.

Note

This method is meaningful only if UltimateListCtrl has the ULC_REPORT or the ULC_TILE styles set.



InsertItem(self, item)

Inserts an item into UltimateListCtrl.

Parameters

item – an instance of UltimateListItem.



InTileView(self)

Returns True if the window is in tile mode (partially implemented).

Todo

Fully implement tile view for UltimateListCtrl.



IsColumnShown(self, column)

Returns True if the input column is shown, False if it is hidden.

Parameters

column – an integer specifying the column index.



IsEmpty(self)

Returns True if the window has no items in it.



IsHighlighted(self, line)

Returns True if the input line is highlighted.

Parameters

line – an instance of UltimateListLineData.



IsItemChecked(self, item)

Returns whether an item is checked or not.

Parameters

item – an instance of UltimateListItem.



IsItemEnabled(self, item)

Returns whether an item is enabled or not.

Parameters

item – an instance of UltimateListItem.



IsItemHyperText(self, item)

Returns whether an item is hypertext or not.

Parameters

item – an instance of UltimateListItem.



IsSingleSel(self)

Returns True if we are in single selection mode, False if multi selection.



IsVirtual(self)

Returns True if the window has the ULC_VIRTUAL style set.



MoveToFocus(self)

Brings the current item into view.



MoveToItem(self, item)

Scrolls the input item into view.

Parameters

item – an instance of UltimateListItem.



OnArrowChar(self, newCurrent, event)

Handles the keyboard arrows key events.

Parameters
  • newCurrent – an integer specifying the new current item;

  • event – a KeyEvent event to be processed.



OnChar(self, event)

Handles the wx.EVT_CHAR event for UltimateListMainWindow.

Parameters

event – a KeyEvent event to be processed.



OnChildFocus(self, event)

Handles the wx.EVT_CHILD_FOCUS event for UltimateListMainWindow.

Parameters

event – a ChildFocusEvent event to be processed.

Note

This method is intentionally empty to prevent the default handler in ScrolledWindow from needlessly scrolling the window when the edit control is dismissed.



OnCompareItems(self, line1, line2)

Returns whether 2 lines have the same index.

Override this function in the derived class to change the sort order of the items in the UltimateListCtrl. The function should return a negative, zero or positive value if the first line is less than, equal to or greater than the second one.

Parameters

Note

The base class version compares lines by their index.



OnEraseBackground(self, event)

Handles the wx.EVT_ERASE_BACKGROUND event for UltimateListMainWindow.

Parameters

event – a EraseEvent event to be processed.

Note

This method is intentionally empty to reduce flicker.



OnHoverTimer(self, event)

Handles the wx.EVT_TIMER event for UltimateListMainWindow.

Parameters

event – a TimerEvent event to be processed.



OnKeyDown(self, event)

Handles the wx.EVT_KEY_DOWN event for UltimateListMainWindow.

Parameters

event – a KeyEvent event to be processed.



OnKeyUp(self, event)

Handles the wx.EVT_KEY_UP event for UltimateListMainWindow.

Parameters

event – a KeyEvent event to be processed.



OnKillFocus(self, event)

Handles the wx.EVT_KILL_FOCUS event for UltimateListMainWindow.

Parameters

event – a FocusEvent event to be processed.



OnMouse(self, event)

Handles the wx.EVT_MOUSE_EVENTS event for UltimateListMainWindow.

Parameters

event – a MouseEvent event to be processed.



OnPaint(self, event)

Handles the wx.EVT_PAINT event for UltimateListMainWindow.

Parameters

event – a PaintEvent event to be processed.



OnRenameAccept(self, itemEdit, value)

Called by UltimateListTextCtrl, to accept the changes and to send the EVT_LIST_END_LABEL_EDIT event.

Parameters
  • itemEdit – an instance of UltimateListItem;

  • value – the new value of the item label.



OnRenameCancelled(self, itemEdit)

Called by UltimateListTextCtrl, to cancel the changes and to send the EVT_LIST_END_LABEL_EDIT event.

Parameters

item – an instance of UltimateListItem.



OnRenameTimer(self)

The timer for renaming has expired. Start editing.



OnScroll(self, event)

Handles the wx.EVT_SCROLLWIN event for UltimateListMainWindow.

Parameters

event – a ScrollEvent event to be processed.



OnSetFocus(self, event)

Handles the wx.EVT_SET_FOCUS event for UltimateListMainWindow.

Parameters

event – a FocusEvent event to be processed.



PaintWaterMark(self, dc)

Draws a watermark at the bottom right of UltimateListCtrl.

Parameters

dc – an instance of wx.DC.

Todo

Better support for this is needed.



RecalculatePositions(self, noRefresh=False)

Recalculates all the items positions, and sets the scrollbars positions too.

Parameters

noRefreshTrue to avoid calling Refresh, False otherwise.



RefreshAfter(self, lineFrom)

Redraws all the lines after the input one.

Parameters

lineFrom – an integer representing the first line to refresh.



RefreshAll(self)

Refreshes the entire UltimateListCtrl.



RefreshLine(self, line)

Redraws the input line.

Parameters

line – an instance of UltimateListLineData.



RefreshLines(self, lineFrom, lineTo)

Redraws a range of lines in UltimateListCtrl.

Parameters
  • lineFrom – an integer representing the first line to refresh;

  • lineTo – an integer representing the last line to refresh.



RefreshSelected(self)

Redraws the selected lines.



ResetCurrent(self)

Resets the current item to None.



ResetLineDimensions(self, force=False)

Resets the line dimensions, so that client rectangles and positions are recalculated.

Parameters

forceTrue to reset all line dimensions.



ResetTextControl(self)

Called by UltimateListTextCtrl when it marks itself for deletion.



ResetVisibleLinesRange(self, reset=False)

Forces us to recalculate the range of visible lines.

Parameters

resetTrue to reset all line dimensions, which will then be recalculated.



ResizeColumns(self)

If ULC_AUTOSIZE_FILL was passed to UltimateListCtrl.SetColumnWidth() then that column’s width will be expanded to fill the window on a resize event.

Called by UltimateListCtrl.OnSize() when the window is resized.



ReverseHighlight(self, line)

Toggles the line state and refreshes it.

Parameters

line – an instance of UltimateListLineData.



ScrollList(self, dx, dy)

Scrolls the UltimateListCtrl.

Parameters
  • dx – if in icon, small icon or report view mode, specifies the number of pixels to scroll. If in list view mode, dx specifies the number of columns to scroll.

  • dy – always specifies the number of pixels to scroll vertically.



SendNotify(self, line, command, point=wx.DefaultPosition, col=0)

Actually sends a UltimateListEvent.

Parameters
  • line – an instance of UltimateListLineData;

  • command – the event type to send;

  • point – an instance of wx.Point.

  • col – an integer specifying the column index.



SetBackgroundImage(self, image)

Sets the UltimateListCtrl background image.

Parameters

image – if not None, an instance of wx.Bitmap.

Note

At present, the background image can only be used in “tile” mode.

Todo

Support background images also in stretch and centered modes.



SetColumn(self, col, item)

Sets information about this column.

Parameters
  • col – an integer specifying the column index;

  • item – an instance of UltimateListItem.



SetColumnCustomRenderer(self, col=0, renderer=None)

Associate a custom renderer to this column’s header

Parameters
  • col – the column index.

  • renderer – a class able to correctly render the input item.

Note

the renderer class must implement the methods DrawHeaderButton and GetForegroundColor.



SetColumnWidth(self, col, width)

Sets the column width.

Parameters

width – can be a width in pixels or wx.LIST_AUTOSIZE (-1) or wx.LIST_AUTOSIZE_USEHEADER (-2) or ULC_AUTOSIZE_FILL (-3). wx.LIST_AUTOSIZE will resize the column to the length of its longest item. wx.LIST_AUTOSIZE_USEHEADER will resize the column to the length of the header (Win32) or 80 pixels (other platforms). ULC_AUTOSIZE_FILL will resize the column fill the remaining width of the window.

Note

In small or normal icon view, col must be -1, and the column width is set for all columns.



SetDisabledTextColour(self, colour)

Sets the items disabled colour.

Parameters

colour – an instance of wx.Colour.



SetFirstGradientColour(self, colour=None)

Sets the first gradient colour for gradient-style selections.

Parameters

colour – if not None, a valid wx.Colour instance. Otherwise, the colour is taken from the system value wx.SYS_COLOUR_HIGHLIGHT.



SetFont(self, font)

Overridden base class virtual to reset the line height when the font changes.

Parameters

font – a valid wx.Font object.

Note

Overridden from ScrolledWindow.



SetGradientStyle(self, vertical=0)

Sets the gradient style for gradient-style selections.

Parameters

vertical – 0 for horizontal gradient-style selections, 1 for vertical gradient-style selections.



SetHyperTextFont(self, font)

Sets the font used to render hypertext items.

Parameters

font – a valid wx.Font instance.



SetHyperTextNewColour(self, colour)

Sets the colour used to render a non-visited hypertext item.

Parameters

colour – a valid wx.Colour instance.



SetHyperTextVisitedColour(self, colour)

Sets the colour used to render a visited hypertext item.

Parameters

colour – a valid wx.Colour instance.



SetImageList(self, imageList, which)

Sets the image list associated with the control.

Parameters
  • imageList – an instance of wx.ImageList or an instance of PyImageList;

  • which – one of wx.IMAGE_LIST_NORMAL, wx.IMAGE_LIST_SMALL, wx.IMAGE_LIST_STATE (the last is unimplemented).

Note

Using PyImageList enables you to have images of different size inside the image list. In your derived class, instead of doing this:

imageList = wx.ImageList(16, 16)
imageList.Add(someBitmap)
self.SetImageList(imageList, wx.IMAGE_LIST_SMALL)

You should do this:

imageList = PyImageList(16, 16)
imageList.Add(someBitmap)
self.SetImageList(imageList, wx.IMAGE_LIST_SMALL)


SetImageListCheck(self, sizex, sizey, imglist=None)

Sets the checkbox/radiobutton image list.

Parameters
  • sizex – the width of the bitmaps in the imglist;

  • sizey – the height of the bitmaps in the imglist;

  • imglist – an instance of wx.ImageList.



SetItem(self, item)

Sets information about the item.

Parameters

item – an instance of UltimateListItemData.



SetItemCount(self, count)

This method can only be used with virtual UltimateListCtrl. It is used to indicate to the control the number of items it contains. After calling it, the main program should be ready to handle calls to various item callbacks (such as UltimateListCtrl.OnGetItemText()) for all items in the range from 0 to count.

Parameters

count – the total number of items in UltimateListCtrl.



SetItemCustomRenderer(self, item, renderer=None)

Associate a custom renderer to this item.

Parameters
  • item – an instance of UltimateListItem;

  • renderer – a class able to correctly render the item.

Note

the renderer class must implement the methods DrawSubItem, GetLineHeight and GetSubItemWidth.



SetItemHyperText(self, item, hyper=True)

Sets whether the item is hypertext or not.

Parameters
  • item – an instance of UltimateListItem;

  • hyperTrue to have an item with hypertext behaviour, False otherwise.



SetItemKind(self, item, kind)

Sets the item kind.

Parameters
  • item – an instance of UltimateListItem;

  • kind – may be one of the following integers:

    Item Kind

    Description

    0

    A normal item

    1

    A checkbox-like item

    2

    A radiobutton-type item



SetItemOverFlow(self, item, over=True)

Sets the item in the overflow/non overflow state.

An item/subitem may overwrite neighboring items/subitems if its text would not normally fit in the space allotted to it.

Parameters
  • item – an instance of UltimateListItem;

  • overTrue to set the item in a overflow state, False otherwise.



SetItemSpacing(self, spacing, isSmall=False)

Sets the spacing between item texts and icons.

Parameters
  • spacing – the spacing between item texts and icons, in pixels;

  • isSmallTrue if using a wx.IMAGE_LIST_SMALL image list, False if using a wx.IMAGE_LIST_NORMAL image list.



SetItemState(self, litem, state, stateMask)

Sets the item state flags for the input item.

Parameters
  • litem – the index of the item; if defaulted to -1, the state flag will be set for all the items;

  • state – the item state flag;

  • stateMask – the bitmask for the state flag.

See also

SetItemStateAll for a list of valid state flags.



SetItemStateAll(self, state, stateMask)

Sets the item state flags for all the items.

Parameters
  • state – any combination of the following bits:

    State Bits

    Hex Value

    Description

    ULC_STATE_DONTCARE

    0x0

    Don’t care what the state is

    ULC_STATE_DROPHILITED

    0x1

    The item is highlighted to receive a drop event

    ULC_STATE_FOCUSED

    0x2

    The item has the focus

    ULC_STATE_SELECTED

    0x4

    The item is selected

    ULC_STATE_CUT

    0x8

    The item is in the cut state

    ULC_STATE_DISABLED

    0x10

    The item is disabled

    ULC_STATE_FILTERED

    0x20

    The item has been filtered

    ULC_STATE_INUSE

    0x40

    The item is in use

    ULC_STATE_PICKED

    0x80

    The item has been picked

    ULC_STATE_SOURCE

    0x100

    The item is a drag and drop source

  • stateMask – the bitmask for the state flag.

Note

The valid state flags are influenced by the value of the state mask.



SetItemText(self, item, value)

Sets the item text.

Parameters


SetItemVisited(self, item, visited=True)

Sets whether an hypertext item was visited.

Parameters
  • item – an instance of UltimateListItem;

  • visitedTrue to mark an hypertext item as visited, False otherwise.



SetItemWindow(self, item, wnd, expand=False)

Sets the window for the given item.

Parameters
  • item – an instance of UltimateListItem;

  • wnd – if not None, a non-toplevel window to be displayed next to the item;

  • expandTrue to expand the column where the item/subitem lives, so that the window will be fully visible.



SetItemWindowEnabled(self, item, enable=True)

Enables/disables the window associated to the item.

Parameters
  • item – an instance of UltimateListItem;

  • enableTrue to enable the associated window, False to disable it.



SetReportView(self, inReportView)

Sets whether UltimateListCtrl is in report view or not.

Parameters

inReportViewTrue to set UltimateListCtrl in report view, False otherwise.



SetSecondGradientColour(self, colour=None)

Sets the second gradient colour for gradient-style selections.

Parameters

colour – if not None, a valid wx.Colour instance. Otherwise, the colour generated is a slightly darker version of the UltimateListCtrl background colour.



SetUserLineHeight(self, height)

Sets a custom value for the UltimateListMainWindow item height.

Parameters

height – the custom height for all the items, in pixels.

Note

This method can be used only with ULC_REPORT and ULC_USER_ROW_HEIGHT styles set.



SetWaterMark(self, watermark)

Sets the UltimateListCtrl watermark image to be displayed in the bottom right part of the window.

Parameters

watermark – if not None, an instance of wx.Bitmap.

Todo

Better support for this is needed.



SortItems(self, func)

Call this function to sort the items in the UltimateListCtrl. Sorting is done using the specified function func. This function must have the following prototype:

def OnCompareItems(self, line1, line2):

    DoSomething(line1, line2)
    # function code

It is called each time when the two items must be compared and should return 0 if the items are equal, negative value if the first item is less than the second one and positive value if the first one is greater than the second one.

Parameters

func – the method to use to sort the items. The default is to use the OnCompareItems method.



TileBackground(self, dc)

Tiles the background image to fill all the available area.

Parameters

dc – an instance of wx.DC.

Todo

Support background images also in stretch and centered modes.



UpdateCurrent(self)

Updates the current line selection.