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(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(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(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(Integer col)

Deletes a column.

ListCtrl#delete_item

Boolean delete_item(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(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(Integer item)

Ensures this item is visible.

ListCtrl#find_item

Integer find_item(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(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(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(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(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(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(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(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(Integer item)

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

ListCtrl#get_item_font

Font get_item_font(Integer item)

Returns the item’s font.

ListCtrl#get_item_position

Boolean get_item_position(Integer item,  Point pos)

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

ListCtrl#get_item_rect

Rect get_item_rect(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(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(Integer item)

Gets the item text for this item.

ListCtrl#get_item_text_colour

Colour get_item_text_colour(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(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(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(Integer col,  ListItem info)
Integer insert_column(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(ListItem info)

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

Integer insert_item(Integer index,  String label)

Inserts a string item.

Integer insert_item(Integer index,  Integer imageIndex)

Inserts an image item.

Integer insert_item(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(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(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(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(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(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(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(Colour col)

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

ListCtrl#set_column

Boolean set_column(Integer col,  ListItem item)

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

ListCtrl#set_column_width

Boolean set_column_width(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(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).

ListCtrl#set_item

Integer set_item(Integer index,  Integer col, 
                    String label, 
                   Integer imageId = -1)
Boolean set_item(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(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(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(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(Integer item,  Font font)

Sets the item’s font.

ListCtrl#set_item_image

Boolean set_item_image(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(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(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(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(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(Integer item,  String text)

Sets the item text for this item.

ListCtrl#set_item_text_colour

set_item_text_colour(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(Integer style,  Boolean add = true)

Adds or removes a single window style.

ListCtrl#set_text_colour

set_text_colour(Colour col)

Sets the text colour of the list control.

ListCtrl#set_window_style_flag

set_window_style_flag(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 Wed Sep 09 02:21:15 +0100 2009]