[Gzz] PEG ``vob_colorable--humppake``: Abstract Colorable Vob

[Asko Soukka]

I hope, I still remembered things from Friday..,

=======================================================
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/10 14:50:48 $
:Revision: $Revision: 1.2 $
: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.

- 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 ``AbstractColorableVob``.

- 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.

- 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.

- 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 AbstractColorableVob** should be created after the following
diagram:

.. UML:: abstractcolorablevob

    jlinkpackage gzz.vob

    class Vob "abstract"
        jlink

    class Colorable "interface"
        methods
            +Colorable cloneColored(List colors)
            +List getColors()
   
    class AbstractColorableVob "abstract"
        realize Colorable
        inherit Vob
        methods
            #ArrayList colors
            
    class vobs.RectBgVob
        realize AbstractColorableVob

    class vobs.OvalBgVob
        realize AbstractColorableVob

    class vobs.ColoredSectorVob
        inherit vobs.OvalBgVob

    class vobs.ColoredSquareSectorVob
        inherit vobs.ColoredSectorVob

   ---
   horizontally(50, vob_h, Colorable, Vob);
   vertically(50, vob_v, Vob, AbstractColorableVob, 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
``AbstractColorableVob``:

 - ``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.

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