Understanding Themes

Themes in an application enable the creation of pages and objects with custom visuals, reflecting the chosen theme. In the Draw workspace, the Brush Editor offers the option to apply Theme colors. The application sets the theme during runtime through the property @Client.Theme.

Definition

Themes are sets of visual styles that determine the appearance of pages and objects within an application, including colors and design elements.

Purpose

The purpose of Themes is to allow users to standardize and customize the visual appearance of their application's interface, maintaining consistency across various components.

Function

Themes function as a collection of design parameters that define the visual style of the application. They control aspects like color schemes and layout aesthetics.

Operation

Users operate Themes by selecting a preferred style within the application settings. In the Draw workspace, the Brush Editor allows the application of Theme Colors to various elements.

Application

Themes apply to the overall look and feel of the application. They affect everything from background colors to button styles, ensuring a cohesive visual experience.

Usage

To use Themes, users navigate to Go to Displays → Themes. They set the runtime theme via the property @Client.Theme, which determines the active visual style of the application.

Configuring Themes

The Themes function allows you to customize the appearance of your display to better suit your solution. It is available for .NET and HTML5 Clients.

When you go to Displays → Themes, you will find predefined theme palettes that are built into most of the project templates. The Blank Project is the only theme that does not have predefined theme palettes. Themes are completely customizable since you can select any color you want for each element in each column. You can use this method to create your own theme.  

The colors and themes displayed in the image below are built into new projects. The DashBoard, HighPerformance and Standard display elements are grouped together in the ItemName column. 

Enabling/Disabling Theme

To enable or disable the themes function, go to the Display Drawing > Drawing and click the checkbox located at the bottom of the left panel.

When a theme is disabled for an entire page, the theme for every object in the display will also be disabled. The colors will be the predefined colors shown in the image above.

When you change the theme in runtime, the pages and objects will keep their default configured colors. 

Individual components will have an Enable/Disable checkbox in the left panel settings.

Setting a Theme

There are a couple of different ways in which a theme can be applied to an object or project:

• Startup a Theme in a Project.
• Change a Theme in Runtime.

• Configure a Palette for an Element in a Page (Rectangle, Button, Textblock, etc).

• Pre-defined Theme and Colors.

• Specific Element Properties (Advanced Settings).

Selecting a Startup Theme

You can select a pre-created Theme to startup your project.

To do so, go to Displays → List, and click Windows button at Client Settings. It will open a popup window where the Initial Theme field is on the bottom. See the image below.

Change a Theme in Runtime

Theme selection in runtime can be done by using the syntax below in Script codes, Expression fields, or objects configuration.

To set the project to the default configuration, without a custom theme, you need to set the Client.Theme to an empty string (Client.Theme= ””) or create an empty theme table and assign it to the theme property.

@Client.Theme = "Blue";
@Client.Theme = "Dark";
@Client.Theme = "Yellow";
@Client.Theme = "";

Configuring a Palette for an Element

Configure a Palette for an Element in a Page (Rectangle, Button, Textblock, etc).

To set a theme for an element in the display, you need to open the Appearance configuration window located in the left panel toolbar, in Displays → Theme Colors. 

At the top of the Appearance configuration window, you will find a field called Theme Color. To select the color you want, you can insert the item name or click the button and browse through the available ones.

For the most part, this theme color configuration window will be available for all elements that can have their colors changed. 

Supported Components

The list below presents display objects that you are able to customize in the Theme tab and some of the most used properties:

Pre-defined Theme and Colors

When a new project is created, it already contains several built-in themes and colors. You can create a new theme with new colors, or you can change the color of the pre-configured theme. 

Some important elements that have pre-defined colors:

• DefaultColor
• DisplayBackground
• HeaderBackground
• TextForeGround
• All HighPerformance State (all of them start with HP, ex: HPOnStroke, HPOffStroke, HPDisableStroke)
• Dashboard pages (all of them start with Dashboard, ex: DashboardTitleBackground, DashboardItem…)

You can use all the colors in the image below to create any color palette you desire. 

Creating new Themes

On Displays → Theme Colors, you will find all the required information to add different theme options to your components. On the top of the display, you will find some buttons:

Theme header

New: Creates a new Themes template option.

Del: Deletes an existing Themes template.

Rename: Renames an existing Themes template.

Check: Checks all added elements to see if there is any invalid configuration.

Export Properties: Exports to the clipboard all properties that are available for selected object type. The user can see them by pasting it to Notepad, for example.

In the grid under these buttons, you will find the following columns:

Type Name: The object type that will be customized (see supported elements in the next Section).

Property Name: Object property that will be customized.

Value: Value that will be applied to the element property. It can be Colors, Font Type, Font Size, Stroke Thickness, etc. For colors you can use in Hex format (e.g.: 0000FF) or HTML Color name (e.g.: Blue).

Description: A briefly description about the component.

Uid: Custom name given to a display object in Draw Environment. UID is optional and it should be used when you want to customize specific objects. The UID is how to identify these objects. You can have many objects with the same UID, so the themes will apply the same property value to all of them. See the image below where you can find the UID field.

In the image below, you can find an example of 3 objects (in the left side) with the same Uid and another one (right side) with different Uid.

Exporting Themes

When selecting to export a page or a symbol with the dependencies enabled the Item Name (rows) will be included in the export process. To include new theme columns the specific ThemeColorName must to be selected manually. It will avoid replace the color scheme already defined in the target project.

Advanced Properties

On Run → Dictionaries → Themes and under the Advanced settings, you can customize the component properties. 

When clicking the advanced button from the Theme tab, the advanced dialog box will open based on which theme you selected with the combobox. 

It is important to notice that these properties will only be valid for the specific theme displayed in the Configuration Window (1).

By opening the advanced settings, you can easily access components such as text font, radio box marker, combo box marker, or components that are not colors or are not exposed in the drawing tool configuration.

In the example above, the customization is valid to TRadioButtons and all Ellipse. You can overwrite the basic color configuration by opening the Advanced Settings and typing the name of the property and value you desire. To filter for specific elements, you should use the Uid property to select a specific element.

To make sure the configuration you inserted is valid, always click the Check button (2). A popup message will appear with a Success/Error message.

The Export Properties button (3) will export all properties that are available, for the selected object, to the clipboard. The user can see the properties by pasting them to a text editor application (e.g.: Notepad). Below you can find some of the exported properties for the Ellipse object.

* Type: System.Windows.Shapes.Ellipse
- Properties:
. Effect, System.Windows.Media.Effects.Effect
. Fill, System.Windows.Media.Brush
. Focusable, System.Boolean
. Height, System.Double
. UseLayoutRounding, System.Boolean
. VerticalAlignment, System.Windows.VerticalAlignment
. Visibility, System.Windows.Visibility
. Width, System.Double

Demonstration Project

There is a Theme demo project available so the customer can test this feature. It contains all supported elements and shows how to use this feature in a project.

There are several different themes available in this demo project that you can use as reference to build it in your own project. Copying from Theme tables (Run → Dictionaries → Themes) and pasting it in your own folder also work great. See below some images extracted from the project.

In this section: