Updating the style information through the API

Article ID: 2174
Last updated: 28 May, 2018
Article ID: 2174
Last updated: 28 May, 2018
Revision: 3
Views: 469
Posted: 06 Jan, 2010
by Dean J.
Updated: 28 May, 2018
by Gargani A.

Question

How to update styling information through the API?

Answer

Current versions of JTGO emphasize the use of CSS rules to style information. For example, to display network elements in red you would use:

object."ilog.tgo.model.IltNetworkElement" {

foreground: red;

}

There are three approaches to perform dynamic updates of styling information:

  • You can update the CSS rules from the API.

    The CSS is essentially ordinary String information that is parsed by the style sheet renderers. You can modify or create your own CSS rules inside a java.lang.String and update the style sheet information. There is a separate sample (Programmatically change a CSS graphic property of a business object) that follows this approach.

    This approach is appropriate for making large, global changes to the styling information, as all matching instances in the model will be updated when the style sheet information changes.

  • You can create a CSS rule that references a model property, then update the model property within the API. For more information, please see the "Styling" manual in the JTGO documentation.

    For example, most samples have a rule to define their label from the name model property.

    object."ilog.tgo.model.IltNetworkElement" {

    label: @name;

    }

    If this name property is changed in the model, the renderer will update the drawing directly.

    If desired, you can create a custom model property (for example, it can represent a color) and build the CSS rule around it. So, if you add a myColor property to an IltNetworkElement, you can write a rule to take it into account:

    object."ilog.tgo.model.IltNetworkElement"[myColor] {

    foreground: @myColor;

    }

    A sample for this is provided style1.zip. This particular sample sets the myColor property directly into existing ltNetworkElement instances in the data source through code. For the more general case, you may need to extend the predefined business class to add myColor as a custom property. For more information on doing this through XML or through the API, please see "Extending Predefined Business Classes" in the "Introducing Business Objects and Data Sources" chapter of the "Business Objects and Data Sources" manual.

    This approach is appropriate for making small, local changes to individual elements, since each individual element has its own myColor property instance.

  • Starting from TGO 7.5, there is a third way to update the styling information using the Network and Equipment APIs, namely through mutable style sheets. Mutable style sheets use the ilog.cpl.css.IlpMutableStyleSheet class which defines an in memory mutable style sheet that can be dynamically modified. Note that this option is only valid for the Network and Equipment components.

    The IlpMutableStyleSheet API allows you to set or update declarations using the setDeclaration() method. For example,  

    IlpMutableStyleSheet mutable = view.getMutableStyleSheet();
    mutable.setDeclaration("object.\"ilog.tgo.model.IltNetworkElement\"",
    "foreground", "red");

    corresponds to the following CSS declaration:

    object."ilog.tgo.model.IltNetworkElement" {
     foreground: red;
    }

    Note that the quotes have to be properly specified within the setDeclaration() call.

    By default, the mutable style sheet automatically updates the view and the new CSS declaration is taken into account by the styling engine. It is possible to modify this behavior using the setUpdateMask() method.

    To get a valid mutable style sheet, you should use IlpNetworkView.getMutableStyleSheet() or IlpEquipmentView.getMutableStyleSheet(). Please note that using any variant of method setStyleSheets() will disconnect the mutable style sheet from the view component.

    For declarations based on the object identifier, there is a utility class that computes the proper selector based on a given object identifier:

    IlpContext ctx = view.getContext();
    Object identifier = ilpobj.getIdendifier();
    String selector =
      IlpCSSUtilities.getObjectSelector(ctx.getTypeConverter(),
      identifier, null);
    mutable.setDeclaration(selector, "label", "@name");

    The setDeclaration() call above corresponds to the following CSS declaration (assuming that ilpobj.getIdentifier() returns myID):

    #myID {
    label: @name;
    }

    When you use the mutable style sheet API to update multiple declarations, you should invoke the method setAdjusting(true) to prevent the styling engine from cascading the style sheets after each call to setDeclaration(), as this might impact performance. Once all modifications have been applied, you should invoke the method setAdjusting(false) to notify the styling engine that a batch update has been completed. For example,

    String selector = "object."ilog.tgo.model.IltNetworkElement"";
    mutable.setAdjusting(true);
    mutable.setDeclaration(selector, "foreground", "#FFFF00");
    mutable.setDeclaration(selector, "labelVisible", "false");
    mutable.setDeclaration(selector, "alarmCountVisible", "false");
    mutable.setAdjusting(false);

    corresponds to the following CSS declaration:

    object."ilog.tgo.model.IltNetworkElement" {
    foreground: #FFFF00;
    labelVisible: false;
    alarmCountVisible: false;
    }

This article was:   Helpful | Not helpful
Report an issue
Article ID: 2174
Last updated: 28 May, 2018
Revision: 3
Views: 469
Posted: 06 Jan, 2010 by Dean J.
Updated: 28 May, 2018 by Gargani A.
Attached files
item style1.zip (1 kb) Download

Also listed in


Others in this category