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
LC_ICON
,
Validator validator = DEFAULT_VALIDATOR,
String name = ListCtrlNameStr)
Constructor, creating and showing a list control.
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. |
Deletes all items and all columns.
Creates the list control. See ListCtrl.new for further details.
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).
Deletes a column.
Deletes the specified item. This function sends the
EVT_COMMAND_LIST_DELETE_ITEM
event for the item being deleted.
See also: delete_all_items
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.
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.
Ensures this item is visible.
Find an item whose label matches this string, starting from start or
the beginning if start is -1.
Find an item whose data matches this data, starting from start or
the beginning if ‘start’ is -1.
Find an item nearest this position in the specified direction, starting from
start or the beginning if start is -1.
Gets information about this column. See ListCtrl#set_item for more
information.
Returns the number of columns.
Gets the column width (report view only).
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).
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.
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). |
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.
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).
Returns the number of items in the list control.
Gets the application-defined data object associated with this item; see
set_item_data.
Returns the item’s font.
Returns the position of the item, in icon or small icon view.
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.
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.
Gets the item state. For a list of state flags, see ListCtrl#set_item.
The stateMask indicates which state flags are of interest.
Gets the item text for this 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).
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. |
Returns the number of selected items in the list control.
Returns an array containing the indexes of all the rows that are
currently selected.
Gets the text colour of the list control.
Gets the index of the topmost visible item when in
list or report view.
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).
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 @NOTFOUND@ 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. |
For report view mode (only), inserts a column. For more details, see ListCtrl#set_item.
Inserts an item, returning the index of the new item if successful,
-1 otherwise.
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.
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
.
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$.
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
.
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.
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.
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.
Sets the background colour (GetBackgroundColour already implicit in
Window class).
Sets information about this column. See ListCtrl#set_item for more
information.
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.
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
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.
Sets the background colour for this item. This function only works in report view.
The colour can be retrieved using
get_item_background_colour.
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.
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.
Sets the item’s font.
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.
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.
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.
Sets the position of the item, in icon or small icon view. Windows only.
Sets the item state. For a list of state flags, see ListCtrl#set_item.
The stateMask indicates which state flags are valid.
Sets the item text for this item.
Sets the colour for this item. This function only works in report view.
The colour can be retrieved using
get_item_text_colour.
Adds or removes a single window style.
Sets the text colour of the list control.
Sets the whole window style, deleting all items.
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):
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-13 21:31:42 +0000]