Developer Resources

ListView

Overview

The ListView class represents a list view control.

Base Class

FormControl

Constructor

ListView(x_pos : Integer, y_pos : Integer, width : Integer, height : Integer)

Arguments

x_pos
The x position of the control.
y_pos
The y position of the control.
width
The width of the control.
height
The height of the control.

Events

ListView.columnClick
Fired when a column is left-clicked.
ListView.columnRightClick
Fired when a column is right-clicked.
ListView.itemActivate
Fired when a list item is activated.
ListView.itemBeginLabelEdit
Fired at the beginning of a list item label edit.
ListView.itemEndLabelEdit
Fired at the end of a list item label edit.
ListView.itemRightClick
Fired when a list item is right-clicked.
ListView.itemSelect
Fired when a list item is selected.
ListView.keyDown
Fired when a key is pressed.

Properties

ListView.LargeIcon
A flag representing that the ListView should be created in large icon mode.
ListView.SmallIcon
A flag representing that the ListView should be created in small icon mode.
ListView.Details
A flag representing that the ListView should be created in details mode (single or multiple column list with column headers).
ListView.List
A flag representing that the ListView should be created in list mode (single or multiple column list without column headers).
ListView.AlignLeft
A flag representing that a column in the ListView should be left-aligned (ListView.Details and ListView.List modes only).
ListView.AlignCenter
A flag representing that a column in the ListView should be center-aligned (ListView.Details and ListView.List modes only).
ListView.AlignRight
A flag representing that a column in the ListView should be right-aligned (ListView.Details and ListView.List modes only).

Methods

ListView.addColumn
Adds a column to the ListView
ListView.addItem
Adds a ListViewItem to the ListView.
ListView.clear
Deletes all items from a list view control
ListView.deleteColumn
Deletes a column from the ListView
ListView.deleteItem
Deletes a list view item
ListView.deselectAllItems
Deselects all the items in the list view control
ListView.deselectItem
Deselects the specified list view item
ListView.findItem
Finds an item with the specified text.
ListView.getItem
Retrieves a list view item
ListView.getItemCount
Returns the number of items in the list view
ListView.getItems
Returns all ListViewItem objects in the list view control
ListView.getLabelEdit
Returns whether the item labels may be edited
ListView.getSelectedIndex
Gets the index of the selected item in the listbox.
ListView.getSelectedItem
Returns the first selected ListViewItem object after the specified index in the list view control
ListView.getSelectedItems
Returns the selected ListViewItem objects in the list view control
ListView.getView
Returns the current view mode of the list view control.
ListView.insertItem
Inserts a ListViewItem into the ListView.
ListView.isItemSelected
Indicates whether or not the specified ListViewItem object is selected
ListView.selectItem
Selects the specified list view item
ListView.setLabelEdit
Sets whether the item labels may be edited
ListView.setView
Sets the view mode of the list view control
ListView.sortItems
Sorts the items in the list view control

Inherited Methods

FormControl.captureMouse
Captures the mouse on this form control.
FormControl.disablePaint
Disables the window from redrawing itself.
FormControl.enablePaint
Enables the window to redraw itself.
FormControl.getBackgroundColor
Gets the background color of the form control.
FormControl.getClientSize
Gets the client size of the form control.
FormControl.getEnabled
Indicates whether or not a form control is enabled.
FormControl.getFont
Gets the default font for the text of form control.
FormControl.getForegroundColor
Gets the foreground color of the form control.
FormControl.getMaxSize
Gets the maximum size of the form control.
FormControl.getMinSize
Gets the minimum size of the form control.
FormControl.getMousePosition
Gets the mouse position relative to this form control.
FormControl.getNativeHandle
Gets the native handle of the window/control
FormControl.getPosition
Gets the position of a form control.
FormControl.getSize
Gets the size of the form control.
FormControl.invalidate
Invalidates a form control, which will cause it to be repainted on the next paint event.
FormControl.refresh
Refreshes a form control, which immediately repaints the entire form control.
FormControl.releaseMouse
Releases the mouse from being captured on this form control.
FormControl.setBackgroundColor
Sets the background color of the form control.
FormControl.setClientSize
Sets the client size of a form control.
FormControl.setEnabled
Enables or disables the form control.
FormControl.setFocus
Sets the focus to the form control.
FormControl.setFont
Sets the default font for the text of the form control.
FormControl.setForegroundColor
Sets the foreground color of the form control.
FormControl.setMaxSize
Sets the maximum size of a form control.
FormControl.setMinSize
Sets the minimum size of a form control.
FormControl.setPosition
Sets the position of a form control relative to the the form control's parent.
FormControl.setSize
Sets the size of a form control.
FormControl.show
Shows or hides the form control.
FormControl.update
Updates a form control, which will immediately repaint any invalid areas.

Example

class MyForm extends Form
{
    var m_list;
    var m_text;
    
    var m_last_sort_order;
    var m_last_sort_column;
    
    function MyForm()
    {
        super("ListView Test", 100, 100, 700, 520);
        setMinSize(500, 360);
        
        // create list view and add some columns        
        m_list = new ListView;
        m_list.setView(ListView.Details);
        m_list.addColumn("Test Column", 200, ListView.AlignLeft);
        m_list.addColumn("Test Column 2", 200, ListView.AlignLeft);
        m_list.addColumn("Test Column 3", 200, ListView.AlignLeft);
        this.add(m_list);
        
        // add some items
        var folder_bitmap = getFolderBitmap();
        m_list.addItem(new ListViewItem("Finch", folder_bitmap));
        m_list.addItem(new ListViewItem("Bluebird", folder_bitmap));
        m_list.addItem(new ListViewItem("Goose", folder_bitmap));
        m_list.addItem(new ListViewItem("Sparrow", folder_bitmap));
        m_list.addItem(new ListViewItem("Hummingbird", folder_bitmap));
        m_list.addItem(new ListViewItem("Duck", folder_bitmap));
        
        // connect events
        m_list.keyDown.connect(this, onKeyDown);
        m_list.itemSelect.connect(this, onItemSelect);
        m_list.itemActivate.connect(this, onItemActivate);
        m_list.itemRightClick.connect(this, onItemRightClick);
        m_list.itemBeginLabelEdit.connect(this, onItemBeginLabelEdit);
        m_list.itemEndLabelEdit.connect(this, onItemEndLabelEdit);
        m_list.columnClick.connect(this, onColumnClick);
        m_list.columnRightClick.connect(this, onColumnRightClick);
               
        // text box for event output
        m_text = new TextBox("", 0, 0, 140, 140);
        m_text.setMultiline();

        // -- some extra buttons --
        
        var additem_button = new Button("Add Item");
        additem_button.click.connect(this, onAddItem);
        
        var changeitem_button = new Button("Change Item");
        changeitem_button.click.connect(this, onChangeItem);
      
        var deleteitem_button = new Button("Delete Item");
        deleteitem_button.click.connect(this, onDeleteItem);
        
        var deleteall_button = new Button("Delete All");
        deleteall_button.click.connect(this, onDeleteAll);
        
        var exit_button = new Button("Exit");
        exit_button.click.connect(this, onExit);
        
        // these variables save the last sort order
        m_last_sort_order = false;
        m_last_sort_column = -1;
        
        // -- create button layout --
        var button_layout = new BoxLayout(Layout.Horizontal);
        button_layout.add(additem_button);
        button_layout.addSpacer(8);
        button_layout.add(changeitem_button);
        button_layout.addSpacer(8);
        button_layout.add(deleteitem_button);
        button_layout.addSpacer(8);
        button_layout.add(deleteall_button);
        button_layout.addStretchSpacer();
        button_layout.add(exit_button);
        
        // -- create main layout --
        var main_layout = new BoxLayout(Layout.Vertical);
        main_layout.addSpacer(8);
        main_layout.add(m_list, 1, Layout.Expand | Layout.Left | Layout.Right, 8);
        main_layout.addSpacer(8);
        main_layout.add(m_text, 0, Layout.Expand | Layout.Left | Layout.Right, 8);
        main_layout.addSpacer(8);
        main_layout.add(button_layout, 0, Layout.Expand | Layout.Left | Layout.Right, 8);
        main_layout.addSpacer(8);
        
        setLayout(main_layout);
    }
    
    function onColumnClick(sender, event_args)
    {
        var column_to_sort = event_args.index;
        var sort_order;
        
        if (column_to_sort == m_last_sort_column)
        {
            sort_order = m_last_sort_order ? false : true;
        }
         else
        {
            sort_order = true; // ascending
        }
        
        m_list.sortItems(column_to_sort, sort_order);
        
        m_last_sort_order = sort_order;
        m_last_sort_column = column_to_sort;
    }
    
    function onColumnRightClick(sender, event_args)
    {
        addLogLine("Column right clicked; index = " + event_args.index);
        
        var sortasc_item = new MenuItem("Sort Ascending");
        var sortdec_item = new MenuItem("Sort Descending");
        var deletecol_item = new MenuItem("Delete Column");
        
        sortasc_item.index = event_args.index;
        sortasc_item.sort_order = true;
        sortasc_item.click.connect(this, onDoColumnSort);
        
        sortasc_item.index = event_args.index;
        sortdec_item.sort_order = false;
        sortdec_item.click.connect(this, onDoColumnSort);
        
        deletecol_item.index = event_args.index;
        deletecol_item.click.connect(this, onDoColumnDelete);
        
        var menu = new Menu;
        menu.add(sortasc_item);
        menu.add(sortdec_item);
        menu.addSeparator();
        menu.add(deletecol_item);
        
        menu.popup(m_list);
    }
    
    function onDoColumnSort(sender, event_args)
    {
        m_list.sortItems(sender.index, sender.sort_order);
    }
    
    function onDoColumnDelete(sender, event_args)
    {
        m_list.deleteColumn(sender.index);
    }
    
    function onKeyDown(sender, event_args)
    {
        addLogLine("Key down; Char code = " + event_args.keyCode + 
                    " shiftDown(" + event_args.shiftDown + ")" +
                    " controlDown(" + event_args.controlDown + ")" +
                    " altDown(" + event_args.altDown + ")");
        
        // handle user pressing Del key
        if (event_args.keyCode == 127)
        {
            m_list.deleteItem(event_args.index);
        }
    }
    
    function onItemSelect(sender, event_args)
    {
        addLogLine("Item selected; index = " + event_args.index);
    }
    
    function onItemActivate(sender, event_args)
    {
        addLogLine("Item activated; index = " + event_args.index);
    }
    
    function onItemRightClick(sender, event_args)
    {
        addLogLine("Item right clicked; index = " + event_args.index);
        
        var menu_item1 = new MenuItem("Test Menu Item 1");
        var menu_item2 = new MenuItem("Test Menu Item 2");
        var menu_item3 = new MenuItem("Delete Listview Item");
        
        menu_item3.item_number = event_args.index;
        menu_item3.click.connect(this, onRightClickDelete);
        
        var menu = new Menu;
        menu.add(menu_item1);
        menu.add(menu_item2);
        menu.addSeparator();
        menu.add(menu_item3);
        
        menu.popup(m_list);
    }
    
    function onRightClickDelete(sender, event_args)
    {
        m_list.deleteItem(sender.item_number);
    }
    
    function onItemBeginLabelEdit(sender, event_args)
    {
        addLogLine("Begin label edit; index = " + event_args.index);
    }
    
    function onItemEndLabelEdit(sender, event_args)
    {
        addLogLine("End label edit; index = " + event_args.index);
    }
    
    function onAddItem(sender, event_args)
    {
        var folder_bitmap = getFolderBitmap();
        m_list.addItem(new ListViewItem("Test Item " + (m_list.getItemCount()+1),
                                        folder_bitmap));
    }
    
    function onDeleteItem(sender, event_args)
    {
        var items = m_list.getSelectedItems();
        for (var i in items)
        {
            m_list.deleteItem(items[i]);
        }
    }
    
    function onChangeItem(sender, event_args)
    {
        var items = m_list.getSelectedItems();
        var counter = 0;
        for (var i in items)
        {
            counter++;
            items[i].setText(items[i].getText() + " Changed Text");
            items[i].setColumnText(1, "Hello " + counter);
            items[i].setColumnText(2, "Hello " + counter);
        } 
    }
    
    function onDeleteAll(sender, event_args)
    {
        m_list.clear();
    }
    
    function addLogLine(s)
    {
        var date = new Date();
        
        var text = m_text.getText();
        text += date.toString() + " - " + s;
        text += "\n";
        m_text.setText(text);
    }

    function onExit()
    {
        Application.exit();
    }
};




var form = new MyForm;
form.show();
Application.run();




var g_folder_bitmap;

function getFolderBitmap()
{
    if (g_folder_bitmap)
        return g_folder_bitmap;
    
    g_folder_bitmap = new Bitmap('
        "16 16 6 1",
        "  c None",
        "! c #000000",
        "# c #808080",
        "$ c #C0C0C0",
        "% c #FFFF00",
        "& c #FFFFFF",
        "                ",
        "                ",
        "  #####         ",
        " #%$%$%#        ",
        "#%$%$%$%######  ",
        "#&&&&&&&&&&&&#! ",
        "#&%$%$%$%$%$%#! ",
        "#&$%$%$%$%$%$#! ",
        "#&%$%$%$%$%$%#! ",
        "#&$%$%$%$%$%$#! ",
        "#&%$%$%$%$%$%#! ",
        "#&$%$%$%$%$%$#! ",
        "#&%$%$%$%$%$%#! ",
        "##############! ",
        " !!!!!!!!!!!!!! ",
        "                "');
    
    return g_folder_bitmap;
}

ListView.addColumn

function ListView.addColumn(caption : String, width : Integer, alignment : AlignmentEnum)

Arguments

caption
The column caption
width
The width of the column in pixels
alignment
The column alignment (ListView.AlignLeft, ListView.AlignCenter, or ListView.AlignRight)

Returns

True if the column was properly added, false otherwise

Description

Adds a column to the list view control. The list view must be in Details mode in order for the column to be displayed. See setView() for more information.

ListView.addItem

function ListView.addItem(item : ListViewItem)

Arguments

item
The ListViewItem item to add to the ListView.

Description

Adds a ListViewItem item to the ListView.

ListView.clear

function ListView.clear()

Description

Deletes all list view items from the control, clearing it out. Columns are not removed.

ListView.deleteColumn

function ListView.deleteColumn(column_index : Integer)

Arguments

column_index
The zero-based column to delete.

Returns

True if the column was properly added, false otherwise

Description

Deletes a column from the list view control.

ListView.deleteItem

function ListView.deleteItem(item : ListViewItem)
function ListView.deleteItem(item_index : Integer)

Arguments

item
A list view item object
item_index
The zero-based index of the item to delete

Returns

True if the item was properly deleted, false otherwise

Description

Deletes an item from the list view. Either an item index or a list view item object may be specified in the parameter.

ListView.deselectAllItems

function ListView.deselectAllItems()

Description

Deselects all the items in the list view control

ListView.deselectItem

function ListView.deselectItem(item : ListViewItem)
function ListView.deselectItem(item_index : Integer)

Arguments

item
The list view item object to deselect
item_index
The zero-based index of the item to deselect

Description

Deselects the specified item or the item at the specified index.

ListView.findItem

function ListView.findItem(text : String, index : Integer) : ListViewItem

Arguments

text
The text of the item to find.
index
(Optional) The zero-based index of the item to start at. If this parameter is left blank or is -1, the find operation will always start with the first item in the ListView.

Returns

Returns the ListViewItem if it's found, and null if the item can't be found.

Description

Finds an item with the specified text and returns the ListViewItem that was found. If a ListViewItem with the specified text can't be found, the function returns null.

ListView.getItem

function ListView.getItem(item_index : Integer) : ListViewItem

Arguments

item_index
The zero-based index of the item to retrieve

Returns

A ListViewItem object. If the call failed, null is returned.

Description

Retrieves an item from the list view. In the parameter, either an item index or a list view item object may be specified.

ListView.getItemCount

function ListView.getItemCount() : Integer

Returns

The number of items in the list view control

Description

Returns the number of items in the list view control

ListView.getItems

function ListView.getItems() : Array(ListViewItem)

Returns

An Array of ListViewItem objects

Description

Returns an Array object containing all ListViewItem objects in the list view control

ListView.getLabelEdit

function ListView.getLabelEdit() : Boolean

Returns

true if item labels may be edited by the user, false otherwise

Description

Returns a boolean value indicated whether the list view item labels may be edited

ListView.getSelectedIndex

function ListView.getSelectedIndex(index : Integer) : Integer

Arguments

index
(Optional) The zero-based index of the item to start at. If this parameter is left blank or is -1, the find operation will always start with the first item in the list view control.

Returns

Returns the zero-based index of the first selected ListViewItem object in the list view control after the start index. If there are no selected items, the function returns -1.

Description

Returns the zero-based index of the first selected ListViewItem object in the list view control after the start index. If there are no selected items, the function returns -1.

ListView.getSelectedItem

function ListView.getSelectedItem(index : Integer) : ListViewItem

Arguments

index
(Optional) The zero-based index of the item to start at. If this parameter is left blank or is -1, the find operation will always start with the first item in the list view control.

Returns

A ListViewItem object, or null if no items are selected in the list view.

Description

Returns the first selected ListViewItem object in the list view control. If no objects are selected in the list view control, null is returned.

ListView.getSelectedItems

function ListView.getSelectedItems() : Array(ListViewItem)

Returns

An Array of ListViewItem objects

Description

Returns an Array object containing all selected ListViewItem objects in the list view control. If no objects are selected in the list view control, an empty array is returned.

ListView.getView

function ListView.getView() : ListViewModeEnum

Returns

One of the following values: ListView.LargeIcon, ListView.SmallIcon, ListView.Details, or ListView.List

Description

Returns the current view mode of the list view control. See setView() for more information.

ListView.insertItem

function ListView.insertItem(item : ListViewItem, index : Integer)

Arguments

item
The ListViewItem item to insert into the ListView.
index
The position of the new item.

Description

Inserts a ListViewItem item into the ListView at the specified position.

ListView.isItemSelected

function ListView.isItemSelected(item : ListViewItem) : Boolean

Arguments

index
The item that is being checked for selection.

Returns

Returns true if the item is selected, and false otherwise. If an error is encountered during the call, null is returned.

Description

Indicates whether or not the specified item is selected. If the item is selected, the function returns true. If the item is not selected, the function returns false.

ListView.selectItem

function ListView.selectItem(item : ListViewItem)
function ListView.selectItem(item_index : Integer)

Arguments

item
The list view item object to select
item_index
The zero-based index of the item to select

Description

Selects the specified item or the item at the specified index.

ListView.setLabelEdit

function ListView.setLabelEdit(allow_label_edit : Boolean)

Description

Invoking setLabelEdit allows the caller to determine whether label edits are generally allowed in the list view control. Passing true to the allow_label_edit parameter effectively makes the control read-only from the user's perspective.

ListView.setView

function ListView.setView(mode : ListViewModeEnum) : Boolean

Arguments

mode
One of the following values: ListView.LargeIcon, ListView.SmallIcon, ListView.Details, or ListView.List

Returns

True if the view mode was successfully set, false otherwise

Description

List view controls have several view modes which allow data to be represented in various ways on the screen. The modes are ListView.LargeIcon, ListView.SmallIcon, ListView.Details, and ListView.List. The ListView.LargeIcon and ListView.SmallIcon modes allow items with various icon sizes to be viewed in a window. The ListView.Details and ListView.List modes allow items to be viewed as a list, along with extra columns to displayed next to the main item. The ListView.Details mode, in contrast with the ListView.List mode, has column headers. To use the ListView.Details or ListView.List mode, the caller must first add columns to the control.

ListView.sortItems

function ListView.sortItems(column_index : Integer, ascending : Boolean)

Arguments

column_index
The zero-based column index used as a basis for the sort operation
ascending
(Optional) Specifying true directs the operation to sort the control ascending, false descending.

Description

Sorts the items in the list view. The column_index parameter specifies the column index to use in the sort. The second parameter, which is optional, specifies the sort order. If this parameter is not specified, an ascending sort order is assumed.