ClientTheme

Wisej.Core.ClientTheme

Namespace: Wisej.Core

Assembly: Wisej.Framework (4.0.0.0)

Represents a Wisej theme.

C#

public class ClientTheme : IWisejSerializable

VB.NET

Public Class ClientTheme
    Inherits IWisejSerializable

You can create a new custom theme based on an existing theme, empty, or initialized from a JSON string.

// create a new custom theme cloned from the current theme.
var myTheme1 = new ClientTheme("MyTheme1", Application.Theme);

// create a new custom theme from a JSON string.
var myTheme2 = new ClientTheme("MyTheme2", json);

You can alter any aspect of a theme by using the dynamic properties: Colors, Images, Fonts, Appearances, Settings, and Stylesheet. These properties, being dynamic, can support any field and any structure. To alter these properties in a way that doesn't break the theme, look at the theme's structure in the ThemeBuilder or a text editor. To save a custom theme you may convert it to a JSON string simply by calling the ToJSON extension method added to all objects by the Wisej framework.

Constructors

ClientTheme(name)

Default private constructor.

Name	Type	Description
name	String	Unique name of the theme.

ClientTheme(name, json)

Constructs a new theme from the name and JSON definition.

Name	Type	Description
name	String	Unique name of the theme.
json	String	JSON definition of the theme.

ClientTheme(name, baseTheme)

Constructs a new theme from the base theme.

Name	Type	Description
name	String	Unique name of the theme.
baseTheme	ClientTheme	Original theme to copy into the new theme.

Properties

Appearances

Object: Theme appearances.

This is a complex dynamic object with several child objects. The structure can get quite complicated. Before messing with the Appearances object, please study the structure of the themes using the ThemeBuilder or a text editor. Being a dynamic object, you can either create a new appearance or alter an existing appearance at any level.

// alter the border of buttons.
// note that when there is a keyword clash you can use the @ prefix.
[e-mail] = 3;
[e-mail] = 0;

// additionally, you my use a string indexer to reach any property.
Application.Theme.Appearances.button.states["default"].styles.radius = 0;

Colors

Object: Theme colors.

You can add or change any color in the current theme:

// change existing color.
Application.Theme.Colors.buttonFace = "red";

// create a new color.
Application.Theme.Colors.myCoolColor = "rgba(5,23,55,0.9)";

// since the theme objects are all dynamic and use a special DynamicObject
// class part of the Wisej Framework, you can also use a string indexer
// to address any field.
Application.Theme.Colors["buttonFace"] = "red";

FilePath

String: The file path where the theme was loaded from. If it was loaded from embedded resources this is null.

Fonts

Object: Theme fonts.

You can add or alter any font to the theme. The structure of the font definition can get complicated. Please refer to the existing themes and the ThemeBuilder to determine the structure to use. The simplest way is to change an existing theme font:

// make the window title bigger and bold.
Application.Theme.Fonts.windowTitle.size = 18;
Application.Theme.Fonts.windowTitle.bold = true;

Images

Object: Theme images.

You can add or change any theme image. Images in the theme are just URLs but can be defined in several ways:

• Absolute URL An URL starting with http: or https: pointing to an image resource.

• Relative URL An URL relative to the current site or relative to value of Images.baseUrl.

• base64 A base64 encoded embedded image.

IsMixin

Boolean: Returns if the theme is a mixin.

Name

String: The name of the theme.

ProjectPath

String: Design time project root path.

Settings

Object: Theme settings.

The Settings property allows a theme to define certain internal properties. Currently these are the supported properties:

• native-scrollbars Instructs Wisej.NET to use the native scrollbars instead of the themed scrollbars. Setting this property can have negative side effects for virtual scrolling widgets like the DataGridView. The default is false.

• overlapped-scrollbars Instructs Wisej to layout the scrollbars over the content being scrolled, similar to Windows' fluent themes or mobiles. The default is false.

Stylesheet

Object: Stylesheet rules embedded in the theme.

The Stylesheet property is a new theme property added since Wisej 2.0. It allows a theme to define a set of CSS rules, just as if Default.html specified a css file. This property has only one string array field: "rules". When the theme is rendered, the client library joins all the rules into a css string and creates a stylesheet loaded into the browser.

// create a custom css rules in the theme.
Application.Theme.Stylesheet.rules = new []{

  "body: { background-color: red };",
  ".myClass: { background-color: red };"
};

ThemesPath

String: Design time or runtime theme path.

Methods

ApplyThemeMixins(designMode, mixins)

Merges the mixin theme extensions with the theme.

Parameter	Type	Description
designMode	Boolean	If designMode = true, the theme is regenerated from the original JSON string. At design time it is possible to change the extensions applied to an already loaded theme.
mixins	String[]	Optional list of theme mixins. If null, the default theme mixins are always applied.

Returns: ClientTheme.

ApplyThemeMixins(mixins, designMode)

Merges the mixin theme extensions with the theme.

Parameter	Type	Description
mixins	IList	List of mixins to apply to the theme.
designMode	Boolean	If designMode = true, the theme is regenerated from the original JSON string. At design time it is possible to change the extensions applied to an already loaded theme.

Returns: ClientTheme.

GetColor(appearance, name, state)

Returns the resolved color defined in the theme for the specified appearance, property or style name and optionally the state.

Parameter	Type	Description
appearance	String	The appearance path that identifies the component in the theme. Nested appearances can be specified using a forward slash: i.e. window/captionbar.
name	String	The name of the property or the style value to query.
state	String	The name of the state to query. It's optional. The default is "default".

Returns: Color. A Color representing the color in the theme.

GetColor(name)

Returns the resolved theme color from the color list.

Parameter	Type	Description
name	String	The name of the color to resolve from the color list.

Returns: Color. A Color representing the color in the theme.

GetFont(appearance, name, state)

Returns the resolved font defined in the theme for the specified appearance, property name and optionally the state.

Parameter	Type	Description
appearance	String	The appearance path that identifies the component in the theme. Nested appearances can be specified using a forward slash: i.e. window/captionbar.
name	String	The name of the property value to query.
state	String	The name of the state to query. It's optional. The default is "default".

Returns: Font. A Font representing the queried font or null if not found.

GetFont(name)

Returns the resolved font defined from the font list.

Parameter	Type	Description
name	String

Returns: Font. A Font representing the queried font or null if not found.

GetImage(appearance, name, state)

Returns the resolved image defined in the theme for the specified appearance, property or style name and optionally the state.

Parameter	Type	Description
appearance	String	The appearance path that identifies the component in the theme. Nested appearances can be specified using a forward slash: i.e. window/captionbar.
name	String	The name of the property or the style value to query.
state	String	The name of the state to query. It's optional. The default is "default".

Returns: Image. A Image representing the queried image or null if not found. SVG images at runtime always return null, they are resolved only at design time.

GetImage(name)

Returns the resolved image defined from the image list.

Parameter	Type	Description
name	String

Returns: Image. A Image representing the queried image or null if not found. SVG images at runtime always return null, they are resolved only at design time.

GetInsets(appearance, state, includePadding)

Returns the size of the inset border and padding.

Parameter	Type	Description
appearance	String	The name of the appearance in the theme. Child component appearances can be specified using the forward slash, i.e. "button/icon".
state	String	The state that defines the property. It can omitted, the default state is "default".
includePadding	Boolean	Whether to include padding in the insets dimension.

Returns: Padding. Dimension of the border and optionally the padding as a Padding value

GetInstance(name, reload)

Retrieves the ClientTheme from the cache or loads it from a file in the application /Themes directory or from the embedded resources in any loaded assembly marked with the assembly:WisejResourcesAttribute.

Parameter	Type	Description
name	String	Name of the theme file or resource, without the path and the extension.
reload	Boolean	True to force a full reload of the theme.

Returns: ClientTheme. A ClientTheme instance.

GetInstance(name)

Retrieves the ClientTheme from the cache or loads it from a file in the application /Themes directory or from the embedded resources in any loaded assembly marked with the assembly:WisejResourcesAttribute.

Parameter	Type	Description
name	String	Name of the theme file or resource, without the path and the extension.

Returns: ClientTheme. A ClientTheme instance.

GetProperty<T>(appearance, name, state)

Returns the property value for the specified name and state within the specified appearance key.

Parameter	Type	Description
T		The Type of the value to retrieve.
appearance	String	The name of the appearance in the theme. Child component appearances can be specified using the forward slash, i.e. "button/icon".
name	String	The name of the property to retrieve.
state	String	The state that defines the property. It can omitted, the default state is "default".

Returns: T. The typed value of the requested property, or default(T) if not found.

GetStyle<T>(appearance, name, state)

Returns the style value for the specified name and state within the specified appearance key.

Parameter	Type	Description
T		The Type of the value to retrieve.
appearance	String	The name of the appearance in the theme. Child component appearances can be specified using the forward slash, i.e. "button/icon".
name	String	The name of the property to retrieve.
state	String	The state that defines the property. It can omitted, the default state is "default".

Returns: T. The typed value of the requested style, or default(T) if not found.

IsThemeColor(color)

Returns true if the color is a theme color.

Parameter	Type	Description
color	Color	Color to check.

Returns: Boolean. True if color is a theme color.

Since the theme may also define SystemColors, using IsThemeColor on a system color returns false, but the rendering on the browser will use the color in the theme, if defined.

IsThemeFont(font)

Returns true if the font is a theme font.

Parameter	Type	Description
font	Font	Font to check.

Returns: Boolean. True if font is a theme font.

Theme fonts (font's with the OriginalFontName starting with "@") are always rendered using the definition in the theme for their size and style. However, an application may use a theme font and change the size and style. In this case, the OriginalFontName is the theme name without the "@". If the name of the font (which could be a system name like "Arial") matches a theme font, Wisej will use the theme font but it uses the size and style set by the application.

TranslateColor(color)

Returns the resolved Color with the proper RGB values. If the color specified in color is a theme color, the value is resolved from the current theme, otherwise the original color is returned.

Parameter	Type	Description
color	Color	The Color to resolve to a usable value.

Returns: Color. A Color instance with the resolved RGB values.

TranslateFont(font)

Returns the resolved Font from the theme font. If the font is a theme font, the value is resolved from current theme.

Parameter	Type	Description
font	Font	The Font to resolve to a usable instance.

Returns: Font. A Font instance that can be used directly.

Implements

Name	Description
IWisejSerializable	Allows an object to serialize itself.