wxJavaScript

back to gui 

wxListCtrl

^{generated from ../src/mod_gui/control/listctrl.cpp}

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 insertItem method.

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 set itemCount first and set at least onGetItemText (and optionally onGetItemImage and onGetItemAttr) 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.

How to sort items?
This example shows a dialog containing a wxListCtrl and two buttons. The list control contains 4 elements 'A', 'B', 'C' and 'D'. Clicking on one of the buttons, will sort the elements in descending or ascending order. First the dialog box is created. A wxBoxSizer is used to layout the dialog. The list control will be shown above the buttons and centered horizontally. Above and below the listcontrol a space of 10 is placed.

   dlg = new wxDialog(null, -1, "wxListCtrl sort example", 
                      wxDefaultPosition, new wxSize(200, 200));
   // The main sizer
   dlg.sizer = new wxBoxSizer(wxOrientation.VERTICAL);

   // Create the listcontrol and add it to the sizer.
   list = new wxListCtrl(dlg, -1, wxDefaultPosition, new wxSize(100, 100));
   dlg.sizer.add(list, 0, wxAlignment.CENTER | wxDirection.BOTTOM | wxDirection.TOP, 10);

   // Create buttons and add them to a boxsizer.
   var btn1 = new wxButton(dlg, -1, "Sort Descending");
   btn1.onClicked = function()
   {
     list.sortItems(sort, 1);
   };
  
   var btn2 = new wxButton(dlg, -2, "Sort Ascending");
   btn2.onClicked = function()
   {
     list.sortItems(sort, 0);
   };

   boxsizer = new wxBoxSizer(wxOrientation.HORIZONTAL);
   boxsizer.add(btn1, 0, wxDirection.RIGHT, 10);
   boxsizer.add(btn2);

   dlg.sizer.add(boxsizer, 0, wxAlignment.CENTER);
   

An array which hold the characters 'A', 'B', 'C' and 'D' is created. Each element is inserted. The itemdata is set to the letter. This is necessary because the sort function uses the itemdata.

 
   var letter = new Array();
   letter[0] = "A";
   letter[1] = "B";
   letter[2] = "C";
   letter[3] = "D";
   for(e in letter)
   {
     var idx = list.insertItem(e, letter[e]);
     list.setItemData(idx, letter[e]);
   }
  

Show the dialog.

   dlg.layout();
   dlg.showModal();
  

The function gets 3 arguments. The first two are the itemdata (which is the index of the corresponding array element) of the first item and the second item. Data is the data passed to sortItems in the onClicked event of wxButton. This way the sort function knows how to sort the items.

   function sort(item1, item2, data)
   {
     if ( data == 1 )
     {
       if ( item1 > item2 )
         return -1;
       else if ( item1 < item2 )
         return 1;
       else return 0;
     }
     else
     {
       if ( item1 > item2 )
         return 1;
       else if ( item1 < item2 )
         return -1;
       else return 0;
     }
   }
   

How to use virtual list controls ?
This example shows how a virtual list control is built. First an array is create which will contain objects of type Car.

   var cars = new Array();

   function Car(brand, type, colour)
   {
     this.brand = brand;
     this.type = type;
     this.colour = colour;
   }

   cars[0] = new Car("Opel", "Astra", "Red");
   cars[1] = new Car("Ford", "Focus", "Black");
   cars[2] = new Car("Skoda", "Octavia", "Green");
   cars[3] = new Car("Peugeot", "305", "White");
   cars[4] = new Car("Citroen", "Picasso", "Green");
   

The init function will create a frame and a list control. The list control is the child of the frame and its style is REPORT and VIRTUAL. For each property of Car, a column is created. Because the list control is virtual, onGetItemText and itemCount must be set.

   function init()
   {
     var frame = new wxFrame(null, -1, "wxListCtrl example");
   
     var listCtrl = new wxListCtrl(frame, -1, wxDefaultPosition,
                                   wxDefaultSize, wxListCtrl.REPORT | wxListCtrl.VIRTUAL);
     listCtrl.insertColumn(0, "Brand");
     listCtrl.insertColumn(1, "Type");
     listCtrl.insertColumn(2, "Colour");
     listCtrl.onGetItemText = getItemText;
     listCtrl.itemCount = cars.length;
     
     frame.visible = true;
     topWindow = frame;
     
     return true;
     }
   

The function getItemText will be called by wxWidgets whenever it needs to know the text of an item. This function gets two arguments: the item and the column index. The text that must be shown is returned.

   function getItemText(item, col)
   {
     var car = cars[item];
   
     switch(col)
     {
       case 0: return car.brand;
       case 1: return car.type;
       case 2: return car.colour;    
     }
   }
   
   wxTheApp.onInit = init;
  

Constants

Autosize

Name	Description
AUTOSIZE	Resize the column to the length of its longest item
AUTOSIZE_USEHEADER	Resize the column to the length of the header (Win32) or 80 pixels (other platforms).

These constants can be used with setColumnWidth.

ImageList Constants

Name	Description
NORMAL	The normal (large icon) image list.
SMALL	The small icon image list.
STATE	The user-defined state image list (unimplemented).

Styles

Name	Description
LIST	Multicolumn list view, with optional small icons. Columns are computed automatically, i.e. you don't set columns as in REPORT. In other words, the list wraps, unlike a wxListBox.
REPORT	Single or multicolumn report view, with optional header.
VIRTUAL	Virtual control, may only be used with REPORT
ICON	Large icon view, with optional labels.
SMALL_ICON	Small icon view, with optional labels.
ALIGN_TOP	Icons align to the top. Win32 default, Win32 only.
ALIGN_LEFT	Icons align to the left.
AUTOARRANGE	Icons arrange themselves. Win32 only.
USER_TEXT	The application provides label text on demand, except for column headers. Win32 only.
EDIT_LABELS	Labels are editable: the application will be notified when editing starts.
NO_HEADER	No header in report mode. Win32 only.
SINGLE_SEL	Single selection.
SORT_ASCENDING	Sort in ascending order (must still supply a comparison callback in SortItems).
SORT_DESCENDING	Sort in descending order (must still supply a comparison callback in SortItems).
HRULES	Draws light horizontal rules between rows in report mode.
VRULES	Draws light vertical rules between columns in report mode.

wxListAlign

Name	Description
DEFAULT
ALIGN_LEFT
ALIGN_TOP
ALIGN_SNAP_TO_GRID

wxListAlign is ported as a separate JavaScript class.

wxListColumnFormat

Name	Description
LEFT
RIGHT
CENTRE
CENTER

wxListColumnFormat is ported as a separate JavaScript class.

wxListFind

Name	Description
UP
DOWN
LEFT
RIGHT

wxListFind is ported as a separate JavaScript class.

wxListMask

Name	Description
STATE
TEXT
IMAGE
DATA
ITEM
WIDTH
FORMAT

wxListMask is ported as a separate JavaScript class

wxListNext

Name	Description
ABOVE	Searches for an item above the specified item
ALL	Searches for subsequent item by index
BELOW	Searches for an item below the specified item
LEFT	Searches for an item to the left of the specified item
RIGHT	Searches for an item to the right of the specified item

wxListNext is ported as a separate JavaScript class. See getNextItem.

wxListRect

Name	Description
BOUNDS
ICON
LABEL

wxListRect is ported as a separate JavaScript class.

wxListState

Name	Description
DONTCARE
DROPHILITED	(Windows only)
FOCUSED
SELECTED
CUT	(Windows only)

wxListState is ported as a separate JavaScript class

Constructor

wxListCtrl

wxListCtrl()
 

wxListCtrl(Parent, 
           Id, 
           Position = wxDefaultPosition, 
           Size = wxDefaultSize, 
           Style = wxListCtrl.ICON, 
           Validator = null)
 

Name	Type	Default	Description
Parent	wxWindow		The parent of wxListCtrl. Can't be null.
Id	Integer		An window identifier. Use -1 when you don't need it.
Position	wxPoint	wxDefaultPosition	The position of the ListCtrl control on the given parent.
Size	wxSize	wxDefaultSize	The size of the ListCtrl control.
Style	Integer	wxListCtrl.ICON	The wxListCtrl style.
Validator	wxValidator	null	Validator.

Constructs a new wxListCtrl object.

Properties

Name	Type	Description
columnCount	Integer	Gets the number of columns.
countPerPage	Integer	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).
editControl	wxTextCtrl	Gets the textcontrol used for editing labels.
itemCount	Integer	Gets/Sets the number of items. Setting the number of items is only allowed with virtual list controls.
onGetItemAttr	Function	Assign a function that returns a wxListItemAttr object. The function gets one argument: the index of the item. This can only be used in virtual list controls.
onGetItemImage	Function	Assign a function that returns the index of the image. The function gets one argument: the index of the item. This can only be used in virtual list controls.
onGetItemText	Function	Assign a function that returns a String. This String is used as text of the item. The function gets two arguments: the index of the item and the index of the column. You must set this property for virtual list controls.
selectedItemCount	Integer	Gets the number of selected items.
textColour	wxColour	Gets/Sets the text colour of the list control.
topItem	Integer	Gets the index of the topmost visible item in report view.
virtual	Boolean	Returns true when the list control is virtual.
windowStyleFlag	Integer	Gets/Sets the window style flag.

Methods

(Item) : wxListItem
 

Name	Type	Default	Description
Item	Integer		The item index

(ListItem) : Boolean
 

Name	Type	Default	Description
ListItem	wxListItem		The item info. Make sure that the id property is set.

Gets the item information. The first form returns a wxListItem object or undefined when the item is not found. The second form returns true when the item is found and puts the item information in the argument.

arrange

arrange(Align = wxListAlign.DEFAULT) : Boolean
 

Name	Type	Default	Description
Align	Integer	wxListAlign.DEFAULT

Arranges the items in icon or small icon view. (Windows only) See wxListAlign

clearAll

clearAll()
 

Deletes all items and columns.

create

create(Parent, 
       Id, 
       Position = wxDefaultPosition, 
       Size = wxDefaultSize, 
       Style = wxListCtrl.ICON, 
       Validator = null) : Boolean
 

Name	Type	Default	Description
Parent	wxWindow		The parent of wxListCtrl. Can't be null.
Id	Integer		An window identifier. Use -1 when you don't need it.
Position	wxPoint	wxDefaultPosition	The position of the ListCtrl control on the given parent.
Size	wxSize	wxDefaultSize	The size of the ListCtrl control.
Style	Integer	wxListCtrl.ICON	The wxListCtrl style.
Validator	wxValidator	null	Validator.

Constructs a new wxListCtrl object.

deleteAllColumns

deleteAllColumns() : Boolean
 

Deletes all columns. Returns true on success.

deleteAllItems

deleteAllItems() : Boolean
 

Deletes all items. Returns true on success.

deleteColumn

deleteColumn(Col) : Boolean
 

Name	Type	Default	Description
Col	Integer		The column index.

Deletes the column. Returns true on success.

deleteItem

deleteItem(Item) : Boolean
 

Name	Type	Default	Description
Item	Integer		The item index.

Deletes the item. Returns true on success.

editLabel

editLabel(Item) : wxTextCtrl
 

Name	Type	Default	Description
Item	Integer		The item index.

Edit the label. The text control is returned (on Windows).

endEditLabel

endEditLabel(Cancel) : Boolean
 

Name	Type	Default	Description
Cancel	Boolean		Cancel the edit, or commit the changes.

Ends editing the label. When Cancel is true, the label is left unchanged. Windows only

ensureVisible

ensureVisible(Item) : Boolean
 

Name	Type	Default	Description
Item	Integer		The item index.

Makes sure the item is visible. Returns true on success.

findItem

findItem(Start, 
         Str, 
         Partial = false) : Integer
 

Name	Type	Default	Description
Start	Integer		The item to start the search or -1 to start from the beginning.
Str	String		The label to search
Partial	Boolean	false	The label must be exactly the same or may start with Str. Default is false.

findItem(Start, 
         Data) : Integer
 

Name	Type	Default	Description
Start	Integer		The item to start the search or -1 to start from the beginning.
Data	Integer		The associated data of an item.

findItem(Start, 
         Pos, 
         Direction) : Integer
 

Name	Type	Default	Description
Start	Integer		The item to start the search or -1 to start from the beginning.
Pos	wxPoint		Find an item near this position.
Direction	Integer		The direction of the search. See wxListFind.

1. Find an item whose label matches the string exact or partial.
2. Find an item with the given associated data.
3. Find an item nearest the position in the specified direction.

The search starts from the given item, or at the beginning when start is -1.

getColumn

getColumn(Col, 
          Item) : wxListItem
 

Name	Type	Default	Description
Col	Integer		The column number
Item	Integer		The item index

getColumn(Col, 
          ListItem) : Boolean
 

Name	Type	Default	Description
Col	Integer		The column number
ListItem	wxListItem		The item info. Make sure that the id property is set.

Gets the column information. The first form returns a wxListItem object or undefined when the column is not found. The second form returns true when the column is found and puts the column information in the second argument.

getColumnWidth

getColumnWidth(Col) : Integer
 

Name	Type	Default	Description
Col	Integer		The column number

Returns the width of the column.

getImageList

getImageList(Which) : wxImageList
 

Name	Type	Default	Description
Which	Integer		Type of the imagelist.

Returns the associated imagelist.

getItemData

getItemData(Item) : Any
 

Name	Type	Default	Description
Item	Integer		The item index.

Returns the associated data of the item. The type of the data can be any type: integer, long, object, ...

getItemPosition

getItemPosition(Item) : wxPoint
 

Name	Type	Default	Description
Item	Integer		The item index.

Returns the position of the item in icon or small icon view. Returns undefined on failure.

getItemRect

getItemRect(Item, 
            Code) : wxRect
 

Name	Type	Default	Description
Item	Integer		The item index.
Code	Integer		Indicates which rectangle to return.

Returns the item rectangle. See wxListRect.

getItemSpacing

getItemSpacing(IsSmall) : Integer
 

Name	Type	Default	Description
IsSmall	Boolean		When true, the item spacing for small icon view is returned. Otherwise the item spacing for large icon view is returned.

Returns the item spacing used in icon view.

getItemState

getItemState(Item, 
             StateMask) : Integer
 

Name	Type	Default	Description
Item	Integer		The item index
StateMask	Integer		Indicates which state flags are valid.

Gets the item state. See wxListState.

getItemText

getItemText(Item) : String
 

Name	Type	Default	Description
Item	Integer		The item index.

Returns the text of the item.

getNextItem

getNextItem(Item, 
            Geometry = wxListNext.ALL, 
            State = wxListState.DONTCARE) : Integer
 

Name	Type	Default	Description
Item	Integer		The start item. Use -1 to start from the beginning.
Geometry	Integer	wxListNext.ALL	Search direction. Use one of the constants defined in wxListNext.
State	Integer	wxListState.DONTCARE	A state. Use one of the constants defined in wxListState.

Searches for an item with the given goemetry 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.
The following example iterates all selected items:

    var item = -1;
    do
    {
      item = listctrl.getNextItem(item, wxListNext.ALL, wxListState.SELECTED);
    } 
    while(item != -1);
   

hitTest

hitTest(Pos) : Array
 

Name	Type	Default	Description
Pos	wxPoint		The position to test.

Determines which item (if any) is at the specified point. This method returns multiple values. Use it as follows:

   var item;
   var flags;
   [item, flags] = list.hitTest(new wxPoint(1, 1));

insertColumn

insertColumn(Col, 
             ListItem) : Integer
 

Name	Type	Default	Description
Col	Integer		A column index
ListItem	wxListItem		The item

insertColumn(Col, 
             Heading, 
             Format = wxListFormat.LEFT, 
             Width = -1) : Integer
 

Name	Type	Default	Description
Col	Integer		A column index
Heading	String		The name for the header.
Format	Integer	wxListFormat.LEFT	The format of the header. Use one of the constants of wxListColumnFormat.
Width	Integer	-1	The width of the column.

Inserts a column. On success, the index of the new column is returned. On failure, -1 is returned.

insertItem

insertItem(ListItem) : Integer
 

Name	Type	Default	Description
ListItem	wxListItem		Item information

insertItem(Item, 
           Label, 
           ImageIdx = -1) : Integer
 

Name	Type	Default	Description
Item	Integer		The item index.
Label	String		Label of the item
ImageIdx	Integer	-1	The index of the image in the associated imagelist

insertItem(Item, 
           ImageIdx) : Integer
 

Name	Type	Default	Description
Item	Integer		The item index.
ImageIdx	Integer		The index of the image in the associated imagelist.

Inserts an item. On success, the index of the new item is returned. On failure, -1 is returned.

refreshItem

refreshItem(Item)
 

Name	Type	Default	Description
Item	Integer		The item index.

Refreshes the item. Only useful for virtual list controls.

refreshItems

refreshItems(From, 
             To)
 

Name	Type	Default	Description
From	Integer		The item index to start from.
To	Integer		The item index of the last item to refresh.

Refreshes a range of items. Only useful for virtual list controls.

scrollList

scrollList(X, 
           Y) : Boolean
 

Name	Type	Default	Description
X	Integer
Y	Integer

Scrolls the list control. If in icon, small icon or report view mode, X specifies the number of pixels to scroll. If in list view mode, X specifies the number of columns to scroll. If in icon, small icon or list view mode, Y specifies the number of pixels to scroll. If in report view mode, Y specifies the number of lines to scroll.

setColumn

setColumn(Col, 
          Item) : wxListItem
 

Name	Type	Default	Description
Col	Integer		The column number
Item	Integer		The item index

setColumn(Col, 
          ListItem) : Boolean
 

Name	Type	Default	Description
Col	Integer		The column number
ListItem	wxListItem		The item info. Make sure that the id property is set.

Sets the column information. False is returned when the column doesn't exist.

setColumnWidth

setColumnWidth(Col, 
               Width) : Boolean
 

Name	Type	Default	Description
Col	Integer		The column number. In small or normal icon view, col must be -1, and the column width is set for all columns.
Width	Integer		Width can be the width in pixels, AUTOSIZE or AUTOSIZE_USEHEADER. AUTOSIZE will resize the column to the length of the longest item. AUTOSIZE_USEHEADER will resize the column to the length of the header (on windows) or on 80 pixels (other platforms).

Sets the columnwidth. Returns true on success, false on failure. See autosize.

setImageList

setImageList(ImageList, 
             Which)
 

Name	Type	Default	Description
ImageList	wxImageList
Which	Integer		Type of the imagelist.

Sets the imagelist associated with the control.

setItem

setItem(ListItem) : Boolean
 

Name	Type	Default	Description
ListItem	wxListItem		The item info

setItem(Item, 
        Col, 
        Label, 
        ImageId = -1) : Integer
 

Name	Type	Default	Description
Item	Integer		The item index
Col	Integer		The column index
Label	String		The text of the item
ImageId	Integer	-1	The zero-base index of an image list.

Sets the item information. On success, true is returned.

setItemData

setItemData(Item, 
            Data) : Boolean
 

Name	Type	Default	Description
Item	Integer		The item index.
Data	Any		The associated data.

Sets the associated data of an item. The type of the data can be any type: integer, long, object, ... When the listcontrol is sortable, the item data must be set.

setItemImage

setItemImage(Item, 
             Image, 
             SelImage) : Boolean
 

Name	Type	Default	Description
Item	Integer		The item index.
Image	Integer		Index of the image to show for unselected items.
SelImage	Integer		Index of the image to show for selected items.

Sets the unselected and selected images associated with the item. The images are indices into the image list associated with the list control.

setItemPosition

setItemPosition(Item, 
                Pos) : Boolean
 

Name	Type	Default	Description
Item	Integer		The item index.
Pos	wxPoint		The new position

Sets the item position in icon or small icon view. Returns true on success.

setItemState

setItemState(Item, 
             State, 
             StateMask) : Boolean
 

Name	Type	Default	Description
Item	Integer		The item index.
State	Integer		The new state.
StateMask	Integer		Indicates which state flags are valid.

Sets the new state of an item. See wxListState.

setItemText

setItemText(Item, 
            Text)
 

Name	Type	Default	Description
Item	Integer		The item index.
Text	String		The new text.

Sets the text of an item.

setSingleStyle

setSingleStyle(Style, 
               Add = true)
 

Name	Type	Default	Description
Style	Integer		A window style.
Add	Boolean	true	When true (= default), the style is added. Otherwise the style is removed.

Adds or removes a single window style.

sortItems

sortItems(SortFn, 
          Data = 0) : Boolean
 

Name	Type	Default	Description
SortFn	Function		A function which receives 3 arguments. The first argument is the associated data of the first item. The second argument is the associated data of the second item. The third arugment is the Data argument you specify with this method. The third argument may be omitted when you don't use it. The return value is an integer value. Return 0 when the items are equal, a negative value if the first item is less then the second item and a positive value when the first item is greater then the second item.
Data	Integer	0	A value passed as the third argument of the sort function. When not passed, 0 is used.

Call this method to sort the items in the list control. Sorting is done using the specified SortFn.
Remark: Notice that the control may only be sorted on client data associated with the items, so you must use setItemData if you want to be able to sort the items in the control.

Events

onBeginDrag	This event is triggered when the user starts dragging with the left mouse button. The function receives a wxListEvent.
onBeginRDrag	This event is triggered when the user starts dragging with the right mouse button. The function receives a wxListEvent.
onBeginLabelEdit	This event is triggered when the user starts editing the label. This event can be prevented by setting veto to true. The function receives a wxListEvent.
onEndLabelEdit	This event is triggered when the user ends editing the label. This event can be prevented by setting veto to true. The function receives a wxListEvent.
onDeleteItem	This event is triggered when an item is deleted. The function receives a wxListEvent.
onDeleteAllItems	This event is triggered when all items are deleted. The function receives a wxListEvent.
onItemSelected	This event is triggered when the user selects an item. The function receives a wxListEvent.
onItemDeselected	This event is triggered when the user deselects an item. The function receives a wxListEvent.
onItemActivated	This event is triggered when the user activates an item by pressing Enter or double clicking. The function receives a wxListEvent.
onItemFocused	This event is triggered when the currently focused item changes. The function receives a wxListEvent.
onItemRightClick	This event is triggered when the user starts right clicks an item. The function receives a wxListEvent.
onListKeyDown	This event is triggered when a key is pressed. The function receives a wxListEvent.
onInsertItem	This event is triggered when an item is inserted. The function receives a wxListEvent.
onColClick	This event is triggered when the user left-clicks a column. The function receives a wxListEvent.
onColRightClick	This event is triggered when the user right-clicks a column. The function receives a wxListEvent.
onColBeginDrag	This event is triggered when the user starts resizing a column. The function receives a wxListEvent.
onColDragging	This event is triggered when the divider between two columns is dragged. The function receives a wxListEvent. This event is triggered when a column is resized. The function receives a wxListEvent.
onColEndDrag
onCacheHint	This event is triggered so that the application can prepare a cache for a virtual list control. The function receives a wxListEvent.