[ve-dev] Design proposal - Allow custom layouts to be selected from the

[Peter Walker <walkerp@xxxxxxxxxx>]

Problem Description
Currently in the Visual Editor, there
is a hard coded list of layout managers for AWT/Swing, and layouts for
SWT, that can be selected in the property sheet viewer for containers that
allow the 'layout' property to be changed. For example, if you select a
javax.swing.JPanel in the graph viewer, and select the 'layout'
property in the property sheet, the drop-down list contains:

• <null>
• BorderLayout
• BoxLayout(X_AXIS)
• BoxLayout(Y_AXIS)
• CardLayout
• FlowLayout
• GridBagLayout
• GridLayout

The VE override extension files for
each layout manager has an EMF extension point that defines the respective
layout factory class. This layout factory class (an implementation of the
interface ILayoutPolicyFactory
provides public API's for getting such things as the GEF layout edit policy,
policy helper, layout switcher, and other classes needed to allow the VE
to provide an enhanced user experience in the graph and beans viewer. Here's
an example of the extension point in the BorderLayout.override file:
<?xml version="1.0" encoding="UTF-8"?>
<event:Add xmi:version="2.0"
xmlns:xmi="http://www.omg.org/XMI" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:org.eclipse.ve.internal.jcm="http:///org/eclipse/ve/internal/jcm.ecore"
xmlns:ecore="http://www.eclipse.org/emf/2002/Ecore"
    xmlns:event="event.xmi"

    featureName="eAnnotations">
  <addedEObjects xsi:type="org.eclipse.ve.internal.jcm:BeanDecorator">
    <keyedValues xsi:type="ecore:EStringToStringMapEntry"
key="org.eclipse.ve.internal.jfc.core.layoutpolicyfactoryclassnamekey"
        value="org.eclipse.ve.jfc/org.eclipse.ve.internal.jfc.core.BorderLayoutPolicyFactory"/>
  </addedEObjects>
</event:Add>

This extension point (although not an
official public extension point) can be used to write additional
layouts in user plugins and create their own layout policy factory that
define user specific edit policies and such.

The only problem is that the property
editor (LayoutManagerCellEditor for Swing, LayoutCellEditor
for SWT) is hard coded with a set of layouts and can't be overridden to
add additional custom layouts for selecting from the property sheet.

I would like to propose a design change
that would allow users to add other layouts to the list in the property
editors.


Design Proposal

Override extension
Provide an extension xmi override file,
one for AWT/Swing and one for SWT that would add annotations to the layout
super class of each. For AWT/Swing this is the interface java.awt.LayoutManager.
For SWT, this is the abstract class org.eclipse.swt.widgets.Layout.
The override file would contain an annotation
for each layout and within each annotation, two key/value pairs would be
defined:

1. The name of the layout class (e.g. java.awt.BorderLayout)
2. The display name to be used in the property sheet viewer (e.g. BorderLayout)

Here's an example of the annotation
to be used for java.awt.BorderLayout in the LayoutManager.override
file:
..... beginning definitions
  <event:AddMany featureName="eAnnotations">
        <addedEObjects
xsi:type="ecore:EAnnotation" source="org.eclipse.ve.LayoutInfo">
         
      <details xsi:type="ecore:EStringToStringMapEntry"
key="org.eclipse.ve.internal.jfc.core.layoutManagerClass"
         
              value="java.awt.BorderLayout"/>
         
      <details xsi:type="ecore:EStringToStringMapEntry"
key="org.eclipse.ve.internal.jfc.core.layoutManagerDisplayName"
         
              value="BorderLayout"/>
        </addedEObjects>
..... more annotations
  </event:AddMany>

Note: the source value
is org.eclipse.ve.LayoutInfo.
This is important since their are many other annotations that are not related
to layout information. This helps filter the annotations when retrieving
them from the EMF model.

Cell Editor implementation
When the layout cell editor is selected
for the first time in the property sheet viewer, reflection on the super
class would cause all layout override files to be loaded  and the
EMF model populated with the layout annotations. The annotations from the
model provide the display names in order to populate the combo box list.
Each display name maps to its respective layout class name so it can be
instantiated in the remote VM when selected. 

The cell editor provides the static
public API for creating and returning the lists; the edit domain is required:
        public
static
String [][] getLayoutManagerItems(EditDomain editDomain)
Currently, the label provider needs
the display name in order to show the correct value in the property sheet
when an object is selected.

EditDomain Cache for Layout Lists
Since the layout cell editor is recreated
many times during an edit session, a String array containing two
String arrays will be stored in the EditDomain using the
name of the editor as the key (e.g. org.eclipse.ve.internal.jfc.core.LayoutManagerCellEditor).
The first array contains the list of the layout class names and the second
array contains a list of the display names. Each entry in one corresponds
to the entry in the other. 

For each layout cell editor (one for
AWT/Swing, one for SWT), there will be an entry in the EditDomain
that is stored there the first time the cell editor is invoked.

Summary
Providing additional layouts in the
VE is an important part of extending the VE to provide an enhanced user
experience and allow users to work with visual components in a variety
of ways.


Please feel free to respond with your
thoughts or comments regarding this design.

Thanks...

Peter Walker
-------------------------------------
Eclipse JVE Development
919-254-1558 - T/L 444, Fax 254-8169, HYSA/501/K107
IBM SWG at RTP, 3039 Cornwallis Rd, RTP, NC 27709
Lotus Notes: Peter Walker/Raleigh/IBM   Internet: walkerp@xxxxxxxxxx