RMF/Contributor Guide/Presentations

Tutorial

This is a brief Howto that describes the creation of a new Presentation Plug-In for ProR.

Headline Presentation Plugin: The Requirements

The requirements are:

• The Presentation shows the configured attribute in a bigger font.
• The Presentation does not support automatic line wrapping.
• The font size can be configured.

Implementation

Step by step instructions.

Create a new Plug-In Project

• Create a new "Empty EMF Project".
• As a convention, start its name org.eclipse.rmf.reqif10.pror.presentation.xxx. We call it org.eclipse.rmf.reqif10.pror.presentation.headline.

Create the EMF Model Extension

Every Presenation must extend the ReqIF Model. This is fairly important to get right.

• Create a new "Ecore Model"
• Store it in the folder model (should already exist) and call it Headline.ecore.
• Leave all the other Defaults and create the model. It should consist of a top-level element (starting with "platform:/...") and an empty package.
• Select the package and configure it in the Properties-View as follows:
  • Name: headline
  • Ns Prefix: headline
  • Ns URI: http://eclipse.org/rmf/pror/presentation/headline
• We need to refer to the ProR UI Model to extend it.
  • Make sure that the Project org.eclipse.rmf.reqif10.pror is in your workspace and open.
  • In your model editor for Headline.ecore, right-click and select "Load Resource..."
  • Select configuration.ecore (platform:/resource/org.eclipse.rmf.reqif10.pror/model/configuration.ecore)
• Now we create the required new Configuration Class
  • Right-Click on the "headline" package
  • Create a new Child of type "EClass"
  • Configure it in the Properties as follows:
    • ESuperTypes: ProrPresentationConfiguration
    • Name: HeadlineConfiguration
• We may as well add the Attribute for Font Size at this time:
  • Right-Click on HeadlineConfiguration and create a new Child of type EAttribute
    • Name: size
    • EType: EInt
    • Lower Bound: 1 (required field)

Your model editor should look as follows:

Create the GenModel

Here, too, things can go wrong. Pay particular attention to how the referred Models are handled.

• Create a new "EMF Generator Model"
  • Call it Headline.genmodel and put it into the same folder model where Headline.ecore is stored
  • Select the "Ecore Model" importer
  • Select the Model URI for Headline.ecore model (it it isn't preloaded already). You may have to hit the "Load" button before you can proceed.
  • Pay attention now as the references must be selected correctly. You should be in the "Package Selection". This Dialog has two panes. In the upper pane you should see the headline, configuration and several reqif packages.
  • Use the "Add" button to add the Genmodels for reqif. Therefore, select the reqif.genmodel file from the org.eclipse.rmf.reqif10.pror plugin. They should now be visible in the lower pane.
  • Check the checkboxes for Configuration and XMLNamespace in the lower pane. As you do this, the packages should disappear from the upper pane.
    • Here is what happened: In the Ecore, we were referencing two models. When we created the Genmodel for Headline, the default would have been to create Genmodels for all three packages. But we only want a Genmodel for Headline. Thus, we have to provide references to existing Genmodels.
  • Last, check the checkbox for Headline in the upper pane. This should enable the "Finish" button
  • Click Finish: The new Genmodel should be open. It should show several package entries. For instance, the entries to Configuration and ReqIF10 should have little arrows, indicating that they are references.
• We only need to generate the Model and Edit code. By default, the Edit code ends up in a new Plugin Project. This is overkill for such a small project. We will change the configuration to generate the Edit code in the Model Plugin (the one we're currently in).
  • Select the Top-Level element "Headline".
  • Expand the "Edit" section in the Property View. Change the Properties as follows:
    • • Edit Plug-in ID: org.eclipse.rmf.reqif10.pror.presentation.headline (remove the training ".edit")
      • Edit Directory: /org.eclipse.rmf.reqif10.pror.presentation.headline/src
    • Now Select the Package "Headline" (just one element below the one you just worked on). Edit in the properties:
      • Base Package: org.eclipse.rmf.reqif10.pror.presentation (Upon code generation, the package name will be appended. Thus the generated package will be org.eclipse.rmf.reqif10.pror.presentation.headline)
• Now we should test our settings.
  • Right-click on the top-level element and select "Generate Model Code"
  • Same with "Generate Edit Code"

• • Note: If you want to generate more, please be sure to configure the project accordingly, unless you want to create new Projects.
  • After the generation, make sure that no new Projects appear in your workspace. Check the source folder, there should be the following four packages:
    • org.eclipse.rmf.reqif10.pror.presentation.headline (the model interfaces)
    • org.eclipse.rmf.reqif10.pror.presentation.headline.impl (the model implementation)
    • org.eclipse.rmf.reqif10.pror.presentation.headline.provider (the ItemProviders, from the Edit generation)
    • org.eclipse.rmf.reqif10.pror.presentation.headline.util (helper code)
• Congratulations! You're done with this step.

Implementing PresentationEditInterface

You will get a number of compile errors, as the interfaces from PresentationEditInterface are not implemented. This interface is inherited by the (abstract) ConfigurationItemProvider. The interface has been written carefully to provide information on how to implement it. So implement it, and refer to the interface documentation if you are stuck.

Next, make the ConfigurationItemProvider stateful by editing the genmodel again, and by regenerating the ItemProviders. this way, you have one instance per configuration element:

• Go to your genmodel
• Open the tree and select HeadlineConfiguration
• In the properties view, open "Edit" and set "Provider Type" to "Stateful".
• Regenerate - it's enough to right-click on HeadlineConfiguration and select "Generate Edit Code"

Extending the Extension Point

Now we will create an extension to tell ProR about the new Presentation:

• Open the Plugin-Manifest (plugin.xml) or the MANIFEST.MF if no plugin.xml exists
• Go to Dependencies and add org.eclipse.rmf.reqif10.pror.editor
• Add a new Extension as follows:

 <extension
         point="org.eclipse.rmf.reqif10.pror.editor.presentation">
      <presentation
            name="Headline"
            service="org.eclipse.rmf.pror.presentation.headline.ui.HeadlinePresentationService">
      </presentation>
   </extension>

We created a new package (ui) to prevent mixing generated and hand-written code.

Implementing the PresentationService

• Next, we'll implement the service (you can generate a stub by clicking on "service" in the Extension View)
• We won't describe the interface methods in detail - please check the JavaDoc, the Interface is well-documented. For simple methods, the JavaDoc even provides the recommended Implementation code.
• We decide not to modify getCellEditor(). By returning null, the default implementation is returned (doesn't matter that the font is small while editing)
• To actually do the proper rendering, we have to modify getCellRenderer() to return a new cell renderer that renders the content in a bigger font.
  • We change the code to

public IProrCellRenderer getCellRenderer(AttributeValue av) {
  if (headlineCellRenderer == null) {
        // Get the headline configuration
        HeadlineConfiguration headlineConfiguration = (HeadlineConfiguration) ConfigurationUtil.getPresentationConfig(av, null);
        // Create a new headline cell renderer
	headlineCellRenderer = new HeadlineCellRenderer();
        // Set the font size from the configuration
        headlineCellRenderer.setFontSize(headlineConfiguration.getSize());
  }
  return headlineCellRenderer;
}

All that's missing is that class.

Implementing the Cell Renderer

In order to create a Cell Renderer for the presentation we have to create a new class HeadlineCellRenderer and to implement the interface IProrCellRenderer. Here is a very basic implementation:

public class HeadlineCellRenderer implements IProrCellRenderer {
 
	private Font font;
	private int fontSize;
 
	public void setFontSize(int fontSize) {
		this.fontSize = fontSize;
	}
 
	public int doDrawCellContent(GC gc, Rectangle rect, Object value) {
		AttributeValueSimple av = (AttributeValueSimple) value;
		String text = ReqIF10Util.getTheValue(av).toString();
		FontData[] fontData = { new FontData("Arial", fontSize, SWT.BOLD) };
		if (font != null)
			font.dispose();
		font = new Font(Display.getDefault(),fontData);
		gc.setFont(font);
		gc.drawText(text, rect.x, rect.y);
		return gc.textExtent(text).y;
	}
 
	public String doDrawHtmlContent(Object value) {
		AttributeValueSimple av = (AttributeValueSimple) value;
		return "<div style='font-size: " + fontSize
				+ "pt; font-weight: bold; padding-top: 4pt;'>"
				+ ReqIF10Util.getTheValue(av) + "</div>";
	}
 
}

• The doDrawCellContent method is responsible for rendering the cell in the Specification Editor.
• The doDrawHtmlContent method is used for generating the HTML representation of the attribute. Sell also RMF/Documentation_Guideline#ReqIF_to_HTML_Generator

Testing

You can test the new Presentation by creating a new entry with ProR > Presentation Configuration...

Updating the LabelProvider

• The generated Label is fairly meaningless. We can fix this in the following way:
• Edit plugin.properties and update the following entry:
  • _UI_HeadlineConfiguration_type = Headline for: {0} (size: {1})
• We also need to set the substitutions To do that, open the generated HeadlineConfigurationItemProvider.java class in the org.eclipse.rmf.pror.presentation.headline.provider package
  • Find public String getText(Object object)
  • change @generated into @generated NOT (this will prevent the change from being overwritten at the next code generation)

         /**
	 * This returns the label text for the adapted class.
	 * <!-- begin-user-doc -->
	 * <!-- end-user-doc -->
	 * @generated NOT
	 */
	@Override
	public String getText(Object object) {
		HeadlineConfiguration headlineConfiguration = (HeadlineConfiguration)object;
		String[] subst = new String[2];
		subst[0] = headlineConfiguration.getDatatype() == null ? "(PLEASE SET TYPE)"
				: headlineConfiguration.getDatatype().getLongName();
		subst[1] = headlineConfiguration.getSize() + "";
		return getString("_UI_HeadlineConfiguration_type", subst);
	}

• Optionally, you can also change the icon
  • You can simply change the icon in the icons folder, but...
  • We prefer to also change the getImage() method to provide a png. pngs have better transparency handling
  • You can copy the standard icon for Presentations from one of the other Presentation Plugins.