Difference between revisions of "Graphical Modeling Framework/Concepts/Labels"

From Eclipsepedia

Jump to: navigation, search
 
(14 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 +
{{GMF}}
 +
 
Labels represent pieces of text possibly associated with icons on diagram surface. Text may be edited using inplace facility. There are many possibilities to construct labels but all of them are grouped in four usecases:
 
Labels represent pieces of text possibly associated with icons on diagram surface. Text may be edited using inplace facility. There are many possibilities to construct labels but all of them are grouped in four usecases:
  
Line 21: Line 23:
 
The only possible label figure is ''Label''. In generated diagram editor the actual figure may be ''Label'' from Draw2D or ''WrapLabel'' from GMF runtime. Attribute "text" of the figure is a text shown on diagram when parser is not available.
 
The only possible label figure is ''Label''. In generated diagram editor the actual figure may be ''Label'' from Draw2D or ''WrapLabel'' from GMF runtime. Attribute "text" of the figure is a text shown on diagram when parser is not available.
  
Position of label figure within model is important; it's used to determine whether label should be inner or external. Link labels are always external but node labels may be located whether inside node figure or "float" near it. If label figure is contained within parent node figure (directly or indirectly) it's inner label.
+
To access to this Label figure, a ''Child Access'' must be created in the figure where the label has been added. This ''Child Access'' will be used by the ''DiagramLabel'' to get the ''Label''.
  
''DiagramLabel'' element refers to the label figure and is being referenced by ''LabelMapping'' from mapping models. If "elementIcon" attribute is set then label use icon from EMF item providers.
+
Position of label figure within the model is important; it's used to determine whether label should be inner or external. Link labels are always external but node labels may be located whether inside node figure or "float" near it. If label figure is contained within parent node figure (directly or indirectly) it's inner label.
 +
 
 +
''DiagramLabel'' element refers to the label figure and is being referenced by ''LabelMapping'' from mapping models. If "elementIcon" attribute is set then label uses icon from EMF item providers. The following visual facets are recognized by tooling in ''DiagramLabel'':
 +
*''AlignmentFacet'' - specifies link label position relative to the link figure; in generator model alignment is copied to "alignment" property of ''GenLinkLabel''
 +
*''LabelOffsetFacet'' - initial distance between the label and node / link figure; in generator model represented by ''LabelOffsetAttributes'' instance in label viewmap
  
 
==Mapping==
 
==Mapping==
Line 31: Line 37:
 
Basic ''LabelMapping'' instance supports 3<sup>rd</sup> and 4<sup>th</sup> usecases. It has "diagramLabel" reference to graphical definition and "readOnly" flag.
 
Basic ''LabelMapping'' instance supports 3<sup>rd</sup> and 4<sup>th</sup> usecases. It has "diagramLabel" reference to graphical definition and "readOnly" flag.
  
''FeatureLabelMapping'' extends ''LabelMapping'' to support 1<sup>st</sup> usecase by referencing domain attributes and providing format patterns:
+
''FeatureLabelMapping'' extends ''LabelMapping'' to support 1<sup>st</sup> usecase by referencing domain attributes and providing format options:
 
*"features" reference: at least one attribute from domain model; all attributes should be defined within ''EClass'' of parent node / link
 
*"features" reference: at least one attribute from domain model; all attributes should be defined within ''EClass'' of parent node / link
*"viewPattern" and "editPattern" attributes: MessageFormat patterns used to construct label text and parse user input
+
*"editableFeatures" reference: same as "features" reference but used within inplace editor; if it's empty then "features" reference is used
 +
*"viewPattern": pattern to construct label text from feature value(s)
 +
*"editorPattern": pattern to construct text for inplace editor from feature value(s)
 +
*"editPattern": pattern to parse text entered by user in new feature value(s)
 +
*"viewMethod": method to produce text from feature value(s) by pattern; used with "viewPattern" and "editorPattern"
 +
*"editMethod": method to parse text entered by user in new feature value(s); used with "editPattern"
 +
 
 +
Currently supported methods are:
 +
*MESSAGE_FORMAT uses [http://java.sun.com/j2se/1.5.0/docs/api/java/text/MessageFormat.html java.text.MessageFormat] class ''(e.g. "{1}: {2}")''
 +
** The first feature starts at "{0}", the second will be "{1}", etc.
 +
** If you set the ''View Pattern'', you will also have to set the ''Edit Pattern''; setting the edit pattern to "{0}" will replace the first feature with text entered in, etc.
 +
*NATIVE only one attribute should be specified; calls EcoreUtil.convertToString(...) / EcoreUtil.createFromString(...) methods
 +
*REGEXP calls [http://java.sun.com/j2se/1.5.0/docs/api/java/lang/String.html#split(java.lang.String) String.split(...)] method
 +
*PRINTF calls [http://java.sun.com/j2se/1.5.0/docs/api/java/lang/String.html#format(java.lang.String,%20java.lang.Object...) String.format(...)] method
  
 
''DesignLabelMapping'' is a ''LabelMapping'' flavour to handle 2<sup>nd</sup> usecase. Now it's empty but there should be a way to define view style used to store label text in notation model [https://bugs.eclipse.org/bugs/show_bug.cgi?id=161593].
 
''DesignLabelMapping'' is a ''LabelMapping'' flavour to handle 2<sup>nd</sup> usecase. Now it's empty but there should be a way to define view style used to store label text in notation model [https://bugs.eclipse.org/bugs/show_bug.cgi?id=161593].
Line 48: Line 67:
  
 
Model facet reflects label usecase:
 
Model facet reflects label usecase:
*'''"feature label"''': ''FeatureLabelModelFacet'' instance; properties "features", "viewPattern" and "editPattern" are taken from ''FeatureLabelMapping''
+
*'''"feature label"''': ''FeatureLabelModelFacet'' instance; features and patterns are taken from ''FeatureLabelMapping''
 
*'''"design label"''': ''DesignLabelModelFacet'' instance
 
*'''"design label"''': ''DesignLabelModelFacet'' instance
 
*'''"default label" and "custom label"''': no model facet (''null'')
 
*'''"default label" and "custom label"''': no model facet (''null'')
Line 58: Line 77:
 
==Pending Requests==
 
==Pending Requests==
  
This is a list of enhancements related to GMF labels; future versions of GMF hopefully will implement them:
+
This is a list of enhancements related to GMF labels; hopefully future versions of GMF will implement them:
*[https://bugs.eclipse.org/bugs/show_bug.cgi?id=161380 Refactor labels in GMF 2.0]
+
 
*[https://bugs.eclipse.org/bugs/show_bug.cgi?id=150816 Support "design" labels for nodes backed up with domain element]
 
*[https://bugs.eclipse.org/bugs/show_bug.cgi?id=150816 Support "design" labels for nodes backed up with domain element]
 
*[https://bugs.eclipse.org/bugs/show_bug.cgi?id=138179 Allow to define labels based on attributes of referenced objects]
 
*[https://bugs.eclipse.org/bugs/show_bug.cgi?id=138179 Allow to define labels based on attributes of referenced objects]
 
*[https://bugs.eclipse.org/bugs/show_bug.cgi?id=161593 Allow to specify notation style for design label mapping]
 
*[https://bugs.eclipse.org/bugs/show_bug.cgi?id=161593 Allow to specify notation style for design label mapping]
*[https://bugs.eclipse.org/bugs/show_bug.cgi?id=158420 Using factory methods for converting to/from Strings and EDataType values in label editor parser]
 
*[https://bugs.eclipse.org/bugs/show_bug.cgi?id=156412 Support printf syntax to produce label text]
 
*[https://bugs.eclipse.org/bugs/show_bug.cgi?id=156411 Support regular expressions in label mappings to extract feature values from user input]
 
 
*[https://bugs.eclipse.org/bugs/show_bug.cgi?id=149429 It should be possible to specify whether empty string should be written in domain model when user provides emty string for the label]
 
*[https://bugs.eclipse.org/bugs/show_bug.cgi?id=149429 It should be possible to specify whether empty string should be written in domain model when user provides emty string for the label]
 
*[https://bugs.eclipse.org/bugs/show_bug.cgi?id=146818 Provide user feedback when invalid value is provided for the diagram label via direct editing]
 
*[https://bugs.eclipse.org/bugs/show_bug.cgi?id=146818 Provide user feedback when invalid value is provided for the diagram label via direct editing]
 
*[https://bugs.eclipse.org/bugs/show_bug.cgi?id=146789 Generate resizable labels (optionally)]
 
*[https://bugs.eclipse.org/bugs/show_bug.cgi?id=146789 Generate resizable labels (optionally)]

Latest revision as of 12:39, 5 October 2011



GMF
Website
Download
Dev Builds
Update Site releases milestones
Community
Mailing ListNewsgroupIRC
Bugzilla
Open
Help Wanted
Bug Day
Source
GMF Notation: View CVS repo

GMF Runtime: View CVS repo
GMF Tooling: View Git Repo, GitHub


Labels represent pieces of text possibly associated with icons on diagram surface. Text may be edited using inplace facility. There are many possibilities to construct labels but all of them are grouped in four usecases:

1. "feature based label"

Label is always defined in context of a diagram node or a link. If it's based on EClass from domain model then label may be used to represent attribute(s) of this class. Tooling will generate code that constructs label text and converts user input to the new value for attribute(s).

2. "design label"

It may be desirable to have a label that is not stored in domain model. Tooling may generate code that will use notation style (DescriptionStyle for example) to store label text in notation model.

3. "default label"

This is a read-only label with fixed text.

4. "custom label"

GMF runtime defines IParser interface that is responsible to provide label text and editing support. In this usecase toolsmith is supposed to provide his own IParser implementation.

Contents

[edit] Graphical Definition

The only possible label figure is Label. In generated diagram editor the actual figure may be Label from Draw2D or WrapLabel from GMF runtime. Attribute "text" of the figure is a text shown on diagram when parser is not available.

To access to this Label figure, a Child Access must be created in the figure where the label has been added. This Child Access will be used by the DiagramLabel to get the Label.

Position of label figure within the model is important; it's used to determine whether label should be inner or external. Link labels are always external but node labels may be located whether inside node figure or "float" near it. If label figure is contained within parent node figure (directly or indirectly) it's inner label.

DiagramLabel element refers to the label figure and is being referenced by LabelMapping from mapping models. If "elementIcon" attribute is set then label uses icon from EMF item providers. The following visual facets are recognized by tooling in DiagramLabel:

  • AlignmentFacet - specifies link label position relative to the link figure; in generator model alignment is copied to "alignment" property of GenLinkLabel
  • LabelOffsetFacet - initial distance between the label and node / link figure; in generator model represented by LabelOffsetAttributes instance in label viewmap

[edit] Mapping

LabelMapping and its subclasses define label within the mapping model.

Basic LabelMapping instance supports 3rd and 4th usecases. It has "diagramLabel" reference to graphical definition and "readOnly" flag.

FeatureLabelMapping extends LabelMapping to support 1st usecase by referencing domain attributes and providing format options:

  • "features" reference: at least one attribute from domain model; all attributes should be defined within EClass of parent node / link
  • "editableFeatures" reference: same as "features" reference but used within inplace editor; if it's empty then "features" reference is used
  • "viewPattern": pattern to construct label text from feature value(s)
  • "editorPattern": pattern to construct text for inplace editor from feature value(s)
  • "editPattern": pattern to parse text entered by user in new feature value(s)
  • "viewMethod": method to produce text from feature value(s) by pattern; used with "viewPattern" and "editorPattern"
  • "editMethod": method to parse text entered by user in new feature value(s); used with "editPattern"

Currently supported methods are:

  • MESSAGE_FORMAT uses java.text.MessageFormat class (e.g. "{1}: {2}")
    • The first feature starts at "{0}", the second will be "{1}", etc.
    • If you set the View Pattern, you will also have to set the Edit Pattern; setting the edit pattern to "{0}" will replace the first feature with text entered in, etc.
  • NATIVE only one attribute should be specified; calls EcoreUtil.convertToString(...) / EcoreUtil.createFromString(...) methods
  • REGEXP calls String.split(...) method
  • PRINTF calls String.format(...) method

DesignLabelMapping is a LabelMapping flavour to handle 2nd usecase. Now it's empty but there should be a way to define view style used to store label text in notation model [1].

[edit] Generator Model

Two hierarchies describe labels in generator model: descendants of GenLabel used to express label presentation in context of parent node / link and descendants of LabelModelFacet that denote label semantic. GenLabel references LabelModelFacet by "modelFacet" reference thus linking them together.

[edit] GenLabel

Basic GenLabel has "elementIcon" flag copied from graphical definition and "readOnly" flag from the mapping model. GenNodeLabel and GenExternalNodeLabel are concrete classes that should be used to represent inner and external node labels respectively. GenLinkLabel is for the link labels and has "alignment" attribute derived from respective visual facet. GenChildLabelNode provides the same attributes as GenLabel but prefixed with "label" word; this class is used for nodes within list compartments.

[edit] LabelModelFacet

Model facet reflects label usecase:

  • "feature label": FeatureLabelModelFacet instance; features and patterns are taken from FeatureLabelMapping
  • "design label": DesignLabelModelFacet instance
  • "default label" and "custom label": no model facet (null)

In fact during mapping model to generator model transformation the following rules are obeyed:

  • FeatureLabelMapping -> FeatureLabelModelFacet
  • DesignLabelMapping -> DesignLabelModelFacet
  • LabelMapping -> null

[edit] Pending Requests

This is a list of enhancements related to GMF labels; hopefully future versions of GMF will implement them: