How to Adapt Your Custom Extension UI to the Current Visual Theme in Spotfire®

Introduction

The visual appearance of the Spotfire® user interface can be modified. A light and a dark visual theme are predefined. It is also possible to have a customized theme. Examples of light and dark visual themes are shown below.

When creating a custom panel or custom visual it is recommended that they follow the selected visual theme in the same way as the built-in panels and visuals. This article describes how to access styling information and how to react to visual theme changes. 

Accessing Styling Information in the Document

The styling properties set by the visual theme in a Document can be accessed from the API.

The API exposes a read-only interface to lots of styling properties for some key visual elements that are relevant when extending Spotfire with custom visuals and custom panels. Examples of styling properties are colors, fonts, borders, and spacing. Spotfire does not expose an API for changing the document theme or any style properties it implies.

Use the GetStyle method on the Document class, and pass it one of the StyleElement constants corresponding to the element in the UI, for which to retrieve style properties. For example:

 var visualContentStyle = document.GetStyle(StyleElement.VisualContent);

How this API can be used is exemplified in the SpotfireDeveloper.CustomPanelExample and SpotfireDeveloper.CustomVisualsExample, available in the SDK.

Reacting to visual theme changes

Use a trigger on the Document.PropertyNames.Styles property name to react to changes to the theme and styling properties.

Example:

this.eventManager = new ExternalEventManager();
this.eventManager.AddEventHandler(
    this.OnStyleChanged,
    Trigger.CreatePropertyTrigger(this.GetDocument(), Document.PropertyNames.Styles));

When implementing a custom visual, there is no need to add an explicit trigger on the Styles property name. The trigger returned by the GetRenderTrigger method in the VisualContent base class will fire when the theme and styling properties change.

Using style properties

The StyleProperties object returned by the GetStyle method has lots of properties that expose the styling of the associated UI element, such as colors, font information, padding, margin borders, etc.

Example:

var visualContentStyle = document.GetStyle(StyleElement.VisualContent);
var color = visualContentStyle.Color;
var backgroundColor = visualContentStyle.BackgroundColor;
var fontFamily = visualContentStyle.FontFamily;
var fontSize = visualContentStyle.FontSize;

To simplify for the case when the UI is implemented with HTML and Javascript, the ToInlineCss method can be used to produce a string that can be set as the style attribute of an HTML element.

There are also some extension methods provided by the DrawingStyleExtensions class, for instance, the GetEffectiveBackgroundColor method that computes the background color that the user will see. This method will return the background color used by the page for a visual that has a transparent background color.