3. Architectural Overview - swixeditor

paltryboarpigΛογισμικό & κατασκευή λογ/κού

3 Νοε 2013 (πριν από 3 χρόνια και 7 μήνες)

89 εμφανίσεις

Invivo software pr
ivate limited

SwixEditor overview

Invivo Software internal document


-

1

-





SwixEditor Overview


Contents provided by: SwixEditor

development

team

Reviewed by: Sanjeev Kumar







COPYRIGHT AND CONFIDENTIALITY

Copyright © Invivo software @2005. All rights reserved. No
part of this document may be reproduced in any form withou
t
the prior written consent of Invivo software private ltd.

This document is presented to you for viewing
only
.




Invivo software pr
ivate limited

SwixEditor overview

Invivo Software internal document


-

2

-




TABLE OF CONTENTS


1.

INTRODUCTION
................................
................................
................................
...............................

3

2.

FUNCTIONAL OVERVIEW

................................
................................
................................
............

3

2.1.

P
ALETTE

................................
................................
................................
................................
.......

4

2.2.

G
RAPHICAL
D
ESIGNER

................................
................................
................................
.................

4

2.3.

L
AYOUT FEEDBACK

................................
................................
................................
......................

5

2.4.

P
ROPERTY
S
HEET

................................
................................
................................
.........................

5

2.5.

O
UTLINE VIEW

................................
................................
................................
.............................

5

3.

ARCHITECTURAL OVERVI
EW

................................
................................
................................
...

6

3.1.

S
WIX
M
ODEL

................................
................................
................................
...............................

7

3.1.1.

BeanInfo VM

................................
................................
................................
...........................

7

3.2.

T
ARGET
VM

................................
................................
................................
................................
.

8

3.3.

P
ROXY
A
DAPTER

................................
................................
................................
..........................

8

3.4.

G
RAPHICAL
E
DITING
F
RAMEWORK

................................
................................
..............................

9

4.

CUSTOMIZATION ARCHIT
ECTURE OVERVIEW

................................
................................
...

9

4.1.

R
ESOLVING THE CUSTOM
CONTROL

................................
................................
............................
10

4.2.


S
IMPL
E
-

U
SING THE

CHOSE BEAN


OPTION
.

................................
................................
..............
10

4.3.

N
EXT LEVEL
-

C
USTOMIZE THE PALETTE

................................
................................
.....................
11

4.3.1.

Customizing the property view entries

................................
................................
...................
12

4.4.

A
DVANCED CUSTOMIZATIO
NS

................................
................................
................................
.....
13

5.

IMPLEMENTATION DETAI
LS

................................
................................
................................
.....
14

6.

MISCELLANEOUS INFORM
ATION

................................
................................
................................
.
14

6.1.

V
ISUAL
I
NHERITANCE

................................
................................
................................
.................
14

6.2.

A
BOUT
M
ODEL AND
E
DITOR CODE SEPARATIO
N

................................
................................
.........
14

6.3.

M
ETADATA IN THE MODEL

................................
................................
................................
..........
14

6.4.

C
ODE METRICS
:

................................
................................
.....
E
RROR
!

B
OOKMARK NOT DEFINED
.

Invivo software pr
ivate limited

SwixEditor overview

Invivo Software internal document


-

3

-

1.

Introduction


This document describes the functional and archite
ctural aspects of SwixEditor tool.
It
has the following sections




1.

Functional overview of SwixEditor

2.

Architectural overview of SwixEditor

3.

Customization architecture for supporting custom components.

4.

Main f
eature
s

summary

5.

Project information


2.

Functiona
l Overview


SwixEditor is a visual designer for Swing forms that are defined in XML format.
Unlike
the other Swing visual
form designers

that render the Java
(Swing)

Code in the designer
canvas, SwixEditor renders
an

XML defined swing form

in

the designer
canvas. The user
ca
n visually edit the Swing XML

using the provided editing tools.


At the functional level, SwixEditor is composed of the following parts



1.

Palette

2.

Graphical Designer (Also called Editor or Canvas)

3.

Layout Feedback

4.

Property Editor

5.

Hierarch
ical Outline


The
screen
-
shot

below describes each of these parts
.
The cartoons with black
background in the figure identify each of the numbered parts above.

The
next

sections
describe each of these parts.

Invivo software pr
ivate limited

SwixEditor overview

Invivo Software internal document


-

4

-



2.1.

Palette


The Palette contains components that
can be instantiated and visualized in the designer
canvas.

The user drags the component from the palette and drops it onto the designer.
The
visual feedback

guide
s

the user in dropping the component at the appropriate
location.

The xml representation

of th
e component

is inserted at the appropriate location
in the form XML (not shown to the users).


2.2.

Graphical
Designer


The graphical designer is a WYSIWYG canvas, which previews the form defined in
XML.

Any change to the form xml is reflected visually in the g
raphical designer/canvas.
The components can be modified directly in the editor or
by actions in the popup menus.
The property view is another interface for modifying the component. Any
modification to
the
component
results in

a change in the XML. The grap
hical editor responds to the XML
change by updating itself.



Invivo software pr
ivate limited

SwixEditor overview

Invivo Software internal document


-

5

-

2.3.

Layout feedback


Swing forms are laid out using a layout manager. Examples of layout managers are


BorderLayout, GridbagLayout,

JGoodies

FormLayout
etc. Each of these layouts imposes
a differe
nt structure of arrangements for the components within a container. The role of a
graphical designer tool becomes more prominent when it has to provide a WYSIWYG
feedback for laying out components in a container.


In the overview figure #1 above, the numb
ered rulers on the top and left side of the
F
orm,
and the dotted grid lines
are

the visual fe
edback for laying out
the form
using
the
J
goodies
FormL
ayou
t

(See cartoon #3 in the figure).


SwixEditor provides visual feedback for the following layouts






JGo
odies Form layout



Gridbag layout



Card layout



Flow layout



Border layout


There is plan to support Table layout and its specialized versions down the line.


2.4.

Property Sheet


The property sheet shows the properties of the components that are selected in the
gr
aphical designer or the outline view.
The properties are obtained from the model
definition of the component. The model definition is static for the components predefined
by the SwixEditor. The model definition for custom components is dynamically
generate
d by introspecting the beans. The value of
each property is shown in the property
sheet.

It can be edited with the associated property editor.

At present the property sheet is
implemented using the standard Eclipse property view. It will be converted to a
custom
view
with tabbed sections
.


2.5.

Outline view


The outline view
displays the structure of components representing the containment
hierarchy.

The selection between the entries in the outline view and the designer view is
synchronized both ways.

The outlin
e view displays each component





As a node with the same icon as in the palette



With the name extracted from the name attribute of the component.


It has the following features


Invivo software pr
ivate limited

SwixEditor overview

Invivo Software internal document


-

6

-




H
elps in the navigating the components hierarchically.



It has popup
menus

to make some operations easy.



User can select a control in the outline and move it to a specific location in the
designer.



It can be used to implement a parking lot.


3.

Architectural Overview


This section provides a design overview of SwixEditor. It i
s not a detailed design
document. There
are

separate
detailed design document
s

for each
feature

of SwixEditor.

Behind each of the functional aspects of SwixEditor lies an architectural component that
is the building block for that functionality. The table
below lists the functional parts and
their architectural building blocks.


Functional part

Architectural part



Graphical Designer

Graphical Editor Framework (GEF)

XML representation

Eclipse Modeling Framework (EMF)

Outline view

Tree Editor Framework (
part of GEF)

Property sheet


EMF static model, BeanInfo and Property
Adapters.

Palette

GEF, .xml file

Visual feedback

GEF, draw2D

WYSIWYG

Screen Xeroxing, or Screen Scraping




The following diagram shows the
architectural
components of SwixEditor.


Invivo software pr
ivate limited

SwixEditor overview

Invivo Software internal document


-

7

-




3.1.

Swix Model


The heart of a
ny

graphical editing system is its model. The model of SwixEditor is
represented using the Eclipse Modeling Framework. In this model,
called as SwixModel,
all the Swing component
s
are represented as
EMF objects

(
EObjects
)
.

SwixModel is
defined to
persist the resource (Form) in XML format. The schema for the XML
representation is the default XMI schema. It can be customized to generate XML for any
schema definition.


The SwixModel forms the static definition of components.

For dynamic models, that is
for components that are not defined statically (custom controls and objects), the EObject
is dynamically generated by introspecting the BeanInfo
. The BeanInfo class returns
information about the attributes, methods and events o
f the Java Bean.


3.1.1.

BeanInfo VM


For creating EObjects for custom components,

SwixEditor creates a separate VM, where
the custom widgets are introspected to return their attributes, methods and events.
However, not all aspects of a Bean can be capture
d in a BeanInfo. For example, a
container/containment relationship cannot be specified using BeanInfo. Similarly, editor
decorations such as direct
-
edit attributes cannot be specified using BeanInfo. SwixEditor
Invivo software pr
ivate limited

SwixEditor overview

Invivo Software internal document


-

8

-

provides a mechanism called override .xmi fil
es to capture this extra information for the
custom beans.

Further details are in section 4.0 of this document.

3.2.

Target VM


The task of the target VM is to provide an image of the Form to the Graphical Designer.

For every form opened in SwixEditor, a t
arget VM is created. Communication between
the target VM and the Graphical Designer is done through a socket.

Every widget
selected from the palette is instantiated on this target VM. All the property changes done
to the component in the designer are refle
cted in this VM, through a Proxy adapter.

A
java.awt.Graphics image is captured in the target VM application, and is sent to
SwixEditor through a socket. SwixEditor recreates that image as a SWT image and
displays it on the canvas.


3.3.

Proxy Adapter


The

SwixProxyAdapter is responsible for creating the instances of Widgets in the target
VM and to set their properties.

It listens to necessary events.

SwixEditor communicates
with the target VM using an API that is similar to the java.lang.reflect API.


Swix
Editor uses a number of custom proxy adapters to deal with specific widget
requirements. There are a
dapters for Frame, TabbedPane, o
ther

Containers, Components.
Work is in progress to create adapters for Table and its child components.



ComponentProxyyAdapter

ContainerAdapter

FrameAdapter

TabAdapter

J
Button,
J
Label,
J
Combo
Box
,
J
Tree,
J
T
ext,
J
TextBox,

J
Slider

JFrame, JInternalFrame

JPanel

JTabbedPane

JScrolledPane

ScrAdapter

Invivo software pr
ivate limited

SwixEditor overview

Invivo Software internal document


-

9

-




It is not clear yet, if there will be a requirement to expose the Proxy Adapter functionality
to the customizers of SwixEditor.

If there is a requirement, an extension
point
can be
provided.


3.4.

Graphical Editing Framework


The palette, desi
gner
-
view, outline view are all based on the Eclipse Graphical Editing
Framework or GEF.
GEF allows us to easily develop Graphical editor applications. GEF
follows the MVC architecture. It provides infrastructure to
build a graphical

edit
or for

any type of

model representation.

SwixEditor uses GEF to render the components in the
designer view and the nodes in the outline tree view.

GEF is built over the draw2D plugin.
GEF represents the visual components as Draw2D figures in the view.

Figures in draw2D
can
be hierarchically nested to create a complex visual representation.

The outline view
uses the SWT tree and tree items.


The role of Controller in the GEF MVC architecture is played by Edit
P
arts.

EditParts are
responsible for mapping the model objects to th
e view figures.

Edit
P
arts are also
responsible f
or making changes to the model. The changes to the model are not made
directly, but are made using Commands. Commands provi
de an interface to validate
model
changes. The commands are routed through a CommandS
tack,
to provide

undo
and redo support.


Each model object

represented in the editor has a corresponding
EditPart
. A container
edit part
has

child edit parts corresponding to the child model objects.


In SwixEditor all edit parts derive from a ComponentEdi
tPart. The ComponentEditPart
provides functionality common to all components. Some model objects have customized
edit parts


example: FrameEditPart, ContainerEditPart


4.

Customization Architecture Overview


This section discusses the architecture for sup
porting custom components (or controls) in
SwixEditor.

However it must be noted that the implementation of these features is not
completed yet.


There are three levels of interfaces to host custom components in SwixEditor. These
levels are categorized acc
ording to the level of flexibility required to customize the
hosting of custom components.


The levels are



Invivo software pr
ivate limited

SwixEditor overview

Invivo Software internal document


-

10

-

1.

Simple


Use the “chose bean” option

2.

Medium


Customize the palette

3.

Advanced


Customize the palette and the designer representation


We will revi
ew each o
f these options in detail in the following sections. Before we do
that lets understand the requirements for hosting a custom component in SwixEditor.


The first requirement is the component itself.
SwixEditor should be able to resolve a fully
qual
ified class name of the custom component. That is, the custom components class
name should be in the class path of the SwixEditor’s target VM (see section 3.2).

Second
requirement arises from the requirement to add the custom control entry to the palette.
Other requirements are advanced customization requirements that will be dealt in the
advanced customization subsection below.


4.1.

Resolving the custom control


SwixEditor uses the class path of the host project (The current project hosting the Form)
to f
ind the custom control.
However this is not an ideal way for the customers to use
custom controls because each user will have to add the jar file to their host project’s class
path. Moreover, if they create more than one project for SwixEditor forms, they
will have
to repeat the step for every project. The more scalable options that
SwixEditor

supports
are as follows
-


1.

Specifying the cla
ss path in a configuration file

-

SwixEditor will provide a
c
onfiguration file to specify location
s

of the jar file
s that

contain

the custom
c
omponent
s
. SwixEditor will provide a dialog to edit the contents of this
configuration file.

When SwixEditor is invoked the first time, it will read the
contents of this configuration file and extract the paths for custom controls.


2.

Sw
ixEditor provides an option to specify the path using the classpath containers.

The customer can create a plugin that implements the JDT extension point
org.eclipse.jdt.ui.classpathContainerPage.
The classpath container

is associated
to the palette entries

using another extension point explained in section 4.3
(Customizing the palette).


4.
2
.

Simple
-

U
sing

the “chose bean” option.


The simplest way to host a custom component in SwixEditor is to use the “chose bean”
option in the palette. The “chose bean”
option is same as the “chose bean” option in
Visual Editor and
in
Instantiation

s Designer.

The XML representation of the bean is in
the following format






Invivo software pr
ivate limited

SwixEditor overview

Invivo Software internal document


-

11

-


<component
type
=”custom”
class
=”com.nortel.application.beans.dateTime”


name
=”generatedName”
attr1
=”a1”
attr2
=”a2” />



4.
3
.

Next level
-

Customize the palette


The “chose bean”
option is very simplistic, and
solve
s

the problem for some of our users
without
requiring much
effort on their part.
However, for users
,

who want to

extend
SwixEditor

to seamlessly host more than a handful of custom controls, who want to add
the entries to the palette and who want to have control over the XML generated, the
“chose bean” option will not be sufficient.



SwixEditor provides extension po
ints to cater to the following requirements
-




Adding entries to the palette



Customizing the property entries



Specifying the format of the XML generated.


To add entries to the palette, the customizer will create an XMI

(An XML type
representation)

f
ile that

describes the entries to
be added to the palette.

To add a
“DateTime” custom entry in a group called “NortelControls”, the xmi entries will be as
follows
-



<xmi:XMI xmi:version="2.0"


xmlns:xmi="http://www.omg.org/XMI"


xmlns:ecore="http:/
/www.eclipse.org/emf/2002/Ecore"


xmlns:
swix
palette="http:///
com
/
invivosoft
/
swixeditor/emf
/
swix
palette.ecore"


xmlns:
swixutils
="http:///
com
/
invivosoft
/
swixeditor
/
emf
/
swixutils
.ecore">


<
swixp
alette:
Catagor
yCmp>


<categoryLabel xsi:type="
sw
ixutils
:ConstantString" string="
NortelControls
"/>







<cmpGroups xsi:type="
swix
palette:GroupCmp">


<cmpEntries xsi:type="
swix
palette:AnnotatedCreationEntry" xmi:id="entry2"



icon16Name="platfor
m:/plugin/
myplugin
/icons/custom.gif">





<objectCreationEntry xsi:type="
swix
palette:EMFCreationToolEntry"



creationClassURI
=
"java:/
com.nortel.application
#
Nor
DateTime
"/>


<entr
yLab
el xsi:type="swixutils
:ConstantString" string="
DateTime
"/>



</cmpEntries>




</cmpG
roups>


</swixpalette:Category
Cmp
>


</xmi:XMI>


Invivo software pr
ivate limited

SwixEditor overview

Invivo Software internal document


-

12

-

The user will then associate the palette with the classpath container, as using the
following plug po
int specification

in their plugin.xml manifest file



<extension


point="com.invivosoft.swixeditor.contributors">


<swixpalette


container="

com.nortel.editor.containerId
"


categories="
customprompter.xmi
"
/>


</extension>


The container attribute specified above is the id of the classpath container as specified in
the classpath container plug point specification below



<extension


point="org.eclipse.jdt.ui.classpathContainerPage">



<clas
spathContainerPage


name="Custom Prompter"




cl
ass="
com.nortel.editor.
ContainerWizardPage"




id="
com.nortel.editor.containerId
">



</classpathContaine
rPage>


</extension>



4.3.1.

Customizing the property view entries


Whenever the custom control is selected in the graphical designer or in the outline view,
the properties view will show its properties and their current values.

The view also allows
edit
ing the property values. SwixEditor has a number of predefined editors for properties
of different types


Integer, String, Color, Font, Dimension, Point etc.


The default behavior of property entries for a custom control can be customized by using
a Bean
Info class.

BeanInfo classes provide a way to describe a classes' design time
behavior and art part of the
JavaBeans specification
.

The BeanInfo specification allows
for a clas
s with the same name as its Java peer to exist that describes the edit time
behavior of the class.

The simplest way to create this class is to put it in the same package
as the class it describes.


Strictly speaking this isn't good physical separation of b
ehaviors
as the BeanInfo classes should be kept apart from the runtime in a separate package and
separate jar so they don't become part of the end user's actual deployment configuration.


A BeanInfo class is responsible for describing the list of propertie
s used by a tool such as
the SwixEditor, and also their edit time behavior.


This is done by specializing the
method
PropertyDescriptor[] getPropertyDescriptors()
.


The method
returns an array of
java.beans.PropertyDescriptor

objects, each one
representing

an item that will appear as a row in the Properties view and containing
information about its display name, the Java get and set method associated with the
property, as well as the rules for how the property should be edited.


The specification
Invivo software pr
ivate limited

SwixEditor overview

Invivo Software internal document


-

13

-

allows sup
port for editing behavior by having a
java.beans.PropertyEditor

defined against the
PropertyDescriptor.


SwixEditor also supports a shorthand notation for specifying key
-
value pairs on the
property descriptor.


public

PropertyDescriptor[]

getPropertyDescri
ptors() {



try

{


PropertyDescriptor[] result =
new

PropertyDescriptor[2];



result[0] =
new

PropertyDescriptor(
"date"
,DateTime.class);


result[1] =
new

PropertyDescriptor
(
"time"
,DateTime.class);


result[2] =
new

PropertyDescriptor
(
"ty
pe"
,DateTime.class);



result[
2
].setValue(
"enumerationValues"
,
new

Object[] {


"
DateTime
"
,
new

Integer(
DateTime
.
DATETIME
),
"
0
"
,



"
OnlyDate
"
,
new

Integer(MyCustomPrompter.
MORE
),
“1
"
,



"
OnlyTime
"
,
new

Integer(MyCustomPrompter.
OPEN
),
”2”




});




return

result;


}
catch

(IntrospectionException e) {


e.printStackTrace();


return null
;


}

}


4.4.

Advanced customization
s


Some
of the

advanced customization

scenarios

are as follows
-


1.

Decorate the widget figure. For example, if the user wants to add a special
decoration to the figure of DateTime component to differentiate the DateOnly
component from the Time
Only

component, then t
he customizer will have to
provide her own version of controller (EditPart).




SwixEditor architecture facilitates this, but the details are beyond the scope of this
document.


2.

The user wants to provide a granular editing of the sub
-
components within
a
custom component. For example, consider a custom component called
“searchGrid”. This component is composed of a “Combo”, a “Grid”, and a
“Button”. When this custom component is hosted in SwixEditor, the visual for
Invivo software pr
ivate limited

SwixEditor overview

Invivo Software internal document


-

14

-

this component will be one entity. The u
ser will not be able to select the “Grid” or
the “Combo” separately. When the user clicks on any of these parts, the entire
“SearchGrid” component will get selected. However, if the customizer wants to
provide for granular selection, then the user will hav
e to provide custom
implementations of “Controller” (or EditPart), and the “Adapter”.


SwixEditor does this for Tabs within a tabbed pane. The Tab header is not a
separate component in TabbedPane. But SwixEditor gives an illusion of a
separate header comp
onent through a custom editpart and adapter.


SwixEditor architecture facilitates this kind of advance customizations. But at
present it is beyond the scope of this document.


Apart from hosting custom controls, the customizer may want to control some othe
r
aspects of the editor, such as the look and feel, the colors etc. The interfaces for these
have not been worked out yet, and will be produced in this section whenever the design
for these features is done.

5.

Implementation details


This section is to be up
dated. At present it is not very important.

6
. Miscellaneous Information


This section lists the features not covered in the previous sections.


6.1
.

Visual Inheritance




Supports inheritance and plagiarization
.


6
.2.

A
bout Model and Editor
code
se
paration


SwixEditor was consciously designed to be independent of the model representation.
The static model can be easily configured to generate XML for any schema. We plan to
use the same model for generating XML for SwiXml, for SwixAt and other ope
n source
swing xml formats.


6
.3.

Metadata in the model


Almost all the important features are configurable through the model metadata, also
called as Annotations in the EMF parlance. The direct edit feature, the swing class path to
be used for the pr
oxy, the defaults for various attributes (such as the CellConstraint.fill
Invivo software pr
ivate limited

SwixEditor overview

Invivo Software internal document


-

15

-

values for various components) are all set using annotations. These annotations are
accessible programmatically and can be overwritten through configuration files.