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.
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.
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 |
ListBox, TreeCtrl, ImageList, ListEvent, ListItem
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.
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. |
clear_all()Deletes all items and all columns.
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.
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).
Boolean delete_column(Integer col)Deletes a column.
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
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.
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.
Boolean ensure_visible(Integer item)Ensures this item is visible.
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.
Boolean get_column(Integer col, ListItem item)Gets information about this column. See ListCtrl#set_item for more information.
Integer get_column_count()Returns the number of columns.
Integer get_column_width(Integer col)Gets the column width (report view only).
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).
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.
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). |
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.
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).
Integer get_item_count()Returns the number of items in the list control.
Object get_item_data(Integer item)Gets the application-defined data object associated with this item; see set_item_data.
Font get_item_font(Integer item)Returns the item’s font.
Boolean get_item_position(Integer item, Point pos)Returns the position of the item, in icon or small icon view.
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.
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.
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.
String get_item_text(Integer item)Gets the item text for this item.
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).
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. |
Integer get_selected_item_count()Returns the number of selected items in the list control.
Array get_selections()Returns an array containing the indexes of all the rows that are currently selected.
Colour get_text_colour()Gets the text colour of the list control.
Integer get_top_item()Gets the index of the topmost visible item when in list or report view.
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).
[ 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. |
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.
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.
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.
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$.
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.
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.
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.
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.
set_background_colour(Colour col)Sets the background colour (GetBackgroundColour already implicit in Window class).
Boolean set_column(Integer col, ListItem item)Sets information about this column. See ListCtrl#set_item for more information.
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.
set_image_list(ImageList imageList, Integer which)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.
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.
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.
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.
set_item_font(Integer item, Font font)Sets the item’s font.
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.
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.
Boolean set_item_position(Integer item, Point pos)Sets the position of the item, in icon or small icon view. Windows only.
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.
set_item_text(Integer item, String text)Sets the item text for this item.
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.
set_single_style(Integer style, Boolean add = true)Adds or removes a single window style.
set_text_colour(Colour col)Sets the text colour of the list control.
set_window_style_flag(Integer style)Sets the whole window style, deleting all 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]