1
2
3
4
5
6
|
<?xml version='1.0' encoding='utf-8' ?><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=utf-8"/></head><body><h2 id="INTRODUCTION">INTRODUCTION</h2><p>In UML, the main information is represented in graphical diagrams. However, it is not always possible to represent graphically the whole semantic of UML, not talking of all the cosmetic properties. For example, it is pretty easy to represent and to edit a Class’ name graphically. While we still can represent the “is abstract” property graphically (By using the italic font for the Class’ name), it is harder to edit this property directly from the diagram. Worse, the “is leaf” property doesn’t even have a graphical representation. Thus, we often need a different view for representing all the properties of a UML Element, without polluting the graphical view.</p><p>As UML is highly extensible, through the mean of Profiles, it is also important to be able to represent and edit the profile’s properties, without managing everything from the diagram view.</p><p>Eclipse provides a standard view for these properties: the Properties Page. This view is a table representing all the properties available for the selected Element, including the ones that cannot be represented or edited graphically. This view is pretty useful, but is neither really user-friendly nor optimal, as it may require up to four clicks to simply edit a comment’s body. Moreover, it can only be extended via Java code, which requires some technical skills and prevents a dynamic modification of the view, as the Java code needs to be recompiled after each modification.</p><p>There is an extension of the base Property View framework, still in the standard Eclipse implementation, which fixes some of these problems. It is called the “Eclipse Tabbed Properties View” framework. It provides a better look and feel for the property view, with more flexibility, and a better usability. However, it keeps being difficult to customize, as it still hard-coded in Java.</p><p>Papyrus provides its own Property View framework, based on the Tabbed Property View framework. The Papyrus Property View can be extended in two ways:</p><ul><li>Dynamically, for the layout of the property view: show/hide a property, reorder the properties, add/remove a tab…</li><li>Statically, through Java code, for advanced operations: create a new widget for editing the properties, add a custom Content Provider for selecting a reference value…</li></ul><p>This document aims at detailing all the features related to the property view customization, both dynamically and statically.</p><h2 id="THE_CUSTOMIZATION_TOOL">THE CUSTOMIZATION TOOL</h2><p>Most customizations can be done through the Property view customization Editor. It provides native support for EMF Models, UML models and profiles. It also provides a set of basic widgets and property editors.</p><h3 id="Edit_a_configuration">Edit a configuration</h3><p>Each property view configuration is defined in a different set of files. Each configuration can contain elements from different contexts, but we typically have one configuration per Ecore Metamodel or UML Profile (i.e. one configuration for UML, one for the Diagram Appearance tab, another one for the SysML profile…)</p><p>To see the list of available configurations, open the properties view (Window -> Show View -> Other… -> General/Properties). Click on the white arrow in the upper right corner of the Properties view, and select “Customize property view”. You should see a dialog with the list of all available configurations.</p><p><img title="Open the property view customization menu" alt="Open the property view customization menu" border="0" src="ressource/fig1.png"/></p><p>As the standard configurations are read-only, you cannot edit them directly. You will first need to make a copy of the configuration. You will then be able to edit the copy.</p><p><img title="Copy an existing configuration to edit it" alt="Copy an existing configuration to edit it" border="0" src="ressource/fig2.png"/></p><p>The Property View Editor has three panes:</p><ul><li>The Editor part</li><li>The Preview part</li><li>The Properties part</li></ul><p>The Editor presents the elements defined by this configuration. The Preview displays an overview of the selected View, as it will be displayed in the property view at runtime. The properties view displays the properties of the selected element</p><p><img title="The property view Editor" alt="The property view Editor" border="0" src="ressource/fig3.png"/></p><h3 id="The_property_view_elements">The property view elements</h3><p>The editor contains a Tree, containing the following elements :</p><ul><li>Context: it is a property view configuration. You will typically have one property view Context per Ecore Metamodel or UML Profile, but you can choose the granularity you want. A context has a list of tabs, and a list of views.</li><li>Tab: describes a tab in the property view. A tab has a label, an (optional) image, and can be indented. It also has a priority.</li><li>View: describes a property view associated to a selection. The view has a name, a constraint, a multiplicity and a list of sections. The constraint is used to determine for what kind of object the view should be displayed.</li><li>Constraint: a query that inputs a selection, and outputs a boolean (true if the constraint matches the input object, false otherwise). It is possible to implement your own constraint type (In Java).</li><li>Section: a section is a sub-part of a view. A view generally needs only one section, but there are cases where you need more than one section. A section is associated to a single tab, so, if you want to display more than one tab in a single view (For example, « UML » and « Profile » in the UML property view), you will need at least two sections in that view (One for each tab). Another (advanced) case is described in « Dynamic sections ». A section has a name, a tab, and a Composite.</li><li>Composite: this is the actual presentation element. The composite is a widget which can contain other widgets. A composite has a type, and a list of widgets.</li><li>Layout: all composites need a layout. The default is « PropertiesLayout », which is a variant of the SWT standard GridLayout. A PropertiesLayout has a number of columns. The default is one column.</li><li>Property Editor: a property editor is a widget which is used to edit a single property of the selected object. You will typically have one Property editor for each property that you want to edit in the property view. The property editor has a property, and a widget to edit that property.</li><li>Standard Widget: a widget from the standard SWT Library. Few of them are currently available, because they are rarely needed.</li></ul><p>The Tree allows reordering or removing easily the elements (Through drag & drop, delete). The editor also supports the Undo/Redo commands.</p><h4 id="Preview">Preview</h4><p>The preview displays a real-time overview of the selected View. However, some widgets can only be computed at runtime, which prevents a pertinent preview. This is the case of the “Enum Radio” widget, for example, as the enumerated values are only known at runtime.</p><h4 id="Property_view">Property view</h4><p>The property view is used to edit the properties of the element selected in the tree. The property view uses the Papyrus Property View framework, thus can be customized just the same way you would customize any other property view.</p><p><img title=" the three panes of the Property view editor" alt=" the three panes of the Property view editor" border="0" src="ressource/fig4.png"/></p><h3 id="Priorities_between_views">Priorities between views</h3><p>When more than one view match a selection, a priority mechanism will determine which one(s) should be displayed. The priorities are defined at the level of the view’s constraints, i.e. if the constraint for a View A overrides a constraint for the View B, the View B won’t be displayed. For example, a UML Class from a Class Diagram will match many views (The list is not exhaustive):</p><ul><li>SingleClass (From UML)</li><li>MultipleClass (As the -1 multiplicity actually means “any number of elements”)</li><li>SingleElement (And MultipleElement)</li><li>SingleClassifier (And MultipleClassifier)</li><li>*Style (From GMF Notation model)</li><li>StereotypeDisplay (From UML Notation model)</li></ul><p>The priorities are computed in two ways:</p><ul><li>Automatic, according to the Java constraints implementations</li><li>Statically, according to the property view configuration</li></ul><p>When the “isOverrideable” property is set to false for a Constraint (In the property view model), only the static rules will be taken into account.</p><p><img title="The constraint cannot be dynamically overridden" alt="The constraint cannot be dynamically overridden" border="0" src="ressource/fig5.png"/></p><p>The automatic rules are the following:</p><ul><li>A constraint with a multiplicity of 1 always overrides the same constraint with a multiplicity of -1 (Or >1). Thus, “MultipleClass” won’t be displayed, because “SingleClass” also matches our selection.</li><li>An EMF (Or UML) “Instance of” constraint always overrides a constraint matching a supertype. Thus, “SingleClassifier” won’t be displayed, because a Class is more specific than a Classifier. However, “SingleElement” *will be* displayed, because it is not overrideable (isOverrideable=false).</li><li>A stereotype constraint (HasStereotype) will *not* override its UML “Instance of” constraint. However, a specific implementation of this constraint has been provided for Scade, which *will* override the UML metaclass (i.e., a Block will override a Class’ property view, hiding the UML tab).</li><li>For CompositeConstraints: if a composite constraint is a superset of another constraint, it will override it (It is more specific). For example, a Composite Constraint “isA and isB” will override a constraint “isB”, but will not override a constraint “isB and isC”.</li></ul><p>Please note that each constraint has its own implementation of the overrides() method. See the advanced chapter for more information</p><p>The static rule is simple: when a Constraint explicitly overrides another constraint, it will always override it. This is especially useful when you’ve marked a constraint as “overrideable=false”, but still want to override it in a specific case (Remember that overrideable=false only applies to *automatic* constraint resolution).</p><p><img title="Force this constraint to override another constraint" alt="Force this constraint to override another constraint" border="0" src="ressource/fig6.png"/></p><p>Finally, in the previous example, the following views will be displayed:</p><ul><li>SingleClass (Overrides MultipleClass, Single/MultipleClassifier ; UML Tab)</li><li>SingleElement (overrideable=false ; Profile tab)</li><li>FillStyle, FontStyle, LineStyle (Appearance tab)</li><li>StereotypeDisplay (overrideable=false ; Appearance tab)</li></ul><h3 id="Preferences">Preferences</h3><p>When you make a copy of a property view, it is not automatically activated. Thus, the modifications brought to the copy are not immediately visible on your property view. To activate a property view, you need to open the Papyrus preferences, from Window > Preferences.</p><p><img title="Preferences" alt="Preferences" border="0" src="ressource/fig7.png"/></p><p>When making a copy of an existing configuration, you should uncheck the default one, and check the new one.</p><h2 id="ADVANCED_CUSTOMIZATION">ADVANCED CUSTOMIZATION</h2><p>The customization tool only allows basic operations, such as adding, removing or reordering properties.</p><p>The property view framework is much more powerful, but this requires some Java development. This chapter will focus on the advanced customization of the property view.</p><h3 id="The_Environment_model">The Environment model</h3><p>To associate Java implementations with the property view model, you need to declare an Environment model. You can create a new Environment model with the “Environment Model” wizard in “Example EMF Model Creation Wizards” category. Select “Environment” as the Model Object.</p><p>Once you’ve added your Java class declarations, you should register the environment model so that the property view knows about it. Add an extension to org.eclipse.papyrus.properties.environment, and select your model file.</p><h3 id="Create_a_new_widget">Create a new widget</h3><p>You can create new widgets for the property view. There are four kinds of graphical elements: CompositeWidget, Layout, StandardWidget and PropertyEditor.
The widgets contain three common fields:</p><ul><li>Label: The label displayed in the Customization editor when the user selects a widget type.</li><li>Namespace: The XWT namespace associated to the Widget.</li><li>WidgetClass: The simple name of the Java class implementing the Widget.</li></ul><p>The PropertyEditor contains two additional fields:</p><ul><li>Multiplicity: The multiplicity of the properties it can handle (1 for single-valued properties, -1 for multivalued properties)</li><li>Type: The type of the properties it can handle.</li></ul><p>To implement a Composite, Layout or Standard widget, you should simply follow the SWT rules, i.e. extend either Composite, Canvas or Layout, and have a (Composite, int) constructor. To define a PropertyEditor, you have two options:</p><ul><li>Extend Composite, have a (Composite, int) constructor, and implement the CustomizablePropertyEditor interface (From org.eclipse.papyrus.properties.widgets)</li><li>Extend directly AbstractPropertyEditor (From org.eclipse.papyrus.properties.widgets)</li></ul><h3 id="Constraints">Constraints</h3><p>Adding a Constraint is similar to creating a new Widget. You have two options to implement a new Constraint:</p><ul><li>Implement the Constraint interface (From org.eclipse.papyrus.properties.constraints)</li><li>Extend the AbstractConstraint class (From org.eclipse.papyrus.properties.constraints)</li></ul><p>The important methods are the following (depending on whether you’re implement Constraint or extending AbstractConstraint):</p><ul><li>setDescriptor/setConstraintDescriptor: <ul><li>Configures the constraint.</li></ul></li><li>match(Object)/match(IStructuredSelection) : Boolean<ul><li>Indicates whether this constraint matches the given given or not</li></ul></li><li>overrides(Constraint) : Boolean<ul><li>Indicates whether this constraint overrides another constraint or not. A constraint should override another constraint when it is more specific.</li></ul></li><li>equivalent(Constraint) : Boolean<ul><li>This is only used by AbstractConstraint. Two constraints are equivalent if they have the same parameters (ConstraintDescriptor). Two equivalent constraints can have different multiplicities.</li></ul></li></ul><p>The equivalent() and overrides() methods are used to automatically resolve constraints conflicts (Two different constraints matching the same element).
Once the Constraint is implemented, don’t forget to register it in your environment model.</p><h3 id="ModelElement">ModelElement</h3><p>The ModelElement is the interface between the property view and your domain model. It is used to retrieve information about the object(s) being edited from the property. These informations will be used to configure the widget. AbstractModelElement provides a base implementation for this interface.</p><p>All methods from this interface take a single parameter, which is the name of the property being edited.</p><ul><li>getObservable(String) / doGetObservable(String) :</li></ul><p>This method returns an IObservable which will be used to read and write a single property from the represented object. It should return an IObservableValue for single-valued properties, and IObservableList for multi-valued properties.</p><ul><li>getContentProvider(String) :</li></ul><p>This method is only used for reference and enumerated properties. It should return a list of values which can be set to the edited property. Unlike IStructuredContentProvider, this provider will not rely on a StructuredViewer to retrieve an input object: the method getElement() will be called without any parameter, so the implementation should be able to retrieve its own typically. This will typically be achieved by passing a context object in the provider’s constructor.</p><ul><li>getLabelProvider(String) :</li></ul><p>This method is used to display an element’s label for a few widgets. Note that the same instance of label provider can be used by more than one Viewer for a given property. For example, the MultiReference widget will display three viewers, each using the same label provider. Each viewer will try to dispose the LabelProvider as soon as they are themselves disposed (For example, when closing the selection dialog from MultiReference). Thus, you should probably not implement the dispose() method, to avoid inconsistent providers.</p><ul><li>getValidator(String) : </li></ul><p>This method returns an IValidator, if there’s one which is set up for the current property. </p><h3 id="ModelElement_Factory">ModelElement Factory</h3><p>The ModelElements are associated to DataContextElements through a ModelElementFactory. The ModelElementFactory is defined on the DataContextRoot. All children of a DataContextRoot will share the same ModelElementFactory.</p><p>To add a new ModelElement, you should also create a new ModelElementFactory, and register it in your Environment model. Then, you can set this factory to your DataContextRoot.</p><p>Note: to display the Data contexts, you need to check the toggle button on top of the editor: <img border="0" src="ressource/fig8.png"/></p><p><img title="The UML DataContextRoots, with their own factories" alt="The UML DataContextRoots, with their own factories" border="0" src="ressource/fig9.png"/></p><h3 id="Content_Providers_and_Widgets">Content Providers and Widgets</h3><p>Note: The ContentProviders have been refactored in Papyrus 0.9, to be simplified. However, most of this chapter should remain true.</p><p>The ContentProvider is a complex features, which often evolves in the Papyrus property view. The ModelElement has been designed to be compatible with many kinds of different widgets (Combo-box, Tree-based dialogs…). The problem is that these widgets typically use different kinds of JFace ContentProvider (IStructuredContentProvider for flat display, ITreeContentProvider for Tree display). In the Property view, we needed to unify these providers.</p><p>Thus, it is recommended to use a IHierarchicContentProvider, which extends ITreeContentProvider, with an additional method: isValidValue(Object). In a Tree, we typically have two kinds of elements: the elements which can potentially be selected, and their containers, which often cannot. The isValidValue() method is used to distinguish between these values.</p><p>When a flat widget (e.g. ReferenceCombo) is used, only the valid values will be displayed. When a tree-based widget (e.g. ReferenceDialog) is used, a sub-tree will be displayed, excluding the sub-trees which don’t contain any valid value. Moreover, the invalid values won’t be selectable (For example, in the ReferenceDialog, the “ok” button will be grayed).</p><p><img title="IHierarchicContentProvider at runtime" alt="IHierarchicContentProvider at runtime" border="0" src="ressource/fig10.png"/></p><h3 id="Dynamic_sections">Dynamic sections</h3><p>Sometimes, the property view should not depend on a selection, but on a specific property of the selected element. In such a case, it is frequent that this specific property might be edited by the property view itself. However, the property view is only refreshed when the selection changes.</p><p>To overcome this problem, Papyrus offers a “Dynamic section” feature, which allows refreshing dynamically one or more sections of the property view. For example, when you’re editing a View’s constraint in the Property view Editor, the constraint’s properties directly depend on the constraint’s type. When you select an UML constraint, the constraint’s parameter is the name of a UML Metaclass. When you select an EMF constraint, the constraint has two parameters: Namespace URI of the Metamodel, and the name of the Metaclass. Changing the constraint type should also change the constraint’s parameters editors.</p><p><img title="A view with a static and a dynamic section" alt="A view with a static and a dynamic section" border="0" src="ressource/fig11.png"/></p><p>This can be achieved with dynamic sections, i.e. a section with a constraint. The constraint will be executed once at the beginning, and once again each time a property from the property view changes. If the constraint is matched, the section will be displayed. Otherwise, it will be hidden.
A view with dynamic sections will typically look like the following:</p><ul><li>A single unconstrained section containing the common parameters</li><li>One dynamic (i.e. constrained) section for each specific case</li></ul><p><img title="Dynamic sections configuration" alt="Dynamic sections configuration" border="0" src="ressource/fig12.png"/></p><p>Please note that tabs cannot be added nor removed dynamically. For example, when you apply a stereotype on a UML Element, the tab associated to the stereotype’s property view cannot be displayed until you select the element again.</p><h3 id="Property_view_Header">Property view Header</h3><p>The Eclipse Tabbed Property View offers an extension point to define the label provider for the property view header. However, this label provider will be specific to the editor. For generic editors, it is not always possible to provide a pertinent label provider: they will always be too generic, and won’t be able to handle specific elements. For example, a generic EMF Model Editor with the customizable property view will only be able to display standard EMF labels and icons. To overcome this problem, Papyrus offers a configurable label provider for the header: org.eclipse.papyrus.properties.provider.SelectionLabelProvider</p><p>This label provider uses the selected element to find the most appropriate label provider, then dispatches the getText and getIcon calls to it. This label provider can be configured through an extension point: org.eclipse.papyrus.properties.labelprovider</p><p>This extension point takes an implementation of IFilteredLabelProvider and a priority. The IFilteredLabelProvider is a label provider with an additional method: boolean accept(IStructuredSelection). For each selection, the label provider accepting the selection, and having the highest priority will be used to display a header for it. It will then be possible to define a generic label provider for all java objects, with the lowest priority; another generic label provider for all EMF Objects, and a really specific label provider for a given metamodel (with the highest priority).
In Papyrus, we have such an example for UML. The Papyrus UML Diagrams use the GMF model, which doesn’t have icons. We wanted to have a different icon for each type of Diagram: this is not possible with a standard EMF label provider, which associates an icon to an EClass, independently of its instances’ attributes.</p><p>So, we registered the standard EMF Label Provider with a medium priority, which can handle any kind of EObject, and a UML Label Provider, which can only handle UML Elements and GMF Diagrams, with a higher priority.</p><p>The lower the priority number, the higher the priority actually is: </p><ul><li>100: Lowest priority. The standard EMF Object label provider has a priority of 100, and is called iff no other label provider can accept an EObject.</li><li>50: Medium priority. The Papyrus UML Label Provider has a priority of 50.</li><li>10: High priority. </li><li>0: Highest priority.</li></ul><p>If no label provider matches the selection, the default JFace LabelProvider is used.</p><h3 id="Binding_and_Validation">Binding and Validation</h3><p>View Properties support JFace Databinding, which connects our UI to our model. For the validation there are two kinds of validators: </p><ul><li>Widget validators: they check that our input is the kind of data expected by our widget before synchronizing it ( e.g IntegerEditor must have a correct integer for input) </li></ul><ul><li>Model validators: they check that our input verifies our model constraint, they must be instantiate in UmlModelElement#getValidator();</li></ul><p>If there are errors during the binding a control decoration is shown next to the widget. It also supports three level of severity (Ok, Warning, Error).</p><p><img title="Example of binding with a model validator and warning severity result" alt="Example of binding with a model validator and warning severity result" border="0" src="ressource/fig13.png"/></p><h3 id="Field_coloration">Field coloration</h3><p>Properties views have fields’ coloration. If you modify a value the background of the field will be orange, when you validate a change the background will turn green for couple of seconds if the synchronization was successful, it will turn red otherwise. </p><p><img title="Example of a field being modified" alt="Example of a field being modified" border="0" src="ressource/fig14.png"/></p><h2 id="GENERATION_TOOL">GENERATION TOOL</h2><p>Editing an existing property view can be useful, but most of the time, you’ll want a brand new configuration for your own profile or meta-model. Thus, the framework provides a tool to automatically generate the initial property view, which you can then customize using the customization tool.
The generator can create a property view configuration from either a UML Profile or an Ecore Meta-model. The wizard is available in the Papyrus category: File -> New -> Other… -> Papyrus/Property view configuration.</p><p>The wizard provides two default generators:</p><ul><li>Generate a property view from a UML Profile</li><li>Generate a property view from an Ecore Meta-model</li></ul><p>The source file must be located in your workspace. A default target file named will be filled with the .ctx extension (This is the extension for a property view configuration).</p><p>Press next: a combo asks you which strategy to use. </p><p>A basic method: all the elements from the profile or meta-model will be extracted, with no dependencies to other models. </p><p>Same CTX file: you are asked to choose which models you want to extract, and will be saved in the same file</p><p>Different CTX file(s): you are asked to choose which models you want to extract and they will be saved in different files, (each profile name will be the name of the generated ctx file)</p><p>Press next: a table with all the elements extracted from your profile or meta-model is displayed. This table contains four columns:</p><ul><li>Field: the name of the element or property</li><li>Display single: whether this property should be displayed when a single instance of this element is selected</li><li>Display multiple: whether this property should be displayed when more than one instance of this element is selected</li><li>Description: the description of the property (Most of the time, it will be N/A, as the default generators cannot extract the documentation from the source model).</li></ul><p>Press finish: two files or more files according to the chosen strategy and a folder are generated:</p><ul><li>The *.ctx file, corresponding to your property view configuration</li><li>The ui/ folder, containing a set of XWT files, which contain the graphical information of your property views</li><li>The *FieldSelection.xmi file, which reminds the choices you’ve made about displaying each property. This file is currently unused.</li></ul><p>You can now open the *.ctx file and customize your property view.</p><h2 id="DEPLOYING_A_PROPERTY_VIEW">DEPLOYING A PROPERTY VIEW</h2><p>Papyrus provides a simple tool to deploy a property view locally (Right click on a CTX file -> Deploy/Undeploy) </p></body></html>
|
