wxRuby Documentation Home

Wx::ListCtrl

A list control presents lists in a number of formats: list view, report view,
icon view and small icon view. In any case, elements are numbered from zero.
For all these modes, the items are stored in the control and must be added to
it using insert_item method. This class includes
Ruby’s Enumerable module, so methods such as find, select and collect
can be used to operate over the control’s whole contents.

A special case of report view quite different from the other modes of the list
control is a virtual control in which the items data (including text, images
and attributes) is managed by the main program and is requested by the control
itself only when needed which allows to have controls with millions of items
without consuming much memory. To use virtual list control you must use
set_item_count first and overload at least
on_get_item_text (and optionally
on_get_item_image and
on_get_item_attr) to return the information
about the items when the control requests it. Virtual list control can be used
as a normal one except that no operations which can take time proportional to
the number of items in the control happen — this is required to allow having a
practically infinite number of items. For example, in a multiple selection
virtual list control, the selections won’t be sent when many items are selected
at once because this could mean iterating over all the items.

To intercept events from a list control, use the event table macros described
in ListEvent.

Derived from

Control

Window

EvtHandler

Object

Window styles

LC_LIST Multicolumn list view, with optional small icons.Columns are computed automatically, i.e. you don’t set columns as in LC_REPORT. In other words,the list wraps, unlike a ListBox.
LC_REPORT Single or multicolumn report view, with optional header.
LC_VIRTUAL The application provides items text on demand. May only be used with LC_REPORT.
LC_ICON Large icon view, with optional labels.
LC_SMALL_ICON Small icon view, with optional labels.
LC_ALIGN_TOP Icons align to the top. Win32 default, Win32 only.
LC_ALIGN_LEFT Icons align to the left.
LC_AUTOARRANGE Icons arrange themselves. Win32 only.
LC_EDIT_LABELS Labels are editable: the application will be notified when editing starts.
LC_NO_HEADER No header in report mode.
LC_SINGLE_SEL Single selection (default is multiple).
LC_SORT_ASCENDING Sort in ascending order (must still supply a comparison callback in SortItems.
LC_SORT_DESCENDING Sort in descending order (must still supply a comparison callback in SortItems.
LC_HRULES Draws light horizontal rules between rows in report mode.
LC_VRULES Draws light vertical rules between columns in report mode.

See also window styles overview.

Event handling

To process input from a list control, use these event handler macros to direct input to member
functions that take a ListEvent argument.

evt_list_begin_drag(id) { | event | … } Begin dragging with the left mouse button.
evt_list_begin_rdrag(id) { | event | … } Begin dragging with the right mouse button.
evt_list_begin_label_edit(id) { | event | … } Begin editing a label. This can be prevented by calling Veto.
evt_list_end_label_edit(id) { | event | … } Finish editing a label. This can be prevented by calling Veto.
evt_list_delete_item(id) { | event | … } Delete an item.
evt_list_delete_all_items(id) { | event | … } Delete all items.
evt_list_item_selected(id) { | event | … } The item has been selected.
evt_list_item_deselected(id) { | event | … } The item has been deselected.
evt_list_item_activated(id) { | event | … } The item has been activated (ENTER or double click).
evt_list_item_focused(id) { | event | … } The currently focused item has changed.
evt_list_item_middle_click(id) { | event | … } The middle mouse button has been clicked on an item.
evt_list_item_right_click(id) { | event | … } The right mouse button has been clicked on an item.
evt_list_key_down(id) { | event | … } A key has been pressed.
evt_list_insert_item(id) { | event | … } An item has been inserted.
evt_list_col_click(id) { | event | … } A column (m_col) has been left-clicked.
evt_list_col_right_click(id) { | event | … } A column (m_col) has been right-clicked.
evt_list_col_begin_drag(id) { | event | … } The user started resizing a column – can be vetoed.
evt_list_col_dragging(id) { | event | … } The divider between columns is being dragged.
evt_list_col_end_drag(id) { | event | … } A column has been resized by the user.
evt_list_cache_hint(id) { | event | … } Prepare cache for a virtual list control

See also

ListBox, TreeCtrl, ImageList, ListEvent,
ListItem

Methods

ListCtrl.new

ListCtrl.new(%(arg-type)Window% parent, Integer id, Point pos = DEFAULT_POSITION, Size size = DEFAULT_SIZE, Integer style = LC_ICON, Validator validator = DEFAULT_VALIDATOR, String name = ListCtrlNameStr)

Constructor, creating and showing a list control.

Parameters

See also

ListCtrl#create, Validator

ListCtrl#arrange

Boolean arrange(%(arg-type)Integer% flag = LIST_ALIGN_DEFAULT)

Arranges the items in icon or small icon view. This only has effect on Win32. flag is one of:

LIST_ALIGN_DEFAULT Default alignment.
LIST_ALIGN_LEFT Align to the left side of the control.
LIST_ALIGN_TOP Align to the top side of the control.
LIST_ALIGN_SNAP_TO_GRID Snap to grid.

See also

ListCtrl#set_image_list

ListCtrl#clear_all

clear_all()

Deletes all items and all columns.

ListCtrl#create

Boolean create(%(arg-type)Window% parent, Integer id, Point pos = DEFAULT_POSITION, Size size = DEFAULT_SIZE, Integer style = LC_ICON, Validator validator = DEFAULT_VALIDATOR, String name = ListCtrlNameStr)

Creates the list control. See ListCtrl.new for further details.

ListCtrl#delete_all_items

Boolean delete_all_items()

Deletes all the items in the list control.

NB: This function does not send the
EVT_COMMAND_LIST_DELETE_ITEM event because deleting many items
from the control would be too slow then (unlike delete_item).

ListCtrl#delete_column

Boolean delete_column(%(arg-type)Integer% col)

Deletes a column.

ListCtrl#delete_item

Boolean delete_item(%(arg-type)Integer% item)

Deletes the specified item. This function sends the
EVT_COMMAND_LIST_DELETE_ITEM event for the item being deleted.

See also: delete_all_items

ListCtrl#each

each() { | index | … }

Can be used to iterate over the control’s contents; passes the integer
index of each valid item in the control into the passed block.

ListCtrl#edit_label

edit_label(%(arg-type)Integer% item)

Starts editing the label of the given item. This function generates a
EVT_LIST_BEGIN_LABEL_EDIT event which can be vetoed so that no
text control will appear for in-place editing.

If the user changed the label (i.e. s/he does not press ESC or leave
the text control without changes, a EVT_LIST_END_LABEL_EDIT event
will be sent which can be vetoed as well.

ListCtrl#ensure_visible

Boolean ensure_visible(%(arg-type)Integer% item)

Ensures this item is visible.

ListCtrl#find_item

Integer find_item(%(arg-type)Integer% start, String str, Boolean partial = false)

Find an item whose label matches this string, starting from start or
the beginning if start is -1.

Integer find_item(%(arg-type)Integer% start, Integer data)

Find an item whose data matches this data, starting from start or
the beginning if ‘start’ is -1.

Integer find_item(%(arg-type)Integer% start, Point pt, Integer direction)

Find an item nearest this position in the specified direction, starting from
start or the beginning if start is -1.

ListCtrl#get_column

Boolean get_column(%(arg-type)Integer% col, ListItem item)

Gets information about this column. See ListCtrl#set_item for more
information.

ListCtrl#get_column_count

Integer get_column_count()

Returns the number of columns.

ListCtrl#get_column_width

Integer get_column_width(%(arg-type)Integer% col)

Gets the column width (report view only).

ListCtrl#get_count_per_page

Integer get_count_per_page()

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

ListCtrl#get_edit_control

TextCtrl get_edit_control()

Returns the edit control being currently used to edit a label. Returns NULL
if no label is being edited.

NB: It is currently only implemented for MSW.

ListCtrl#get_image_list

ImageList get_image_list(%(arg-type)Integer% which)

Returns the specified image list. which may be one of:

IMAGE_LIST_NORMAL The normal (large icon) image list.
IMAGE_LIST_SMALL The small icon image list.
IMAGE_LIST_STATE The user-defined state image list (unimplemented).

ListCtrl#get_item

ListItem get_item(%(arg-type)Integer% row, Integer col = -1)

Gets information, such as the text label, font and colour, about a
ListCtrl item at zero-based row number row. The col parameter is
optional, and is only meaningful if the ListCtrl was created with the
style LC_REPORT. In that case the ListItem will contain information
such as the text content specific to that column in that row.

The information about the list entry is returned as a
ListItem – see that class and
ListCtrl#set_item for more information.

ListCtrl#get_item_background_colour

Colour get_item_background_colour(%(arg-type)Integer% item)

Returns the colour for this item. If the item has no specific colour, returns
an invalid colour (and not the default background control of the control
itself).

See also

get_item_text_colour

ListCtrl#get_item_count

Integer get_item_count()

Returns the number of items in the list control.

ListCtrl#get_item_data

Object get_item_data(%(arg-type)Integer% item)

Gets the application-defined data object associated with this item; see
set_item_data.

ListCtrl#get_item_font

Font get_item_font(%(arg-type)Integer% item)

Returns the item’s font.

ListCtrl#get_item_position

Boolean get_item_position(%(arg-type)Integer% item, Point pos)

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

ListCtrl#get_item_rect

Rect get_item_rect(%(arg-type)Integer% item, Integer code = LIST_RECT_BOUNDS)

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

code is one of LIST_RECT_BOUNDS, LIST_RECT_ICON, LIST_RECT_LABEL.

ListCtrl#get_item_spacing

Size get_item_spacing()

Retrieves the spacing between icons in pixels: horizontal spacing is returned
as x component of the Size object and the vertical
spacing as its y component.

ListCtrl#get_item_state

Integer get_item_state(%(arg-type)Integer% item, Integer stateMask)

Gets the item state. For a list of state flags, see ListCtrl#set_item.

The stateMask indicates which state flags are of interest.

ListCtrl#get_item_text

String get_item_text(%(arg-type)Integer% item)

Gets the item text for this item.

ListCtrl#get_item_text_colour

Colour get_item_text_colour(%(arg-type)Integer% item)

Returns the colour for this item. If the item has no specific colour, returns
an invalid colour (and not the default foreground control of the control itself
as this wouldn’t allow distinguishing between items having the same colour as
the current control foreground and items with default colour which, hence, have
always the same colour as the control).

ListCtrl#get_next_item

Integer get_next_item(%(arg-type)Integer% item, Integer geometry = LIST_NEXT_ALL, Integer state = LIST_STATE_DONTCARE)

Searches for an item with the given geometry or state, starting from
item but excluding the item itself. If item is -1,
the first item that matches the specified flags will be returned.

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

geometry can be one of:

LIST_NEXT_ABOVE Searches for an item above the specified item.
LIST_NEXT_ALL Searches for subsequent item by index.
LIST_NEXT_BELOW Searches for an item below the specified item.
LIST_NEXT_LEFT Searches for an item to the left of the specified item.
LIST_NEXT_RIGHT Searches for an item to the right of the specified item.

NB: this parameter is only supported by MSW currently and ignored on
other platforms.

state can be a combination of the following:

LIST_STATE_DONTCARE Don’t care what the state is.
LIST_STATE_DROPHILITED The item indicates it is a drop target.
LIST_STATE_FOCUSED The item has the focus.
LIST_STATE_SELECTED The item is selected.
LIST_STATE_CUT The item is selected as part of a cut and paste operation.

ListCtrl#get_selected_item_count

Integer get_selected_item_count()

Returns the number of selected items in the list control.

ListCtrl#get_selections

Array get_selections()

Returns an array containing the indexes of all the rows that are
currently selected.

ListCtrl#get_text_colour

Colour get_text_colour()

Gets the text colour of the list control.

ListCtrl#get_top_item

Integer get_top_item()

Gets the index of the topmost visible item when in
list or report view.

ListCtrl#get_view_rect

Rect get_view_rect()

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 that this function only works in the icon and small icon views, not in
list or report views (this is a limitation of the native Win32 control).

ListCtrl#hit_test

[ Integer item, Integer flags ] = hit_test(%(arg-type)Point% point)

Determines which item (if any) is at the specified point, giving details
in flags_. Returns a two-element array, with the first element being
the index of the item or @NOT
FOUND@ if no item is at the specified
point. flags will be a combination of the following flags:

LIST_HITTEST_ABOVE Above the client area.
LIST_HITTEST_BELOW Below the client area.
LIST_HITTEST_NOWHERE In the client area but below the last item.
LIST_HITTEST_ONITEMICON On the bitmap associated with an item.
LIST_HITTEST_ONITEMLABEL On the label (string) associated with an item.
LIST_HITTEST_ONITEMRIGHT In the area to the right of an item.
LIST_HITTEST_ONITEMSTATEICON On the state icon for a tree view item that is in a user-defined state.
LIST_HITTEST_TOLEFT To the right of the client area.
LIST_HITTEST_TORIGHT To the left of the client area.
LIST_HITTEST_ONITEM Combination of LIST_HITTEST_ONITEMICON, LIST_HITTEST_ONITEMLABEL,LIST_HITTEST_ONITEMSTATEICON.

ListCtrl#insert_column

Integer insert_column(%(arg-type)Integer% col, ListItem info) Integer insert_column(%(arg-type)Integer% col, String heading, Integer format = LIST_FORMAT_LEFT, Integer width = -1)

For report view mode (only), inserts a column. For more details, see ListCtrl#set_item.

ListCtrl#insert_item

Integer insert_item(%(arg-type)ListItem% info)

Inserts an item, returning the index of the new item if successful,
-1 otherwise.

Integer insert_item(%(arg-type)Integer% index, String label)

Inserts a string item.

Integer insert_item(%(arg-type)Integer% index, Integer imageIndex)

Inserts an image item.

Integer insert_item(%(arg-type)Integer% index, String label, Integer imageIndex)

Insert an image/string item.

Note that if you are using a ListCtrl with the Wx::LC_REPORT style,
you must create one or more columns using the insert_column method
before inserting items, or it will not work, and WxRuby may crash.

Parameters

ListCtrl#on_get_item_attr

ListItemAttr on_get_item_attr(%(arg-type)Integer% item)

This function may be overloaded in the derived class for a control with
LC_VIRTUAL style. It should return the attribute for the
for the specified item or NULL to use the default appearance
parameters.

ListCtrl will not delete the pointer or keep a reference of it. You can
return the same ListItemAttr pointer for every OnGetItemAttr call.

The base class version always returns NULL.

See also

on_get_item_image,

on_get_item_text

ListCtrl#on_get_item_image

Integer on_get_item_image(%(arg-type)Integer% item)

This function must be overloaded in the derived class for a control with
LC_VIRTUAL style having an image list
(if the control doesn’t have an image list, it is not necessary to overload
it). It should return the index of the items image in the controls image list
or $-1$ for no image.
In a control with LC_REPORT style, OnGetItemImage only gets called for
the first column of each line.

The base class version always returns $-1$.

See also

on_get_item_text,

on_get_item_attr

ListCtrl#on_get_item_text

String on_get_item_text(%(arg-type)Integer% item, Integer column)

This function must be overloaded in the derived class for a control with
LC_VIRTUAL style. It should return the string containing the text of
the given column for the specified item.

See also

set_item_count,

on_get_item_image,

on_get_item_attr

ListCtrl#refresh_item

refresh_item(%(arg-type)Integer% item)

Redraws the given item. This is only useful for the virtual list controls
as without calling this function the displayed value of the item doesn’t change
even when the underlying data does change.

See also

refresh_items

ListCtrl#refresh_items

refresh_items(%(arg-type)Integer% itemFrom, Integer itemTo)

Redraws the items between itemFrom and itemTo. The starting item
must be less than or equal to the ending one.

Just as refresh_item this is only useful for
virtual list controls.

ListCtrl#scroll_list

Boolean scroll_list(%(arg-type)Integer% dx, Integer dy)

Scrolls the list control. If in icon, small icon or report view mode,
dx 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.

NB: This method is currently only implemented in the Windows version.

ListCtrl#set_background_colour

set_background_colour(%(arg-type)Colour% col)

Sets the background colour (GetBackgroundColour already implicit in
Window class).

ListCtrl#set_column

Boolean set_column(%(arg-type)Integer% col, ListItem item)

Sets information about this column. See ListCtrl#set_item for more
information.

ListCtrl#set_column_width

Boolean set_column_width(%(arg-type)Integer% col, Integer width)

Sets the column width.

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

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

ListCtrl#set_image_list

set_image_list(%(arg-type)ImageList% imageList, Integer which)

Sets the image list associated with the control. which is one of
IMAGE_LIST_NORMAL, IMAGE_LIST_SMALL, IMAGE_LIST_STATE (the last is unimplemented).
h3(#ListCtrl_setitem). ListCtrl#set_item

Integer set_item(%(arg-type)Integer% index, Integer col, String label, Integer imageId = -1) Boolean set_item(%(arg-type)ListItem% info)

Sets information about the item. The first form of the method sets the
label in the specified row and column to the specified string.

The second form is more flexible, as it allows setting a number of
attributes at once. ListItem is a class with the following attributes -
see the ListItem class for how to create this class and
set its attributes in wxRuby.

long m_mask Indicates which fields are valid. See the list of valid mask flags below.
long m_itemId The zero-based item position.
int m_col Zero-based column, if in report mode.
long m_state The state of the item. See the list of valid state flags below.
long m_stateMask A mask indicating which state flags are valid. See the list of valid state flags below.
String m_text The label/header text.
int m_image The zero-based index into an image list.
long m_data Application-defined data.
int m_format For columns only: the format. Can be LIST_FORMAT_LEFT, LIST_FORMAT_RIGHT orLIST_FORMAT_CENTRE.
int m_width For columns only: the column width.

The m_mask member contains a bitlist specifying which of the other fields are valid. The flags are:

LIST_MASK_STATE The m_state field is valid.
LIST_MASK_TEXT The m_text field is valid.
LIST_MASK_IMAGE The m_image field is valid.
LIST_MASK_DATA The m_data field is valid.
LIST_MASK_WIDTH The m_width field is valid.
LIST_MASK_FORMAT The m_format field is valid.

The m_stateMask and m_state members take flags from the following:

LIST_STATE_DONTCARE Don’t care what the state is. Win32 only.
LIST_STATE_DROPHILITED The item is highlighted to receive a drop event. Win32 only.
LIST_STATE_FOCUSED The item has the focus.
LIST_STATE_SELECTED The item is selected.
LIST_STATE_CUT The item is in the cut state. Win32 only.

The ListItem object can also contain item-specific colour and font
information: for this you need to call one of SetTextColour(),
SetBackgroundColour() or SetFont() functions on it passing it the colour/font
to use. If the colour/font is not specified, the default list control
colour/font is used.

ListCtrl#set_item_background_colour

set_item_background_colour(%(arg-type)Integer% item, Colour col)

Sets the background colour for this item. This function only works in report view.

The colour can be retrieved using
get_item_background_colour.

ListCtrl#set_item_count

set_item_count(%(arg-type)Integer% count)

This method can only be used with virtual list controls. 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
on_get_item_text) for all items in the range
from $0$ to count.

ListCtrl#set_item_data

Boolean set_item_data(%(arg-type)Integer% item, Object data)

Associates application-defined data with this item. Any normal ruby
object may be stored as item data. Note that in a multi-column ListCtrl,
created with Wx::LC_REPORT, item data is still stored per-row.

ListCtrl#set_item_font

set_item_font(%(arg-type)Integer% item, Font font)

Sets the item’s font.

ListCtrl#set_item_image

Boolean set_item_image(%(arg-type)Integer% item, Integer image)

Sets the image associated with the item. The image is an index into the
image list associated with the list control. In report view, this only sets
the image for the first column.

Boolean set_item_image(%(arg-type)Integer% item, Integer image, Integer selImage)

Sets the unselected and selected images associated with the item. The images are indices into the
image list associated with the list control. This form is deprecated: selImage is not
used.

ListCtrl#set_item_column_image

Boolean set_item_image(%(arg-type)Integer% item, Integer column%(arg-type)Integer% image)

Sets the image associated with the item. In report view, you can specify the column.
The image is an index into the image list associated with the list control.

ListCtrl#set_item_position

Boolean set_item_position(%(arg-type)Integer% item, Point pos)

Sets the position of the item, in icon or small icon view. Windows only.

ListCtrl#set_item_state

Boolean set_item_state(%(arg-type)Integer% item, Integer state, Integer stateMask)

Sets the item state. For a list of state flags, see ListCtrl#set_item.

The stateMask indicates which state flags are valid.

ListCtrl#set_item_text

set_item_text(%(arg-type)Integer% item, String text)

Sets the item text for this item.

ListCtrl#set_item_text_colour

set_item_text_colour(%(arg-type)Integer% item, Colour col)

Sets the colour for this item. This function only works in report view.

The colour can be retrieved using
get_item_text_colour.

ListCtrl#set_single_style

set_single_style(%(arg-type)Integer% style, Boolean add = true)

Adds or removes a single window style.

ListCtrl#set_text_colour

set_text_colour(%(arg-type)Colour% col)

Sets the text colour of the list control.

ListCtrl#set_window_style_flag

set_window_style_flag(%(arg-type)Integer% style)

Sets the whole window style, deleting all items.

ListCtrl#sort_items

sort_items() { | a, b | … }

Call this function to sort the items in the list control. Sorting is
done according to the passed block, which should accept two
arguments. This block will be called each time a pair of items is being
compared; it will be passed the item data associated with the two items.

The block should return 0 if the items are equal, a negative numeric
value if the first item is less than the second one and a positive
numeric value if the first one is greater than the second one. This is
similar to the way that Ruby classes implementing the comparison
operator “<=>” must work. In fact, ListCtrl#sort_items can be used simply by
relying on that ruby method, if the item data in the control is of a
suitable class (eg Numeric, String):

list_ctrl.sort_items { | a, b | a <=> b }

Note that the control may only be sorted on item data associated with
the items; the block is not passed the indexes of the
items. Therefore, you must use set_item_data
if you want to be able to sort the items in the control.

[This page automatically generated from the Textile source at 2023-06-03 08:07:42 +0000]