lwgrid.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.grid;

import org.zaval.lw.event.*;
import org.zaval.lw.*;
import org.zaval.util.*;
import org.zaval.misc.*;
import org.zaval.misc.event.*;
import org.zaval.data.*;
import org.zaval.data.event.*;

import java.awt.*;
import java.awt.event.*;

/**
 * This is light weight grid component. The component is a composite component that is built basing
 * on MVC-model:
 * <ul>
 *   <li>
 *     <b>Model.</b> The component is bound with <code>MatrixModel</code>. Use
 *     <code>setModel</code> and <code>getModel</code> methods to set and get the
 *     model.
 *   </li>
 *   <li>
 *     <b>View.</b>
 *     The cell rendering process is defined by grid cell view provider interface. Use
 *     <code>setViewProvider</code> and <code>getViewProvider</code> methods to customize
 *     the process. Using the interface it is possible to define a background color for the
 *     specified cell, a view to render the cell data and horizontal and vertical alignments.
 *   </li>
 *   <li>
 *     <b>Controller.</b>
 *     The grid component controls painting, event handling and validation processes.
 *   </li>
 * </ul>
 * <p>
 * The component allows to edit cells data and customizes editor components types, by
 * the editor provider interface. Use <code>setEditorProvider</code> and
 * <code>getEditorProvider</code> methods to set and get the editor provider interface.
 * Actually the interface defines two things:
 * <ul>
 *  <li>light weight component that will be used to edit the specified cell data.</li>
 *  <li>how to fetch edited data from the editor component to update the grid model.</li>
 * </ul>
 * <p>
 * The component supports two metric types:
 * <ul>
 *   <li>
 *     <b>Custom metric.</b> In this case the rows heights and columns widths can be defined
 *     by the <code>setRowHeight</code> and <code>setColWidth</code> methods, the painting
 *     process uses horizontal and vertical alignments (provided by view provider interface)
 *     to align cells views.
 *   </li>
 *   <li>
 *     <b>Preferred size metric.</b> In this case the rows heights and columns widths are
 *     calculated basing on the cells views preferred sizes. <code>setRowHeight</code> and
 *     <code>setColWidth</code> methods have no effect. The painting process doesn't use
 *     horizontal and vertical alignments (provided by view provider interface) to align cells
 *     views.
 *   </li>
 * </ul>
 * To set appropriate metric type use <code>usePsMetric</code>method.
 * <p>
 * The component sets special layout manager that should not be changed. The layout
 * manager defines TOP_CAPTION_EL constraint that can be used to add grid caption
 * component as it is demonstrated below:
 * <pre>
 *   ...
 *   LwGrid        grid       = new LwGrid();
 *   LwGridCaption topCaption = new LwGridCaption(grid);
 *   grid.add (LwGrid.TOP_CAPTION_EL, topCaption);
 *   ...
 * </pre>
 * The LEFT_CAPTION_EL constraint is reserved for the futher version of the component.
 * <p>
 * To control selection state use PosController that can be got by <code>getPosController</code>
 * method. The component suppotrts single row selection. It is possible to disable selection
 * any grid row, set the pos controller to <code>null</code> for the purpose by
 * <code>setPosController</code> method.
 * <p>
 * The component implements ScrollObj interface, so the grid component can be used inside
 * LwScrollPan component.
 */
public class LwGrid
extends LwPanel
implements MatrixListener, ScrollObj, LwMouseListener,
           LwFocusListener, LwKeyListener, PosInfo, PosListener,
           LwLayout, LwGridMetrics, LwChildrenListener
{
   /**
    * Top caption component layout constraint.
    */
    public static final Integer TOP_CAPTION_EL  = new Integer(1);

   /**
    * Cell editor component layout constraint.
    */
    public static final Integer EDITOR_EL       = new Integer(2);

   /**
    * Left caption component layout constraint.
    */
    public static final Integer LEFT_CAPTION_EL = new Integer(3);

   /**
    * Use preferred size metric bit mask.
    */
    public static final short USE_PSMETRIC = 32;

   /**
    * Draw horizontal lines bit mask.
    */
    public static final short DRAW_HLINES = 64;

   /**
    * Draw vertical lines bit mask.
    */
    public static final short DRAW_VLINES = 128;

   /**
    * Enable col resizing bit mask.
    */
    public static final short ENABLE_COLRESIZE = 256;

   /**
    * The default column width.
    */
    public static final int DEF_COLWIDTH  = 80;

   /**
    * The default row height.
    */
    public static final int DEF_ROWHEIGHT = 20;

    private static final short METRIC_VALID = 512;
    private static final short ROWVIS_VALID = 1024;
    private static final short COLVIS_VALID = 2048;

    private Dimension          psSize;
    private MatrixModel        data;
    protected int[]            colWidths, rowHeights;
    protected int              dx, dy;

    private int                editingRow = -1, editingCol = -1, netSize = 1;
    private Insets             cellInsets = new Insets (2, 2, 2, 2);
    private LwGridViewProvider provider;
    private Color              netColor = Color.gray, noneActSelColor = LwToolkit.darkBlue, actSelColor = Color.yellow;

    private CellsVisibility    visibility = new CellsVisibility();
    private ScrollMan          man;
    private PosController      controller;
    private LwComponent        topCaption, editor;
    private LwEditorProvider   editors;

   /**
    * Constructs the component with the default data model.
    */
    public LwGrid() {
      this(new Matrix(5, 5));
    }

   /**
    * Constructs the component with the specified data model.
    * @param <code>data</code> the specified data model
    */
    public LwGrid(MatrixModel data)
    {
      setModel(data);
      setViewProvider(new LwDefViews());
      setPosController (new PosController());
      enableColResize(true);
      setNetMask ((short)(DRAW_HLINES | DRAW_VLINES));
    }

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


   /**
    * Sets the editor provider. The provider is used to define how the specified
    * cell should be edited.
    * @param <code>p</code> the specified editor provider.
    */
    public /*C#virtual*/ void setEditorProvider (LwEditorProvider p)
    {
      if (p != editors) {
        stopEditing(true);
        editors = p;
      }
    }

   /**
    * Gets the net mask.
    * @return a net mask.
    */
    public short getNetMask () {
      return (short)(bits & (DRAW_HLINES | DRAW_VLINES));
    }

   /**
    * Sets the specified net mask. The net mask is a bit mask that defines
    * what grid lines should be painted. There are four ways to paint grid lines:
    * <ul>
    *   <li>To paint only horizontal lines. Use DRAW_HLINES bit mask.</li>
    *   <li>To paint only vertical lines. Use DRAW_VLINES bit mask.</li>
    *   <li>To paint vertical and horizontal lines. Use DRAW_VLINES | DRAW_HLINES bit mask.</li>
    *   <li>To paint no lines. Use zero bit mask.</li>
    * </ul>
    * The default net mask is DRAW_VLINES | DRAW_HLINES.
    * @param <code>mask</code> the specified net mask.
    */
    public void setNetMask (short mask)
    {
      if (mask != getNetMask())
      {
        bits = MathBox.getBits(bits, DRAW_HLINES, (mask & DRAW_HLINES) > 0);
        bits = MathBox.getBits(bits, DRAW_VLINES, (mask & DRAW_VLINES) > 0);
        repaint();
      }
    }

   /**
    * Enables columns resizing. The method defines if the columns of the component
    * can be resized or not by <code>setColWidth</code> method.
    * @param <code>b</code> use <code>true</code> to enable columns resizing; <code>false</code>
    * otherwise.
    */
    public void enableColResize (boolean b) {
      if (MathBox.checkBit(bits, ENABLE_COLRESIZE) != b)
        bits = MathBox.getBits(bits, ENABLE_COLRESIZE, b);
    }

   /**
    * Sets the specified grid metric type. There are two metric types:
    * <ul>
    *  <li>
    *    Preferred size metric type.
    *  </li>
    *  <li>
    *    Custom metric type.
    *  </li>
    * </ul>
    * The default metric type is custom metric type.
    * @param <code>b</code> use <code>true</code> to set preferred size metric type;
    *  <code>false</code> to set custom metric type.
    */
    public void usePsMetric (boolean b)
    {
      if (isUsePsMetric() != b)
      {
        bits = MathBox.getBits(bits, USE_PSMETRIC, b);
        if (b) enableColResize(false);
        iMetric();
        repaint();
      }
    }

   /**
    * Gets the grid metric type.
    * @return <code>true</code> if the preferred size metric type is used;
    * <code>false</code> otherwise.
    */
    public boolean isUsePsMetric() {
      return MathBox.checkBit(bits, USE_PSMETRIC);
    }

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

   /**
    * Sets the position controller. The controller can be set to <code>null</code>, in this
    * case it will be impossible to navigate over the grid component rows.
    * @param <code>p</code> the specified position controller.
    */
    public void setPosController(PosController p)
    {
      if (controller != p)
      {
        if (controller != null) controller.removePosListener(this);
        controller = p;
        if (controller != null)
        {
          controller.addPosListener(this);
          controller.setPosInfo(this);
        }
        repaint();
      }
    }

   /**
    * Gets the data model.
    * @return a data model.
    */
    public MatrixModel getModel () {
      return data;
    }

   /**
    * Gets the view provider.
    * @return a view provider.
    */
    public /*C#virtual*/ LwGridViewProvider getViewProvider() {
      return provider;
    }

   /**
    * Sets the view provider.
    * @param <code>p</code> the view provider.
    */
    public /*C#virtual*/ void setViewProvider(LwGridViewProvider p)
    {
      if (provider != p)
      {
        provider = p;
        iMetric();
        repaint();
      }
    }

   /**
    * Sets the data model.
    * @param <code>d</code> the data model.
    */
    public /*C#virtual*/ void setModel (MatrixModel d)
    {
      if (d != data)
      {
        if (data != null) data.removeMatrixListener(this);
        data = d;
        if (data != null) data.addMatrixListener(this);
        iMetric();
        repaint();
      }
    }

   /**
    * Sets the selection marker color for the specified grid state. There are two possible states:
    * <ul>
    *   <li>The grid has focus.</li>
    *   <li>The grid has not focus.</li>
    * </ul>
    * @param <code>c</code> the selection marker color.
    * @param <code>hasFocus</code> the specified state. Use <code>true</code> for "grid has focus"
    * state and <code>false</code> for "grid has not focus" state.
    */
    public void setSelectColor (Color c, boolean hasFocusVal)
    {
       Color old = getSelectColor(hasFocusVal);
       if (!c.equals(old))
       {
         if (hasFocusVal)  actSelColor     = c;
         else              noneActSelColor = c;
         if (hasFocus() && hasFocusVal) repaint();
       }
    }

   /**
    * Gets the selection marker color for the specified grid state. There are two possible states:
    * <ul>
    *   <li>The grid has focus.</li>
    *   <li>The grid has not focus.</li>
    * </ul>
    * @param <code>hasFocus</code> the specified state. Use <code>true</code> for "grid has focus"
    * state and <code>false</code> for "grid has not focus" state.
    * @return a selection marker color.
    */
    public Color getSelectColor (boolean hasFocus) {
      return hasFocus?actSelColor:noneActSelColor;
    }

   /**
    * Gets the grid lines color.
    * @return a grid lines color.
    */
    public Color getNetColor () {
      return netColor;
    }

    public Insets getCellInsets () {
      return new Insets (cellInsets.top, cellInsets.left, cellInsets.bottom, cellInsets.right);
    }

   /**
    * Sets the grid cells insets.
    * @param <code>t</code> the top cell indent.
    * @param <code>l</code> the left cell indent.
    * @param <code>b</code> the bottom cell indent.
    * @param <code>r</code> the right cell indent.