lwlist.java

Zaval Light-Weight Visual Components Library (LwVCL) is a pure Java alternative to humble AWT-based

/**
 *     Caption: Zaval Light-Weight Visual Components Library
 *     $Revision: 2.79 $
 *     $Date: 2003/08/22 11:24:16 $
 *
 *     @author:     Andrei Vishnevsky
 *     @version:    3.50
 *
 * Zaval Light-Weight Visual Components Library (LwVCL) is a pure Java
 * alternative to humble AWT-based and SWING-based GUI interfaces for
 * wide ranges of platforms, including J2SE, PersonalJava and J2ME.
 *
 * Designed as light-weight but, alternatively to Swing, built separately
 * from AWT (not on top of the java.awt library like Swing), the LwVCL is
 * the good alternative to highly performant, memory-efficient, flexible
 * GUI solution for embedded, stand-alone and applet applications.
 *
 * For more info on this product read Zaval Light-Weight Visual Components Library Tutorial
 * (It comes within this package).
 * The latest product version is always available from the product's homepage:
 * http://www.zaval.org/products/lwvcl/
 * and from the SourceForge:
 * http://sourceforge.net/projects/zaval0003/
 *
 * Contacts:
 *   Support : [e-mail]
 *   Change Requests : [e-mail]
 *   Feedback : [e-mail]
 *   Other : [e-mail]
 *
 * Copyright (C) 2001-2003  Zaval Creative Engineering Group (http://www.zaval.org)
 *
 * This program is free software; you can redistribute it and/or
 * modify it under the terms of the GNU General Public License
 * (version 2) as published by the Free Software Foundation.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
 *
 */
package org.zaval.lw;

import org.zaval.lw.event.*;
import org.zaval.misc.*;
import org.zaval.misc.event.*;
import org.zaval.util.event.*;
import java.awt.*;
import java.awt.event.*;

/**
 * This is list component. The main features of the component are shown in the list below:
 * <ul>
 *   <li>
 *      The list component uses other light weight component as the list items. Use
 *      <code>add</code>, <code>remove</code>, <code>insert</code> methods to manipulate
 *      the list component content. For example, if it is necessary to add following three
 *      text items: "Item 1", "Item 2", "Item 3", you can use LwLabel component as it is shown
 *      below:
 *      <pre>
 *         ...
 *         LwList list = new LwList();
 *         list.add(new LwLabel("Item 1"));
 *         list.add(new LwLabel("Item 2"));
 *         list.add(new LwLabel("Item 3"));
 *         ...
 *      </pre>
 *      The class has method <code>add</code> that get string as input argument. The method
 *      creates LwLabel object with the string argument as a title. In this case the sample
 *      above can be simplify as follow:
 *      <pre>
 *         ...
 *         LwList list = new LwList();
 *         list.add("Item 1");
 *         list.add("Item 2");
 *         list.add("Item 3");
 *         ...
 *      </pre>
 *   </li>
 *   <li>
 *     The list component is a composite component, that allows to use other composite component
 *     as the list items. It means the it is possible to add LwButton component to the
 *     list as an item and it is possible to work with the component after it has been
 *     selected (the button component can be pressed).
 *   </li>
 *   <li>
 *     The list component uses LwListLayout as default manager to layout the list items.
 *     It is possible to use any other layout manager for the purpose, but the layout
 *     manager should implement org.zaval.misc.PosInfo to have ability working together
 *     with the a pos manager of the list. The library provides two layout managers that
 *     can be used as the layout manager: LwListLayout and LwGridLayout.
 *   </li>
 *   <li>
 *     The list has PosController class that is used to control position. Draw attention that
 *     selection and position are two different things. The list implementation automatically
 *     reselects item when the position has been changed. But further version of the component
 *     can support multiselection. To control the list position use pos controller that can be
 *     got by <code>getPosController</code> method. To control selection use <code>select</code>,
 *     <code>getSelected</code>, <code>getSelectedIndex</code>, <code>isSelected</code> methods.
 *     To listen when an item component has been selected use <code>addSelectionListener</code>
 *     and <code>removeSelectionListener</code> methods.
 *   </li>
 *   <li>
 *     The list component can scroll its view if not all items are visible. The feature works
 *     correct if the component will be inserted in LwScrollPan.
 *   </li>
 *   <li>
 *     Use <code>addSelectionListener</code> and <code>removeSelectionListener</code> methods
 *     to listen whenever the selected item has been changed. The selection event is represented
 *     by the LwActionEvent where <code>getData</code> method returns the selected item index.
 *   </li>
 * </ul>
 */
public class LwList
extends LwPanel
implements LwKeyListener, LwMouseListener,
           LwFocusListener, LwComposite,
           PosListener, ScrollObj
{
    private int selectedIndex = -1;
    private PosController controller;
    private PosInfo       posInfo;
    private LwActionSupport support;
    private LwComponent input;
    private int  dx, dy;
    private Color selectColor = LwToolkit.darkBlue, posRectColor = Color.yellow;
    private ScrollMan man;

   /**
    * Constructs a list component with no items.
    */
    public LwList() {
      setPosController(new PosController());
    }

    public /*C#override*/ boolean canHaveFocus() {
      return true;
    }

   /**
    * Sets the specified position controller. The controller manages the virtual cursor
    * location.
    * @param <code>c</code> the specified position controller.
    */
    public void setPosController(PosController c)
    {
      if(c == null) throw new IllegalArgumentException();
      if(c != controller)
      {
        if (controller != null) controller.removePosListener(this);
        controller = c;
        controller.addPosListener(this);
        if (posInfo != null) controller.setPosInfo(posInfo);
        repaint();
      }
    }

   /**
    * Sets the layout manager for this container. The layout manager has to implement
    * org.zaval.misc.PosInfo interface, the interface allows to control virtual position
    * of the list component with the position controller of the component.
    * @param <code>l</code> the specified layout manager.
    */
    public /*C#override*/ void setLwLayout(LwLayout l)
    {
      if (l != getLwLayout())
      {
        super.setLwLayout(l);
        if (l instanceof PosInfo) posInfo = (PosInfo)l;
        if (controller != null) controller.setPosInfo(posInfo);
      }
    }

   /**
    * Gets the position controller.
    * @return a position controller.
    */
    public PosController getPosController() {
      return controller;
    }

   /**
    * Gets the selection marker color.
    * @return a selection marker color.
    */
    public Color getSelectColor() {
      return selectColor;
    }

   /**
    * Sets the selection marker color.
    * @param <code>c</code> the selection marker color.
    */
    public void setSelectColor(Color c)
    {
      if (!c.equals(selectColor)) {
        selectColor = c;
        repaint();
      }
    }

   /**
    * Gets the position rectangle color.
    * @return a position rectangle color.
    */
    public Color getPosRectColor() {
      return posRectColor;
    }

   /**
    * Sets the color for a position rectangle. The position rectangle is rendered around
    * a list item where the current position is.
    * @param <code>c</code> the color.
    */
    public void setPosRectColor(Color c)
    {
      if (!c.equals(posRectColor)) {
        posRectColor = c;
        repaint();
      }
    }

   /**
    * Adds an item to the list. The method creates LwLabel component with the specified
    * label and adds it to the list.
    * @param <code>s</code> the specified label.
    */
    public void add (String s)  {
      add (new LwLabel(s));
    }

    /**
    * Selects the item by the specified index.
    * @param <code>index</code> the specified item index.
    */
    public void select(int index)
    {
      if (selectedIndex != index)
      {
        boolean b = clearSelection();
        if (index >= 0)
        {
          selectedIndex = index;
          b = !notifyScrollMan(index);
        }
        if (b) repaint();

        if (selectedIndex >= 0) perform(selectedIndex);
      }
    }

   /**
    * Gets the selected item index.
    * @return a selected item index.
    */
    public int getSelectedIndex() {
      return selectedIndex;
    }

   /**
    * Tests if the item with the specified index is selected or not.
    * @return <code>true</code> if the item with the specified index is selected; otherwise
    * <code>false</code>.
    */
    public boolean isSelected(int i)  {
      return i == selectedIndex;
    }

   /**
    * Adds the specified selection listener to receive selection events from this list component.
    * The event is represented by LwActionEvent where <code>getData</code> method returns Integer