Latest revision as of 18:22, 1 October 2009

Back

Creating a Customized Color Provider

STEM uses color providers to determine the colors used for painting the map that appears during a simulation. The system goes through the graph elements that need to be painted and adapts each one of them into a color. This color is then used as the color for painting that element. If the element is the geographic nodes, then the color is used to fill the polygons that visually represent those nodes.

A dropdown box below the painted map allows the user running the simulation to choose the type of color provider to be used. STEM comes with a small set of color providers that can be used (like the Intensity and the SEIR). Developers can add new colors by using an extension point mechanism that allows them to plug in their customized color provider.

Follow the steps below to develop and deploy a customized color provider.

Step 1. Create the provider interface

Create a new interface that extends the org.eclipse.stem.ui.adapters.color.ColorProvider interface. This interface declares the methods that should be implemented by the color provider.

For example, org.eclipse.stem.ui.adapters.color.IntensityColorsLabelsMappingColorProvider indirectly extends the above interface and does not declare any additional methods on top of those already existing in the ColorProvider interface.

Step 2. Create the adapter

This class is where the actual work of choosing and providing the right color is done. It should implement the provider interface created in step 1 and the methods declared by it (including the methods declared by the ColorProvider interface). The adapter should also extend the ColorProviderAdapter class.

In any of the implemented methods, the object that is being adapted into a color can be accessed by the getTarget() method. For example, if the adapted objects are of type Node, then the Notifier returned by this method should be cast into Node.

Step 3. Create the adapter factory

The adapter factory examines the target object (the one to be adapted) and, based on its class, returns the appropriate adapter.

Extending the AbstractColorProviderAdapterFactory abstract class will give you a set of methods that should be overridden for those class types that the adapter will be able to adapt.

Therefore, if the adapter should deal with Node classes, then the method createNodeAdapter should be overridden. The method should return an instance of the adapter that you’ve created before. It’s up to the implementer to decide if a singleton of adapter is required. In such a case, the single instance of the adapter is kept within the factory.

Another method that should be overridden by this factory is the isFactoryForType method. This method should return true if the provided class is one of the classes that the current factory deals with.

The AbstractColorProviderAdapterFactory mentioned before implements the IColorProviderAdapterFactory interface. This interface defines a method called createPropertiesComposite that returns an SWT Composite object. This is the contribution, if there is such, to the bottom bar below the map. The contributed composite may contain drop boxes with parameters that affect the specific color provider or any other widget needed by the color provider.

Step 4. Add the color provider

After you’ve implemented the different classes of the color provider, add it to the list of color providers available to the user. This list appears in a drop down box when running a scenario.

STEM uses the Eclipse plug-ins mechanism for adding new color providers. A special extension point has been created for that purpose.

Therefore, a plug-in that wishes to add color providers to STEM should extend the org.eclipse.stem.ui.colorproviders extension point.

Take a look at the following XML fraction taken from a plugin.xml file:

<extension point="org.eclipse.stem.ui.colorproviders"> <colorprovider factory="org.eclipse.stem.ui.adapters.color.IntensityColorsLabelsMappingColorProviderAdapterFactory" name="Labels Colors Mapping" provider="org.eclipse.stem.ui.adapters.color.IntensityColorsLabelsMappingColorProvider"> </colorprovider> </extension>

This entry defines an extension to the color provider’s extension point. The attributes of the colorprovider elements are:

• factory – The qualified name of the color provider adapter factory that you’ve created before.
• name – A human readable name for the color provider that will be shown to the end user in the combo box that lists the available color providers.
• provider - The qualified name of the color provider interface that you’ve created before.

References

Several color providers have already been implemented and are provided as an integral part of the disease models plug-in. These can be used as implementation references for the developer.

The org.eclipse.stem.ui.diseasemodels is a plug-in that has a package called org.eclipse.stem.ui.adapters.color. Two color providers exist within this java package:

• IntensityColorsLabelsMappingColorProvider – A color provider that provides a single color with different intensity based on the relative value of the selected state (S, E, I, R, etc.).

• SEIRColorsLabelsMappingColorProvider – A color provider that uses a predefined mapping between colors and ranges of relative value, based on the selected state (S, E, I, R, etc.).