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

 * Copyright (c) 2000, 2007 IBM Corporation and others.

 * Portion Copyright (c) 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:

 *     IBM Corporation - initial API and implementation

 *     Nokia Corporation - S60 implementation

 *     Nokia Corporation - QT implementation

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

package org.eclipse.ercp.swt.mobile;

import org.eclipse.swt.SWT;

import org.eclipse.swt.widgets.Composite;

import org.eclipse.swt.widgets.Event;

import org.eclipse.swt.widgets.Internal_PackageSupport;

import org.eclipse.swt.widgets.Scrollable;

import org.eclipse.swt.widgets.TypedListener;

import org.eclipse.swt.events.SelectionListener;

import org.eclipse.swt.graphics.Font;

import org.eclipse.swt.graphics.Image;

import org.eclipse.swt.graphics.Internal_GfxPackageSupport;

import org.eclipse.swt.graphics.Point;

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;

/**

 * Instances of this class represent a selectable user interface object that

 * displays a list of items consisting of text and icons from a data model. Each

 * list item may include combinations of heading text, heading icons, detail

 * text, and detail icons. The layout and display of the various text and icons

 * is variable depending upon the style and modifier constants passed to the

 * constructor. Only one LB_STYLE_xxxx layout style constant may be specified.

 * The LB_STYLE_NO_HEADING_TEXT style displays detail text on a single line per

 * item. The LB_STYLE_1LINE_ITEM style displays heading text next to detail text

 * in a single row. The LB_STYLE_2LINE_ITEM style displays heading text above

 * detail text in a two line cell.

 * <p>

 * The following diagrams show the general layout for each layout style:

 * <p>

 * LB_STYLE_NO_HEADING_TEXT <Table width=200 border=1>

 * <tr>

 * <td>Detail Text</td>

 * </tr>

 * <tr>

 * <td>Detail Text</td>

 * </tr>

 * <tr>

 * <td>Detail Text</td>

 * </tr>

 * <tr>

 * <td>Detail Text</td>

 * </tr>

 * </table>

 * <p>

 * LB_STYLE_1LINE_ITEM <Table width=200 border=1>

 * <tr>

 * <td>Heading Text</td>

 * <td>Detail Text</td>

 * </tr>

 * <tr>

 * <td>Heading Text</td>

 * <td>Detail Text</td>

 * </tr>

 * <tr>

 * <td>Heading Text</td>

 * <td>Detail Text</td>

 * </tr>

 * <tr>

 * <td>Heading Text</td>

 * <td>Detail Text</td>

 * </tr>

 * </table>

 * <p>

 * LB_STYLE_2LINE_ITEM <Table width=200 border=1>

 * <tr>

 * <td><b>Heading Text </b> <br>

 * Detail Text</td>

 * </tr>

 * <tr>

 * <td><b>Heading Text </b> <br>

 * Detail Text</td>

 * </tr>

 * <tr>

 * <td><B>Heading Text </b> <br>

 * Detail Text</td>

 * </tr>

 * </table>

 * <p>

 * The specific placement of item elements is locale and platform-dependent.

 * LB_MOD_xxxx style modifiers are hints which are implemented in a

 * platform-dependent fashion or perhaps not at all. They may be specified by

 * or-ing any number of LB_MOD_xxxx constants with one selected layout style.

 * Heading and detail icons are optionally displayed on any of the style layouts

 * by specifying the LB_MOD_SHOW_HEADING_ICONS or LB_MOD_SHOW_DETAILS_ICONS

 * modifiers. Heading and detail icons, if both displayed, are separated within

 * the layout to indicate that they are distinct from each other. The

 * LB_MOD_SHOW_SELECTION_NUMBER modifier is a hint for the ListBox to display a

 * single digit next to each item which indicates that pressing that number

 * selects the item. A list may be SINGLE or MULTI select. However, due to

 * typical layout contraints, MULTI select is a hint that is guaranteed to be

 * implemented only when no style modifiers are used.

 * <p>

 * The following is a possible layout for LB_STYLE_1LINE_ITEM |

 * LB_MOD_SHOW_DETAIL_ICONS | LB_MOB_SHOW_SELECTION_NUMBER: <Table width=200

 * border=1>

 * <tr>

 * <td>1</td>

 * <td>Heading</td>

 * <td>Detail Text</td>

 * <td>icon</td>

 * </tr>

 * <tr>

 * <td>2</td>

 * <td>Heading</td>

 * <td>Detail Text</td>

 * <td>icon</td>

 * </tr>

 * <tr>

 * <td>3</td>

 * <td>Heading</td>

 * <td>Detail Text</td>

 * <td>icon</td>

 * </tr>

 * <tr>

 * <td>4</td>

 * <td>Heading</td>

 * <td>Detail Text</td>

 * <td>icon</td>

 * </tr>

 * </table>

 *

 * <p>

 * The model data is provided by an array of ListBoxItems. The array is not

 * copied. The array is used until the ListBox is destroyed or a new data model

 * is set.

 * <p>

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

 * platforms, the fonts of the heading and detail texts are defined by the

 * layout styles. ListBox allows setting the fonts even if the underlying

 * platform does not, but in this case the appearance of the control will not

 * change.

 * <p>

 * <dl>

 * <dt><b>Styles: </b></dt>

 * <dd>SINGLE, MULTI</dd>

 * <p>

 * Note: Only one of SINGLE and MULTI may be specified.

 * <p>

 * </dl>

 * <dl>

 * <dt><b>Layout Styles: </b></dt>

 * <dd>LB_STYLE_NO_HEADING_TEXT</dd>

 * <dd>LB_STYLE_1LINE_ITEM</dd>

 * <dd>LB_STYLE_2LINE_ITEM</dd>

 * <p>

 * Note: Only one layout style may be specified. If more than one layout style

 * is specified, the actual style used is implementation dependent.

 * <p>

 * <dl>

 * <dt><b>Layout Style Modifiers: </b></dt>

 * <dd>LB_MOD_SHOW_SELECTION_NUMBER</dd>

 * <dd>LB_MOD_SHOW_HEADING_ICONS</dd>

 * <dd>LB_MOD_SHOW_DETAIL_ICONS</dd>

 * </dl>

 * <p>

 * Note: Style modifiers are hints. Any number of modifier styles may be

 * combined with a layout style

 * </dl>

 * <p>

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

 * <dd>Selection, DefaultSelection</dd>

 * </dl>

 * <p>

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

 * </p>

 *

 * @see ListBoxItem

 */

public class ListBox extends Scrollable {

    private static final int LISTBASE_SHOW_CHECKBOX = 0x80;

    private static final int LISTTYPE_STRINGLIST = 1;

    private static final int LISTTYPE_SORTEDLIST = 2;

    private static final int LISTTYPE_LISTVIEW = 4;

    private static final int LISTTYPE_LISTBOX = 8;

    private int layoutStyle;

    private int dataModelHandle;

    private int selectionModelHandle;

    private int listType;

    private boolean undoSelectionChangePhase = false;

    private int delegateHandle;

    private Font headingFont;

    private Image[][] detailImages;

    private Image[][] headingImages;

    private ListBoxItem []items;

    /**

     * single line item, 1 column (default)

     */

    public static final int LB_STYLE_NO_HEADING_TEXT = 0;

    /**

     * single line item, 2 columns

     */

    public static final int LB_STYLE_1LINE_ITEM = 1;

    /**

     * double line item, 1 column with heading and detail combined

     */

    public static final int LB_STYLE_2LINE_ITEM = 2;

    /**

     * shows a single digit number aligned with each item which may be used to

     * select the item.

     */

    public static final int LB_MOD_SHOW_SELECTION_NUMBER = 0x10;

    /**

     * shows icon associated with heading text

     */

    public static final int LB_MOD_SHOW_HEADING_ICONS = 0x20;

    /**

     * shows icons associated with detail text

     */

    public static final int LB_MOD_SHOW_DETAIL_ICONS = 0x40;

    static final class ListBoxPackageProxy extends PackageProxy {

        public void createHandle(int index) {

            ((ListBox)w).createHandle(index);

        }

        public void qt_signal_selectionChanged(int selectionHandle, int deSelectionHandle) {

            ((ListBox)w).qt_signal_selectionChanged(selectionHandle, deSelectionHandle);

        }

        public void qt_signal_abstractitemview_activated(int row, int column) {

            ((ListBox)w).qt_signal_abstractitemview_activated(row, column);

        }

        public void releaseHandle() {

            ((ListBox)w).releaseHandle();

        }

        public void releaseWidget() {

            ((ListBox)w).releaseWidget();

        }

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

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

        }

        public Point getPreferredClientAreaSize() {

            return ((ListBox)w).getPreferredClientAreaSize();

        }

        public void hookEvents() {

            ((ListBox)w).hookEvents();

        }

    }

    /**

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

     * describing its selection behavior, and a style value describing its

     * layout.

     * <p>

     * The <code>style</code> 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. Style bits are also inherited from

     * superclasses.

     * <p>

     * The <code>layoutStyle</code> value is one or more of the class layout

     * style constants which may be combined by <em>bitwise OR</em> 'ing. Use

     * of styles not applicaple to this class are ignored.

     * </p>

     *

     * @param parent

     *            a composite control which will be the parent of the new

     *            instance (cannot be null)

     * @param style

     *            the style of control to construct

     *

     * @param layoutStyle

     *            the layout style of control to construct

     *

     * @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

     */

    public ListBox(Composite parent, int style, int layoutStyle) {

        super(parent, checkStyle(style), checkLayoutStyle(layoutStyle),

                new ListBoxPackageProxy(), false);

        this.layoutStyle = layoutStyle;

        // show check box only for S60

        if (OS.windowServer == OS.WS_SYMBIAN_S60) {

            this.layoutStyle |= LISTBASE_SHOW_CHECKBOX;

        }

        initList();

        delegateHandle = OS.ListBoxItemDelegate_new(topHandle());

        /*

         * after next line, QListView owns item delegate

         */

        OS.QListView_setItemDelegate(topHandle(), delegateHandle);

    }

    static int checkLayoutStyle(int layoutStyle) {

        return Internal_PackageSupport.checkBits(layoutStyle, LB_STYLE_NO_HEADING_TEXT,

                LB_STYLE_1LINE_ITEM, LB_STYLE_2LINE_ITEM, 0, 0, 0);

    }

    static int checkStyle(int style) {

        return Internal_PackageSupport.checkBits(style, SWT.SINGLE, SWT.MULTI, 0, 0, 0, 0);

    }

    void createHandle(int index) {

        int scrollAreaHandle = OS.QListView_new();

        Internal_PackageSupport.setScrollAreaHandle(this, scrollAreaHandle);

        Internal_PackageSupport.setFrameHandle(this, scrollAreaHandle);

        Internal_PackageSupport.setHandle(this, OS.QAbstractScrollArea_viewPort(scrollAreaHandle));

        Internal_PackageSupport.setTopHandle(this, scrollAreaHandle);

        Internal_PackageSupport.setState(this, Internal_PackageSupport.state(this) | WidgetState.HANDLE);

    }

    /**

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

     * when the receiver's selection changes, by sending it one of the messages

     * defined in the SelectionListener interface.

     * <p>

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

     * <code>widgetDefaultSelected</code> is typically called when selection

     * is finalized.

     *

     * @param listener

     *            instance called when selection events occur

     *

     * @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 parent</li>

     *                </ul>

     * @exception SWTError

     *                <ul>

     *                <li>ERROR_ITEM_NOT_ADDED - if the operation fails because

     *                of an operating system failure</li>

     *                </ul>

     *

     * @see ListBox#removeSelectionListener

     * @see SelectionListener

     */

    public void addSelectionListener(SelectionListener listener) {

        listBase_addSelectionListener(listener);

    }

    /**

     * 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) {

        listBase_deselect(index);

    }

    /**

     * 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. 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) {

        listBase_deselect(start, end);

    }

    /**

     * 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) {

        listBase_deselect(indices);

    }

    /**

     * 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() {

        listBase_deselectAll();

    }

    /**

     * 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() {

        return listBase_getFocusIndex();

    }

    /**

     * Returns the number of items currently selected.

     * <p>

     *

     * @return count of selected items

     *

     * @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 parent</li>

     *                </ul>

     * @exception SWTError

     *                <ul>

     *                <li>ERROR_CANNOT_GET_COUNT - if the operation fails

     *                because of an operating system failure</li>

     *                </ul>

     *

     * @see #getSelectionIndices

     */

    public int getSelectionCount() {

        return listBase_getSelectionCount();

    }

    /**

     * Returns the zero-relative indices of the items which are currently

     * selected in the receiver. The array is empty if no items are selected.

     * <p>

     * Note: This is not the actual structure used by the receiver to maintain

     * its selection, so modifying the array will not affect the receiver.

     * </p>

     *

     * @return the array of indices of the selected items

     *

     * @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_SELECTION - if the operation fails

     *                because of an operating system failure</li>

     *                </ul>

     */

    public int[] getSelectionIndices() {

        return listBase_getSelectionIndices();