[Gzz] PEG Colorable Vob

[Asko Soukka]

Some issues:

- Object.clone() needs implenting java.lang.Cloneable interface. Should
  Abstract ColorableVob or Vob implement it? 

  Since I don't know is there any use for it in Vob I've currently
  set ColorableVob to implement it.

- How Abstract Colorable Vob class should be named?

  Because using cloneColored() needs usually casting, I suggest
  only ColorableVob instead of AbstractColorableVob. At least today
  it was fine to Tuomas also. 

  interface Colorable + abstract class Vob = abstract class ColorableVob

And finally an example how using this would look in BoxCellView:

        /** Default background vob to use. */
        protected static ColorableVob defaultBg = new RectBgVob();

        /** ( The previous could be also i.e. "new RectBgVob(Color.yellow, 
         * false) to create vob with yellow background and without 
         * border line. )
         */ 
        ...

        /** Collecting possible multiple colors. */
        List cursorColors = context.getCursorColors(c);
        ArrayList vobColors = new ArrayList(5);
        if(cursorColors != null)
            for(Iterator i = cursorColors.iterator(); i.hasNext();)
                vobColors.add(i.next());
        if (c.s(d_clone, -1) != null) // if clone
            vobColors.add(Color.yellow);
        else if (c.s(d_clone, 1) != null) // if rootclone
            vobColors.add(new Color(0xffff8c));
        if (context.isMarked(c)) // if marked
            vobColors.add(new Color(0xff0000));
        
        /** If multiple colors found, clone multi-colored version
         * of default vob. Otherwise use default vob as it is.
         */
        final ColorableVob bg;
        if (vobColors.size() > 0) {
            Color[] colors = (Color[]) vobColors.toArray(new Color[1]);
            bg = (ColorableVob)defaultBg.cloneColored(colors);
        } else bg = defaultBg;

=======================================================
PEG ``vob_colorable--humppake``: Abstract Colorable Vob
=======================================================

:Authors:   Asko Soukka
:Stakeholders: Benja Fallenstein, Tuomas Lukka 
:Date-created: 2003-03-05
:Last-Modified: $Date: 2003/03/11 13:05:07 $
:Revision: $Revision: 1.3 $
:Status:   Current
:Scope:    Trivial
:Type:     Feature

This PEG proposes creating **Abstract ColorableVob** class, which
implements a new **Colorable interface** also defined by this PEG.

**Colorable Vob** is a very basic vob type, which enhances the regular
Vob with interface for placing multiple solid colors on its
background. The multiple solid colors are used a lot in basic views
i.e. to show cursor location and node properties. In the current
implementations multiple solid colors are shown as parallel vertical
stripes or sectors.

This PEG replaces the older `PEG for Abstract Background Vob`__.

.. _PEG: ../vob_bgvob--humppake/peg.gen.html
__ PEG_

Issues
------

- Why is Abstract Colorable Vob needed?

  RESOLVED: Currently there is no common interface for multiple solid
  colors in vobs, but they are defined and implemented from the scratch in 
  every background vob (starting from ``RectBgVob``). A common interface 
is
  necessary when a single node view that supports solid colors, should
  select between multiple different background vob types (basing the
  selection i.e. on nodes' content).

- Why was the PEG for Abstract BackgroundVob declared irrelevant?

  RESOLVED: It was about to propose such interfaces for background
  vobs, which would have made them strongly mutable. It was also
  criticized to restrict background vobs too much by forcing them to
  have border and background color properties.

- Should Colorable Vob be immutable?

  RESOLVED: Yes. The current multi-color implementation in
  ``RectBgVob`` and other background vobs have made them mutable.
  Inheriting those multi-color features from Colorable Vob should turn
  them back to immutable. Immutability allows storing created vob
  objects, re-using them and finally enhancing the overall
  performance.

  Multi-coloring stored vob prototype (which implements Colorable Vob)
  could be cloned using method::
  
    Colorable cloneColored(Color[] colors);

- How is Colorable Vob related to background vobs?

  RESOLVED: Colorable Vob won't define any background vob properties
  like background color or border. Although, background vobs should be
  immutable and use the common interface for multiple solid colors;
  They should be inherited from ``ColorableVob``.

- How should Colorable Vob be assembled?

  RESOLVED: ColorableVob extends the basic Vob class and implements
  Colorable Interface for multiple background colors.

- How should the new interfaces and classes be named?

  RESOLVED: **public interface Colorable** and **public abstract class
  ColorableVob**

- Where they should be located?

  RESOLVED: Currently in the package **``gzz.vob``**
  (``gzz.vob.Colorable`` and ``gzz.vob.ColorableVob``. Probably in the
  future they will be moved into package ``org.libvob.vob``.

- How should *solids* be renamed?

  RESOLVED: Earlier, *cellColors* has been proposed. Although, we are
  currently moving away from *cells* to *nodes*. Therefore *solids*
  should be called simply **colors**. Note that the method
  adding them in the current implementations has been called
  *addColor*.

- How should we store colors?

  RESOLVED: Since we are using the *java.util Collections API*
  the **ArrayList** implementation of List should be used.

  RE-RESOLVED: For performance reasons we should use pure **Color Array**.
  This is also reasonable, because vobs are immutable and therefore 
  colors can't be added after creating the multi-colored vob (via
  ``Colorable.cloneColore()``). 

  It still possible to use ArrayList for building up the colors and pass
  ``List.toArray()`` to ``Colorable.cloneColored()``.

- How should the colors be set?

  RESOLVED: Since Colorable Vob should be immutable, colors
  could be added only by cloning a new vob. This method would prefer
  setting all the colors at once as a single List.

  RE-RESOLVED: All colors should be set at once by passing 
  a single **array** to ``Colorable.cloneColored()``.

- Should SolidBgVob be inherited from Colorable Vob?

  RESOLVED: No. ``SolidBgVob`` is not a such background vob than other
  BgVobs (``RectBgVob`` and ``OvalBgVob``). More prefarably, SolidBgVob
  should be renamed to avoid misunderstandings.

- Should **Colored Sector Vobs** be inherited from Colorable Vob?

  RESOLVED: Yes. Also ``gzz.vob.vobs.ColoredSectorVob`` should be
  inherited from Colored Vob (via ``OvalBgVob``, which holds some
  circle routines for GL). Semantically Colored Sector Vobs are not
  meant to be background vobs, but they do have the same features. The
  difference to background vobs will be done by dropping ``Bg`` off from
  their naming.

Changes
-------

The Java classes **public interface Colorable** and **public abstract
class ColorableVob** should be created after the following
diagram:

.. UML:: abstractcolorablevob

    jlinkpackage gzz.vob

    class Vob "abstract"
        jlink

    class Colorable "interface"
        methods
            +Colorable cloneColored(Color[] colors)
            +Color[] getColors()
   
    class java.lang.Cloneable "interface"

    class ColorableVob "abstract"
        realize java.lang.Cloneable
        realize Colorable
        inherit Vob
        methods
            #Color[] colors
            
    class vobs.RectBgVob
        realize ColorableVob

    class vobs.OvalBgVob
        realize ColorableVob

    class vobs.ColoredSectorVob
        inherit vobs.OvalBgVob

    class vobs.ColoredSquareSectorVob
        inherit vobs.ColoredSectorVob

   ---
   horizontally(50, vob_h, Colorable, Vob, java.lang.Cloneable);
   vertically(50, vob_v, Vob, ColorableVob, vobs.RectBgVob);
   horizontally(50, vobs_h, vobs.RectBgVob, vobs.OvalBgVob);
   vertically(50, sector_v, vobs.OvalBgVob, vobs.ColoredSectorVob);
   horizontally(50, sector_h, vobs.ColoredSquareSectorVob, 
vobs.ColoredSectorVob);

The following background vobs should be modified to inherit
``ColorableVob``:

 - ``gzz.vob.vobs.RectBgVob``
 - ``gzz.vob.vobs.OvalBgVob``

**Cell Views** and **Node Views** will be broken (and hast to be
fixed) after this change, since background vobs' addColor interface
will be removed to make vobs immutable. 

The recommended way to fix Views is to store all needed vob prototypes
as class attributes when instantiating the class at the first
time. When a multi-colored version of any prototype (whose class
implements Colorable) is needed, it will be created by passing colors
to prototype's cloning method::

    Colorable cloneColored(Color[] colors);

-- 
Asko Soukka <address@hidden>
<http://www.iki.fi/asko.soukka/>