Synoptic Display Studio Developers Guide

Size: px

Start display at page:

Download "Synoptic Display Studio Developers Guide"

Terence Owen
5 years ago
Views:

Synptic Display Studi Develpers Guide Table f Cntents 1. Intrductin... 3 2. Cntributing widgets... 4 2.1. Cncepts... 4 2.2. Defining the mdel... 5 2.2.1. Prvide a widget mdel... 5 2.2.2. Define a widget mdel factry.

1 Synptic Display Studi Develpers Guide Table f Cntents 1. Intrductin Cntributing widgets Cncepts Defining the mdel Prvide a widget mdel Define a widget mdel factry Register the widget mdel at the SDS Defining the view Defining the cntrller Prvide an edit part Register the edit part at the SDS Summary References Page - 1 -

2 Dcument Histry Dcument versin Authr Cmments 1.0 ( ) C1 WPS Initial versin 1.2 ( ) C1 WPS Pre-public versin Page - 2 -

3 1. Intrductin This dcument is intended t guide develpers wh want t cntribute t the develpment f the Synptic Display Studi (SDS). The SDS is an applicatin fr the Cntrl System Studi (CSS) that allws fr the visual design f displays and the cnnectin f these with prcess variables frm a cntrl system. Due t the CSS, SDS is based n the Eclipse Rich Client Platfrm (RCP). Tapping the ptential f the RCP, the SDS prvides an extensible system architecture that allws fr the integratin f custm widgets. All widgets (such as rectangles, ellipses, etc.) are integrated int the system via these pen mechanisms s every SDS widget beys the same integratin rules. Besides Eclipse RCP, tw ther SDS cre technlgies are the Eclipse Graphical Editing Framewrk (GEF) and the Data Access Layer (DAL). GEF is a framewrk that allws fr the develpment f graphical editrs with a rich functinality. DAL prvides access t underlying cntrl systems t establish cnnectins t prcess variables. Althugh the SDS brings tgether these rather cmplex technlgies it als defines a cmfrtable framewrk that hides mst f the cmplexity f these technlgies frm the widget develper. T prvide a cmprehensive example, we discuss the basic SDS rectangle widget in detail. Yu can develp and integrate custm widgets if yu fllw the steps that are presented in the fllwing. Chapter tw cntains a detailed discussin f the parts f the SDS architecture that need t be understd in rder t extend the system with custm widgets. Chapter three summarizes the steps and prvides shrt check list with an aggregated verview f all needed classes, interfaces and extensin pints. The furth chapter cntains sme references t dcuments that cntain in-depth descriptins f the technlgies the SDS is based upn. Page - 3 -

4 2. Cntributing widgets This chapter cntains a step-by-step example f hw the SDS can be extended with custm widgets. Therein we discuss all aspects that develpers have t keep track f if they want t cntribute a widget t the SDS Cncepts SDS widgets rely n the mdel-view-cntrller pattern t separate respnsibilities amng their single cmpnents. Due t this general design pattern every type f SDS widget (such as rectangles, meters and plygns) cnsists f the three separated parts: Mdel The mdel f a widget defines a set f prperties, stres the accrding values and keeps track f value changes. View The view f a widget is respnsible fr the visual representatin f a mdel. Cntrller Since the mdel f a widget des nt make any assumptins abut its representatin, an instance that mderates between it and its assciated view is needed. This is dne by the cntrller. Utilizing this pattern, lse cupling is eased as the respnsibilities are clearly shared amng the mdel, view and the cntrller. The Mdel des nt make any assumptins f hw it is suppsed t be used. The View is slightly mre intelligent as it is nrmally allwed t knw abut the Mdel and hw t use it. In ur cde we mdified this part f the MVC pattern and prevent ur Views frm knwing the Mdel directly. This helps t avid situatins with unclear respnsibilities. The Cntrller brings Mdel and View tgether and therefre knws abut the Mdel as well as abut its View. In the fllwing we prvide a detailed discussin f the integratin f the standard rectangle widget int the SDS. Page - 4 -

5 2.2. Defining the mdel The mdel f yur custm SDS widget encapsulates the widgets business lgic. This lgic is fairly simple in mst cases e. g. in case f the rectangle widget the business lgic nly cnsists f the strage f the fill level. T prvide a mdel that encapsulates the business lgic f a custm widget, the fllwing steps have t be perfrmed Prvide a widget mdel The class rg.csstudi.sds.mdel.abstractwidgetmdel is the base class f all SDS widget mdels. Therein, sme basic widget prperties are defined that are cmmn t all SDS widgets: width and height x and y crdinates fregrund and backgrund clr brder clr, width and style visibility A custm mdel must subclass AbstractWidgetMdel and can define additinal prperties. Fr example the standard rectangle mdel prvides a fill level prperty. The fllwing cde cntains the minimal definitin f the rectangle mdel. This cde is discussed later n. public final class RectangleMdel extends AbstractWidgetMdel { * The ID f the fill grade prperty. public static final String PROP_FILL = "fill"; //$NON-NLS-1$ * The ID f this widget mdel. public static final String ID = "element.rectangle"; //$NON-NLS-1$ * The default value f the fill grade prperty. private static final duble DEFAULT_FILL = 100.0; * public String gettypeid() { return ID; * prtected vid cnfigureprperties() { addprperty(prop_fill, new DublePrperty(Messages.FillLevelPrperty, WidgetPrpertyCategry.Behaviur, DEFAULT_FILL, 0.0, 100.0)); Page - 5 -

6 AbstractWidgetMdel defines tw abstract methds yu have t implement within yur custm mdel. The gettypeid() methd shuld return a unique ID which is used by the SDS framewrk t identify 1 yur mdel class and apply generic unctinalities (e. g. persisting yur mdel during runtime). The cnfigureprperties() methd is called by the SDS framewrk during the instantiatin f yur mdel class. Yu can use it t equip yur wn widget mdel with custm prperties. T d s, yu need t call addprperty(..) t add a new prperty t the mdel s prperty set. The signature f the addprperty(..) methd requests a prperty ID that must be unique within the widget mdel and an instance f WidgetPrperty that defines the prperty type. The SDS currently supprts the fllwing prperty types: BleanPrperty ClrPrperty DublePrperty FntPrperty IntegerPrperty OptinPrperty PintListPrperty StringPrperty Please refer t the JavaDc f these classes fr mre detailed infrmatin. The prperties f a widget mdel can be assigned t categries which are used t grup them in the Prperty View. If ne f the mentined widget prperty types is instantiated, yu have t prvide the assignment f the prperty t the available categries. These categries are defined by the enum PrpertyCategry. Currently there are the fllwing categries: Image Behaviur Display Psitin Misc Please refer t the JavaDc f WidgetPrpertyCategry fr mre detailed infrmatin. Additinally the standard cnstructr can be used t predefine values fr generic prperties (such as size, psitin etc.). Optinally yu can define custm accessr methds like getfilllevel(). 1 This indirectin is useful t avid identificatin rutines, which rely n the full qualified class name. Page - 6 -

7 Define a widget mdel factry All instances f SDS widget mdels must be created by assciated factries. S if yu prvide a custm mdel, yu have t prvide a factry fr it, as well. Mdel factries must implement the interface rg.csstudi.sds.mdel.iwidgetmdelfactry, the example f the rectangle widget factry illustrates: public final class RectangleMdelFactry implements IWidgetMdelFactry { * {@inheritdc public AbstractWidgetMdel createwidgetmdel() { return new RectangleMdel(); * {@inheritdc public Class getwidgetmdeltype() { return RectangleMdel.class; The methd createwidgetmdel() simply creates a rectangle mdel instance and returns it. getwidgetmdeltype() must return the Java type f the widget mdels that are created by the factry this is internally needed fr management purpses Register the widget mdel at the SDS S nce yu have successfully designed a custm widget mdel and have implemented a factry t create instances f it, yu have t make the SDS aware f the existence f yur widget. This registratin is perfrmed using the rg.csstudi.sds. widgetmdelfactries extensin pint f the plug-in rg.csstudi.sds. The registratin f ur example rectangle mdel lks like this: <extensin pint="rg.csstudi.sds.widgetmdelfactries"> <widgetmdelfactry class="rg.csstudi.sds.cmpnents.internal.mdel.rectanglemdelfactry" descriptin="rectangle" icn="icns/rectangle.gif" name="rectangle" typeid="element.rectangle"/> </extensin This definitin makes the SDS aware that there is a mdel with the ID element.rectangle and defines the creatin mechanism fr it. The attributes descriptin, icn and name define additinal infrmatin that is used fr the representatin f the described widget in the user interface. Nw the mdel is dne and can be used by the SDS cre. Page - 7 -

8 2.3. Defining the view The view cmpnent is respnsible fr the graphical representatin f a widget mdel. Within the SDS all visual elements have t implement the interface rg.csstudi.sds.ui.figures.irefreshablefigure. This interface is a specializatin f rg.eclipse.draw2d.ifigure. S designing visual elements fr the SDS basically means develping Draw2D figures. Fr a detailed intrductin int Draw2D please see [GEF04]. T give an example f the definitin f a SDS figure, the RefreshableRectangleFigure is discussed here: public final class RefreshableRectangleFigure extends RectangleFigure implements IRefreshableFigure { * The fill grade (0-100%). private duble _fillgrade = 100; * A brder adapter, which cvers all brder handlings. private IBrderEquippedWidget _brderadapter; * prtected synchrnized vid fillshape(final Graphics graphics) { Rectangle figurebunds = getbunds(); int neww = (int) Math.rund(figureBunds.width * (getfill() / 100)); graphics.setbackgrundclr(getbackgrundclr()); graphics.fillrectangle(getbunds()); graphics.setbackgrundclr(getfregrundclr()); graphics.fillrectangle(new Rectangle(figureBunds.getLcatin(), new Dimensin(newW, figurebunds.height))); * {@inheritdc public vid randmniserefresh() { setfill(math.randm() * 100); repaint(); * Sets the fill grade. * fill * the fill grade. public vid setfill(final duble fill) { _fillgrade = fill; * Gets the fill grade. * the fill grade public duble getfill() { return _fillgrade; * {@inheritdc Page - 8 -

9 public Object getadapter(final Class adapter) { if ( adapter == IBrderEquippedWidget.class) { if(_brderadapter==null) { _brderadapter = new BrderAdapter(this); return _brderadapter; return null; The RefreshableRectangleFigure is based upn the standard rg.eclipse.draw2d. RectangleFigure. It cntains the slight mdificatin that the fillshape methd actually draws a rectangle that is filled t the given level. A SDS figure shuld neither cntain any deeper lgic nr perfrm sme magic by itself. It shuld simply draw itself depending n the parameters that were set frm the cntrller. Fllwing this maxim the RefreshableRectangleFigure nly prvides the additinal methds getfilllevel and setfilllevel(..) s it can be equipped with the required infrmatin. The methd randmniserefresh() is a tribute t the testability f the SDS and its cmpnents. It is called by the SDS perfrmance tests t measure the average time that is needed t render the visual elements. If a figure shuld prvide a brder, it simply has t be adaptable t IBrderEquippedWidget as is shwn within getadapter() Defining the cntrller SDS widget cntrllers basically are special GEF edit parts. Yu dn t need in-depth knwledge abut GEF t prvide a cntrller fr a custm widget. The SDS prvides a cmfrtable framewrk fr that Prvide an edit part T prvide a custm edit part yu simply have t subclass rg.csstudi.sds.ui. editparts.abstractwidgeteditpart. The edit part fr a rectangle, fr example, lks like this: public final class RectangleEditPart extends AbstractWidgetEditPart { * prtected IRefreshableFigure dcreatefigure() { RectangleMdel mdel = (RectangleMdel) getcastedmdel(); RefreshableRectangleFigure rectangle = new RefreshableRectangleFigure(); rectangle.setfill(mdel.getfilllevel()); return rectangle; * prtected vid registerprpertychangehandlers() { // fill IElementPrpertyChangeHandler fillhandler = new IElementPrpertyChangeHandler() { Page - 9 -

10 public blean handlechange(final Object ldvalue, final Object newvalue, final IRefreshableFigure refreshablefigure) { RefreshableRectangleFigure rectangle = (RefreshableRectangleFigure) refreshablefigure; rectangle.setfill((duble) newvalue); return true; ; setprpertychangehandler(rectanglemdel.prop_fill, fillhandler); The dcreatefigure() methd creates the initial figure by instantiating a RefreshableRectangleFigure. In the mdel-view-cntrller pattern, the cntrller is respnsible fr the mderatin between the mdel and the view and therefre, in the case f the rectangle widget, it sets the figure s fill level with the value that is fetched frm the mdel. T access the accrding mdel, the methd getcastedmdel() can be called. The return type is AbstractWidgetMdel and s the result must simply be casted t the actual mdel type. Within the edit part, the handling f mdel prperty changes can be dne very finegrained. This is perfrmed by instances f IElementPrpertyChangeHandler that are attached t a mdel prperty. The assignment f prperty change handlers t mdel prperties is dne within the registerprpertychangehandlers() methd. In the upper example, a handler fr the fill level prperty is defined. Its handlechange(..) methd receives the changed value, updates the passed in figure and returns true r false whether the framewrk shuld be advised t redraw the figure r nt Register the edit part at the SDS After yu have defined the cntrller, it still has t be registered at the SDS. Yu simply have t prvide an extensin f the rg.csstudi.sds.ui.sdseditparts extensin pint f plug-in rg.csstudi.sds.ui: <extensin pint="rg.csstudi.sds.ui.widgeteditparts"> <widgeteditpart class="rg.csstudi.sds.cmpnents.ui.internal.editparts.rectangleeditpart" typeid="element.rectangle"/> </extensin> This extensin simply names the class f yur custm edit part and the assciated type ID. Please keep in mind that this ID is essential since it glues tgether the single cmpnents f a SDS widget. Page

11 3. Summary T cntribute a custm SDS widget, the fllwing steps have t be made: Define the mdel f yur custm SDS widget Prvide a custm mdel class that is a subclass f rg.csstudi.sds.mdel. AbstractWidgetMdel. This class encapsulates the business lgic f yur custm SDS widget. Define a factry that creates instances f yu mdel class. Factries have t implement rg.csstudi.sds.mdel.iwidgetmdelfactry. Register yur mdel class alng with the assciated factry at the rg.csstudi.sds.widgetmdelfactries extensin pint f the plug-in rg.csstudi.sds. Define the view f yu custm SDS widget Prvide an implementatin f rg.csstudi.sds.ui.figures.irefreshable Figure. Define the cntrller f yur custm SDS widget Prvide a custm cntrller class that is a subclass f rg.csstudi.sds.ui. editparts.abstractwidgeteditpart. This class is respnsible fr the mderatin between the mdel and it s view. Register yur cntrller class at the rg.csstudi.sds.ui.widgeteditparts extensin pint f plug-in rg.csstudi.sds.ui. Finally, t give an verall summary, the imprtant interfaces, classes and extensin pints are: Classes and interfaces rg.csstudi.sds.mdel.abstractwidgetmdel rg.csstudi.sds.mdel.iwidgetmdelfactry rg.csstudi.sds.ui.figures.irefreshablefigure rg.csstudi.sds.ui.editparts.abstractwidgeteditpart Extensin pints rg.csstudi.sds.widgetmdelfactries rg.csstudi.sds.ui.widgeteditparts Page

12 4. References The fllwing list cntains sme references t dcuments that prvide a mre detailed discussin f SDS-related technlgies. DAL06 Csylab: Data Access Layer API Prpsal, 04/2006, df. DAL07 Csylab: Data Access Layer Plug Implementatin, 01/2007, tatin.pdf. GEF04 IBM Redbk: Eclipse Develpment using the Graphical Editing Framewrk and the Eclipse Mdeling Framewrk, 02/2004, Lee03 Daniel Lee: Display a UML Diagram using Draw2D, 08/2003, Draw2d.html. Page

TRAINING GUIDE. Overview of Lucity Spatial

TRAINING GUIDE. Overview of Lucity Spatial TRAINING GUIDE Overview f Lucity Spatial Overview f Lucity Spatial In this sessin, we ll cver the key cmpnents f Lucity Spatial. Table f Cntents Lucity Spatial... 2 Requirements... 2 Setup... 3 Assign