/*******************************************************************************

 * Copyright (c) 2004, 2008 Nokia Corporation and/or its subsidiary(-ies).

 * All rights reserved. This program and the accompanying materials 

 * are made available under the terms of the Eclipse Public License v1.0

 * which accompanies this distribution, and is available at

 * http://www.eclipse.org/legal/epl-v10.html

 * 

 * Contributors:

 *     Yu You (Nokia Corp.)- initial API specification 

 *     Nokia Corporation - S60 implementation

 *     Nokia Corporation - QT implementation

 *******************************************************************************/

package org.eclipse.ercp.swt.mobile;

import java.util.Vector;

import org.eclipse.swt.SWT;

import org.eclipse.swt.events.SelectionListener;

import org.eclipse.swt.graphics.Font;

import org.eclipse.swt.graphics.Image;

import org.eclipse.swt.graphics.Point;

import org.eclipse.swt.graphics.Rectangle;

import org.eclipse.swt.internal.qt.ListUtils;

import org.eclipse.swt.internal.qt.OS;

import org.eclipse.swt.internal.qt.PackageProxy;

import org.eclipse.swt.internal.qt.WidgetState;

import org.eclipse.swt.widgets.Composite;

import org.eclipse.swt.widgets.Internal_PackageSupport;

import org.eclipse.swt.widgets.Scrollable;

import org.eclipse.swt.widgets.TypedListener;

/**

 * 

 * A widget that allows the user to select one or more items from a collection

 * of items that can be displayed in a multi-column way with different styles.

 * 

 * <p>

 * ListView lays out its children items in one or more columns from top to

 * bottom. If a layout orientation hint is not specified, the implementation

 * chooses the orientation. If there is only enough screen width for one column,

 * the list scrolls vertically. If there is room to display multiple columns

 * within the widget, then the list scrolls horizontally. The list never scrolls

 * in more than one direction. The layout orientation may be set at runtime by

 * calling method <code>setLayout(int)</code>.

 * <p>

 * The item density hint determines the size and positioning of items in order

 * to fit more or less within the widget. Applications can query the preferred

 * sizes of the icons for each density level. Note that the sizes may be diverse

 * in different platforms. When the given icons do not match the prefered size,

 * the implementation may adjust icon sizes without throwing any exception.

 * Applications can change the item density level at runtime by calling method

 * <code>setLayoutDensity(int)</code>. Some platforms may use context-sensitive

 * device keys to allow the user to change the ListView's density level at

 * run-time. For example, by activating "zoom in/out" device keys when the

 * ListView is focused.

 * <p>

 * Applications can query the current layout and density values by calling the

 * corresponding "get" methods.

 * 

 * <dl>

 * <dt><b>SWT styles: </b></dt>

 * <dd>SINGLE, MULTI: single or multiple selection</dd>

 * <dd>VERTICAL, HORIZONTAL: defines the layout orientation</dd>

 * <dt><b>ListView density levels: </b></dt>

 * <dd>HIGH, MEDIUM (default), LOW: defines the item density levels that

 * determine the numbers of visible list items per screen</dd>

 * <dt><b>Events: </b></dt>

 * <dd>Selection, DefaultSelection</dd>

 * </dl>

 * <p>

 * Note: If styles not applicable to ListView are specified, they are ignored.

 * </p>

 * <p>

 * Note: ListView is a subclass of Scrollable. Changing the scrollbar values (

 * <code>ScrollBar.setSelection(int)</code>) will affect the scrolling position

 * of the ListView control. However, changing the range of scrollbars, such as

 * <code>setMaximum(int)</code> and <code>setMinimum(int)</code>, will not

 * affect the ListView at all.

 * </p>

 * <p>

 * IMPORTANT: This class is <em>not</em> intended to be subclassed.

 * </p>

 */

public class ListView extends Scrollable {

private Vector icons = new Vector();

private int density;

private int spacing;

private boolean ignoreSelectionEvent;

/**

 * A low density level.

 * 

 * <P>

 * Value <code>1</code> is assigned to <code>LOW</code>.

 * </P>

 * 

 */

public static final int LOW = 1;

/**

 * A medium density level.

 * 

 * <P>

 * Value <code>2</code> is assigned to <code>MEDIUM</code>.

 * </P>

 * 

 */

public static final int MEDIUM = 2;

/**

 * A high density level.

 * <P>

 * Value <code>3</code> is assigned to <code>HIGH</code>.

 * </P>

 * </DL>

 * 

 */

public static final int HIGH = 3;

static final class ListViewPackageProxy extends PackageProxy {

    public void createHandle(int index) {

        ((ListView)w).createHandle(index);

    }

    public void hookEvents() {

        ((ListView)w).hookEvents();

    }

    public void qt_signal_list_itemDoubleClicked(int selectionHandle) {

        ((ListView)w).qt_signal_list_itemDoubleClicked(selectionHandle);

    }

    public void qt_signal_list_itemSelectionChanged() {

        ((ListView)w).qt_signal_list_itemSelectionChanged();

    }

    public void setTraversalFlags(int type, int key, int modifier, int character) {

        ((ListView)w).setTraversalFlags(type, key, modifier, character);

    }

    public Point getPreferredClientAreaSize() {

        return ((ListView)w).getPreferredClientAreaSize();

    }

}

/**

 * Constructs a new instance of this class given its parent and a style

 * value describing its behavior and appearance.

 * <p>

 * The style value is either one of the style constants defined in class

 * <code>SWT</code> which is applicable to instances of this class, or must

 * be built by <em>bitwise OR</em> 'ing together (that is, using the

 * <code>int</code> "|" operator) two or more of those <code>SWT</code>

 * style constants. The class description lists the style constants that are

 * applicable to the class. Style bits are also inherited from superclasses.

 * </p>

 * 

 * @param parent

 *            a widget which will be the parent of the new instance (cannot

 *            be null)

 * @param style

 *            the style value of the widget to construct. See <a

 *            href="#description">Description </a> for details.

 * 

 * @exception IllegalArgumentException

 *                <ul>

 *                <li>ERROR_NULL_ARGUMENT - if the parent is null</li>

 *                </ul>

 * @exception SWTException

 *                <ul>

 *                <li>ERROR_THREAD_INVALID_ACCESS - if not called from the

 *                thread that created the parent</li>

 *                <li>ERROR_INVALID_SUBCLASS - if this class is not an

 *                allowed subclass</li>

 *                </ul>

 * 

 * @see SWT#SINGLE

 * @see SWT#MULTI

 * @see SWT#HORIZONTAL

 * @see SWT#VERTICAL

 */

public ListView(Composite parent, int style) {

    super(parent, checkStyle(style), 0, new ListViewPackageProxy(), false);

}

/**

 * Constructs a new instance of this class given its parent and a style

 * value describing its behavior and appearance styles.

 * <p>

 * The style value is either one of the style constants defined in class

 * <code>SWT</code> which is applicable to instances of this class, or must

 * be built by <em>bitwise OR</em> 'ing together (that is, using the

 * <code>int</code> "|" operator) two or more of those <code>SWT</code>

 * style constants. The class description lists the style constants that are

 * applicable to the class. Style bits are also inherited from superclasses.

 * </p>

 * 

 * <p>

 * The density style is one of HIGH, MEDIUM and LOW.

 * </p>

 * 

 * @param parent

 *            a widget which will be the parent of the new instance (cannot

 *            be null)

 * @param style

 *            the style value of the widget to construct. See <a

 *            href="#description">Description </a> for details.

 * @param density

 *            the density style value.

 * 

 * @exception IllegalArgumentException

 *                <ul>

 *                <li>ERROR_NULL_ARGUMENT - if the parent is null</li>

 *                <li>ERROR_INVALID_ARGUMENT - if the density is invalid</li>

 *                </ul>

 * @exception SWTException

 *                <ul>

 *                <li>ERROR_THREAD_INVALID_ACCESS - if not called from the

 *                thread that created the parent</li>

 *                <li>ERROR_INVALID_SUBCLASS - if this class is not an

 *                allowed subclass</li>

 *                </ul>

 * 

 * @see SWT#SINGLE

 * @see SWT#MULTI

 * @see SWT#HORIZONTAL

 * @see SWT#VERTICAL

 * @see #HIGH

 * @see #MEDIUM

 * @see #LOW

 * @see #getLayoutDensity

 */

public ListView(Composite parent, int style, int density) {

    super(parent, style, 0, new ListViewPackageProxy(), false);

    if (density != LOW && density != MEDIUM && density != HIGH) {

        SWT.error(SWT.ERROR_INVALID_ARGUMENT);

    }

    this.density = density;

}

/**

 * Adds the string item and an optional icon to the end of the receiver's

 * list.

 * 

 * @param item

 *            the new item text

 * @param icon

 *            the icon of the item, or null.

 * 

 * @exception IllegalArgumentException

 *                <ul>

 *                <li>ERROR_NULL_ARGUMENT - if the item is null</li>

 *                </ul>

 * @exception SWTException

 *                <ul>

 *                <li>ERROR_WIDGET_DISPOSED - if the receiver has been

 *                disposed</li>

 *                <li>ERROR_THREAD_INVALID_ACCESS - if not called from the

 *                thread that created the receiver</li>

 *                </ul>

 * @exception SWTError

 *                <ul>

 *                <li>ERROR_ITEM_NOT_ADDED - if the operation fails because

 *                of an operating system failure</li>

 *                </ul>

 * 

 * @see #add(String,Image, int)

 */

public void add(String item, Image icon) {

    checkWidget();

    ListUtils.add(topHandle(), item, icon);

    icons.addElement(icon);

    resetGeometry(getItemCount() - 1);

}

/**

 * Adds the string item and an optional icon to the receiver's list at the

 * given zero-relative index.

 * <p>

 * Note: To add an item at the end of the list, use the result of calling

 * <code>getItemCount()</code> as the index or use

 * <code>add(String, Image)</code>.

 * </p>

 * 

 * @param string

 *            the new item

 * @param icon

 *            the icon part of the item, or null.

 * @param index

 *            the index for the item

 * 

 * @exception IllegalArgumentException

 *                <ul>

 *                <li>ERROR_NULL_ARGUMENT - if the string is null</li>

 *                <li>ERROR_INVALID_RANGE - if the index is not between 0

 *                and the number of elements in the list (inclusive)</li>

 *                </ul>

 * @exception SWTException

 *                <ul>

 *                <li>ERROR_WIDGET_DISPOSED - if the receiver has been

 *                disposed</li>

 *                <li>ERROR_THREAD_INVALID_ACCESS - if not called from the

 *                thread that created the receiver</li>

 *                </ul>

 * @exception SWTError

 *                <ul>

 *                <li>ERROR_ITEM_NOT_ADDED - if the operation fails because

 *                of an operating system failure</li>

 *                </ul>

 * 

 * @see #add(String, Image)

 */

public void add(String item, Image icon, int index) {

    checkWidget();

    ListUtils.add(topHandle(), item, icon, index);

    icons.insertElementAt(icon, index);

    resetGeometry(index);

}

/**

 * Adds the listener to the collection of listeners who will be notified

 * when the receiver's selection changes. The listener receives the messages

 * defined in the <code>SelectionListener</code> interface.

 * <p>

 * <code>widgetSelected</code> is called when the selection changes.

 * <code>widgetDefaultSelected</code> is typically called when an item is

 * double-clicked.

 * </p>

 * 

 * @param listener

 *            the listener which should be notified

 * 

 * @exception IllegalArgumentException

 *                <ul>

 *                <li>ERROR_NULL_ARGUMENT - if the listener is null</li>

 *                </ul>

 * @exception SWTException

 *                <ul>

 *                <li>ERROR_WIDGET_DISPOSED - if the receiver has been

 *                disposed</li>

 *                <li>ERROR_THREAD_INVALID_ACCESS - if not called from the

 *                thread that created the receiver</li>

 *                </ul>

 * 

 * @see SelectionListener

 * @see #removeSelectionListener

 * @see org.eclipse.swt.events.SelectionEvent

 */

public void addSelectionListener(SelectionListener listener) {

    checkWidget();

    if (listener == null) {

        SWT.error(SWT.ERROR_NULL_ARGUMENT);

    }

    TypedListener typedListener = new TypedListener(listener);

    addListener(SWT.Selection, typedListener);

    addListener(SWT.DefaultSelection, typedListener);

}

/**

 * Deselects the item at the given zero-relative index in the receiver. If

 * the item at the index was already deselected, it remains deselected.

 * Indices that are out of range are ignored.

 * 

 * @param index

 *            the index of the item to deselect

 * 

 * @exception SWTException

 *                <ul>

 *                <li>ERROR_WIDGET_DISPOSED - if the receiver has been

 *                disposed</li>

 *                <li>ERROR_THREAD_INVALID_ACCESS - if not called from the

 *                thread that created the receiver</li>

 *                </ul>

 */

public void deselect(int index) {

    checkWidget();

    ignoreSelectionEvent = true;

    ListUtils.deselect(topHandle(), index);

    ignoreSelectionEvent = false;

}

/**

 * Deselects the items at the given zero-relative indices in the receiver.

 * If the items at the given zero-relative indexes in the receiver are

 * selected, they are deselected. If they were not selected, they remain

 * deselected. Indices that are out of range and duplicate indices are

 * ignored.

 * 

 * @param indices

 *            the array of indices for the items to deselect

 * 

 * @exception IllegalArgumentException

 *                <ul>

 *                <li>ERROR_NULL_ARGUMENT - if the set of indices is null</li>

 *                </ul>

 * @exception SWTException

 *                <ul>

 *                <li>ERROR_WIDGET_DISPOSED - if the receiver has been

 *                disposed</li>

 *                <li>ERROR_THREAD_INVALID_ACCESS - if not called from the

 *                thread that created the receiver</li>

 *                </ul>

 */

public void deselect(int[] indices) {

    checkWidget();

    ignoreSelectionEvent = true;

    ListUtils.deselect(topHandle(), indices);

    ignoreSelectionEvent = false;

}

/**

 * Deselects the items at the given zero-relative indices in the receiver.

 * If the items at the given zero-relative indexes in the receiver were

 * selected, they are deselected. If they were not selected, they remain

 * deselected. The range of the indices is inclusive. Indices that are out

 * of range are ignored.

 * 

 * @param start

 *            the start index of the items to deselect

 * @param end

 *            the end index of the items to deselect

 * 

 * @exception SWTException

 *                <ul>

 *                <li>ERROR_WIDGET_DISPOSED - if the receiver has been

 *                disposed</li>

 *                <li>ERROR_THREAD_INVALID_ACCESS - if not called from the

 *                thread that created the receiver</li>

 *                </ul>

 */

public void deselect(int start, int end) {

    checkWidget();

    ignoreSelectionEvent = true;

    ListUtils.deselect(topHandle(), start, end);

    ignoreSelectionEvent = false;

}

/**

 * Deselects all selected items in the receiver.

 * 

 * @exception SWTException

 *                <ul>

 *                <li>ERROR_WIDGET_DISPOSED - if the receiver has been

 *                disposed</li>

 *                <li>ERROR_THREAD_INVALID_ACCESS - if not called from the

 *                thread that created the receiver</li>

 *                </ul>

 */

public void deselectAll() {

    checkWidget();

    ignoreSelectionEvent = true;

    ListUtils.deselectAll(topHandle());

    ignoreSelectionEvent = false;

}

/**

 * Returns the zero-relative index of the item which currently has the focus

 * in the receiver, or -1 if no item has focus.

 * 

 * @return the index of the selected item

 * 

 * @exception SWTException

 *                <ul>

 *                <li>ERROR_WIDGET_DISPOSED - if the receiver has been

 *                disposed</li>

 *                <li>ERROR_THREAD_INVALID_ACCESS - if not called from the

 *                thread that created the receiver</li>

 *                </ul>

 */

public int getFocusIndex() {

    checkWidget();

    return ListUtils.getFocusIndex(topHandle());

}

/**

 * Returns the item icon at the given, zero-relative index in the receiver.

 * Throws an exception if the index is out of range.

 * 

 * @param index

 *            the index of the item to return

 * @return the associated icon at the given index. Null means no icon

 *         defined.

 * 

 * @exception IllegalArgumentException

 *                <ul>

 *                <li>ERROR_INVALID_RANGE - if the index is not between 0

 *                and the number of elements in the list minus 1 (inclusive)

 *                </li>

 *                </ul>

 * @exception SWTException

 *                <ul>

 *                <li>ERROR_WIDGET_DISPOSED - if the receiver has been

 *                disposed</li>

 *                <li>ERROR_THREAD_INVALID_ACCESS - if not called from the

 *                thread that created the receiver</li>

 *                </ul>

 * @exception SWTError

 *                <ul>

 *                <li>ERROR_CANNOT_GET_ITEM - if the operation fails because

 *                of an operating system failure</li>

 *                </ul>

 */

public Image getIcon(int index) {

    checkWidget();

    if (index < 0 || index >= icons.size()) {

        SWT.error(SWT.ERROR_INVALID_RANGE);

    }

    return (Image) icons.elementAt(index);

}

/**

 * Gets the preferred icon size that matches the density style. The style

 * must be one of SWT.HIGH, SWT.MEDIUM, or or SWT.LOW.

 * 

 * @param style

 *            the size style. Only SWT.HIGH, SWT.MEDIUM, and SWT.LOW can be

 *            used.

 * 

 * @return Point the best icon size in pixel (width and height). Must be

 *         positive values.

 * @exception IllegalArgumentException

 *                <ul>

 *                <li>ERROR_INVALID_ARGUMENT - if the style value is invalid

 *                </li>

 *                </ul>

 * @exception SWTException

 *                <ul>

 *                <li>ERROR_WIDGET_DISPOSED - if the receiver has been

 *                disposed</li>

 *                <li>ERROR_THREAD_INVALID_ACCESS - if not called from the

 *                thread that created the receiver</li>

 *                </ul>

 *