Theme BuilderWisej.comLoading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Theme mixins are partial theme files that are always applied on top of a base theme. The concept is very similar to JavaScript mixins.
You can edit a theme mixin in two ways:
Open a theme mixin file
Click the Open Theme button on the toolbar and select the theme mixin file (.mixin.theme) to load.
Double click a theme mixin file
You can double click .mixin.theme file in a folder or in a Visual Studio project to load it in Theme Builder.
You cannot create a theme mixin using the Theme Builder. Theme mixins are created in Visual Studio by adding the Theme Mixin component to the project, or manually by creating a new .mixin.theme file.
While editing a theme mixin you can switch the base theme by selecting one of the preloaded themes, or by again clicking the Open Theme button and selecting a .theme file.
When you change the base theme, the Theme Builder updates the previews but the tree and the editor are still limited to the elements defined in the mixin.
Wisej.NET applications handle layouts on two fronts: client side and server side. The client-side layout is entirely managed in JavaScript and it is the internal layout of widgets. Server-side layout is entirely managed in .NET and it's the layout in containers.
Themes can affect both, and can break both.
All widgets in Wisej.NET are a composition of basic building blocks. For example, a wisej.web.TextBox widget (appearance: textbox) is composed of up to 4 child components, while the wisej.web.Button widget (appearance: button) is composed with 3 child components.
In the case of the wisej.web.TextBox, the 4 child components are: the container div (the one that shows the border), the inner input element (where you type the text), and optionally 2 div containers to the left and right of the input element containing the tool buttons (appearance: toolcontainer with state editor).
In the case of the wisej.web.Button, the 3 child components are: the container div (the one that shows the color and border), the label div (the one that shows the text) and the icon img element (the one that shows the optional icon).
The internal layout, that is the relation between the child components and the container, is entirely managed in JavaScript and can be affected only by the theme. You can change the padding, margin, alignment, etc. in the theme file and don't worry about the application code since the application only "sees" the widget as a whole.
If the internal layout makes the internal components "push" the size of the container to exceed the size set by the application, or if the min/max Height and Width set in the theme clash with the sizes set in the application, the widget may either get truncated or may grow past it's application size.
On the server you set the size and location of the controls in three ways: in the designers, fluently managed by a container, dynamically set by code.
When the location and size are "fluent", managed by the container because of docking, anchoring or a layout managed container, the Padding and Margin properties affect the positioning and sizing of the controls.
These two properties (Padding and Margin) are not linked to the margin and padding set in the theme. However, when a control is set to AutoSize, the size calculation is affected by several styles and properties set in the theme depending on the widget.
The most important limitation to keep in mind is that a theme cannot alter the overall application layout automatically without some coding assistance.
For example, if your application has all the text fields set to a height of 24px using the AutoSize property and you load a new theme where the height is 32px, Wisej.NET will resize the text boxes to the new height but it cannot change their location unless the application was built without setting the specific position: i.e. using a FlowLayoutPanel, or a FlexLayoutPanel, or Docking and Anchoring.
Or, if panels are docked next to each other and spaced using the Margin property, changing the margin in the theme will not change the Dock layout but it may affect the client and break the layout.
Wisej.NET can use any web font, including woff, woff2, eot, svg, ttf, depending on the browser. Usually woff or woff2 are compatible with all browsers.
However, if the web font is not available to .NET code also on the server, Wisej.NET cannot use it to calculate the size for auto-sized controls correctly and you may end up with truncated labels and wrong auto-sized controls.
In this case, you also need to download and install the ttf version of the font and make it part of your server installation.
Wisej.NET will automatically match the web font to the ttf version to make sure that auto sizing works properly. Just make sure that both font formats are available to avoid wrong sizing of text in controls.
Starting with Wisej.NET a font does not need to be installed on the server anymore to be used. See https://docs.wisej.com/docs/releases/whats-new-in-3.2/enhanced-font-support
Sometimes you may need to add some complex additional CSS style that is not directly supported by the Wisej.NET theme system. In this case you can add a CSS string of almost any complexity in relation to a state, including adding :after and :before pseudo elements.
A very good example is in the Material-3 theme under the inputElement shared appearance key:
Wisej.NET will convert the CSS definition (which is JSON in the theme file) to the equivalent style sheet properties in the browser when the state is applied to the widget.
You can use themed colors in the custom CSS as long as the CSS property ends with "color". For example, you can set "background-color": "buttonFace" (or "backgroundColor": "buttonFace" since Wisej supports both notations) and the theme system will replace "buttonFace" with the corresponding CSS color set in the theme before generating the style sheet in the browser.
You can use themed images in the custom CSS as long as the CSS property ends with "image". For example, you can set "background-image": "icon-print" (or "backgroundImage": "icon-print" since Wisej.NET supports both notations) and the theme system will replace "icon-print" with the corresponding image source set in the theme before generating the style sheet in the browser.
Wisej.NET applications can add all sorts of animations to its components using the Animation extender. However, you can also add simple animations to a theme or a mixing by using the transform, transition and css styles.
You can find an example of a simple animation in all the built-in themes under the button appearance:
By applying a transformation or transition to a widget in conjunction with a state you can add some "functional" animations to all the widgets in your app.
The theme system supports the inheritance of appearances allowing a theme creator to consolidate common styles in shared appearances. You can find an example of this feature in the built-in themes for the icon-dark, icon-light, scrollbar, scrollarea, datechooser, and inputElement (in Material-3) appearances.
You can also refer to a child component appearance using the forward slash: i.e. inherit: "window/title" inherits the styles and properties from the title component in the window appearance.
You can use the Wisej JavaScript source code and qooxdoo source code to inspect the appearances and child components used by a widget. Usually the appearance key is set either by refining the appearance property or in code:
All the child components are named and created in the _createChildControlImpl method:
The number of styles, states and properties, in conjunction with child components, with their own states, styles, properties and child components makes it a virtually unlimited system. Therefore, if you need to implement very advanced widgets and themes, dealing with the source code is a necessity.
The name of the child component is also the name of the child appearance. For example, the appearance of the drop down button in a combobox is "combobox/button", and in the theme definition it's under the appearances/button/components/button branch.
You can edit a theme in several ways:
Open a theme file
Click the Open Theme button on the toolbar and select the theme file to load.
Double click a theme file
You can double click a .theme file in a folder or in a Visual Studio project to load it in Theme Builder.
Select a preloaded theme
Every time you load a theme in the Theme Builder, it's added to the list of preloaded themes. You can switch easily between themes by selecting from the drop down.
The full path of the current theme is displayed in the status bar at the bottom left of the main window.
When you start the Theme Builder application, it shows the main window displayed below. Initially it shows the default preview pane containing a sample of Wisej controls in two floating windows in a Wisej.Web.Desktop container.
The tree on the left side shows all the elements in the current theme and the property grid on the left-bottom side displays the properties or items of the selected tree node.
You can change any aspect of the theme through this window and see immediately what effect your changes have on any Wisej control or on your application while it's running.
Wisej.NET Theme Builder is a self-contained Windows executable that allows you to edit or create Wisej.NET themes and theme mixins.
The theme system in Wisej.NET is quite powerful and goes beyond simple CSS, LESS or SASS. It is entirely contained in a single JSON file, including colors, images, fonts and appearances. You can virtually change any visual aspect of Wisej controls through a single theme file.
The Theme Builder application doesn't need to be installed. It's a single self-contained executable that you can freely distribute to other developers or graphic designer professionals.
One of the most powerful features of the Theme Builder is the possibility to theme a running Wisej application.
The second preview tab (Browser) lets you load a Wisej application in the Theme Builder and see what it would look like with any other theme.
You can load a different theme, and you can modify a theme and see the result immediately in the running application.
The actual theme of the application is not changed. Your edits and theme selection is only applied to the browser view in the Theme Builder. To change the theme of the application you still need to deploy the changed theme.
Make sure to periodically check for updates.
To create a new theme, click the Create Theme button - the first on the top toolbar - to open the New Theme Dialog:
Enter the file name or full file path in the first field and select the base theme in the second field. You can select one of the preloaded themes or select a theme from a file.
A new theme must always copy the initial structure from an existing theme.
The preview pane on the right side of the Theme Builder lets you see any change you apply to the theme in real time. There are three built-in previews, but you can edit or create your own preview script and you can preview your running application right in Theme Builder.
Since Wisej.NET is an open system being able to integrate with countless JavaScript widgets out there, we may need to preview custom widgets and extensions in order to theme them using either a new theme or a theme mixin.
For this purpose, the Theme Builder supports loading or editing preview scripts. You may edit the existing built-in scripts, or use them as a reference to see how they have been built, or you can create new scripts.
You can change the current preview view using the toolbar above the preview area:
The first preview script loads a number of common controls into two floating windows inside a Desktop control. Use this preview to see the result of your changes to active and inactive windows, many common controls, and the Desktop control and Taskbar.
When you edit a preview script, remember to save it to a file, otherwise when you switch back to another script view your changes will be lost.
The second preview script shows all the controls that didn't fit in the floating windows in the Windows preview script, plus popup widgets (i.e. Tooltip, MessageBox, AlertBox, ...).
The third preview script shows a grid with some sample data and a representation of the most used column types. You can sort, move and resize the columns to see how your changes affect a grid also during normal usage.
You can edit the existing preview script, or create and load your own custom preview scripts. The language is JavaScript and runs directly inside the browser instance used in the preview pane.
The code below:
Shows the preview below:
The root element in the preview panel is called root. To show any widget in the preview panel you have to add it to root.
The preview panels in Theme Builder load the built-in preview scripts (JavaScript) to show a predefined selection of controls and layouts.
The Color Picker in the Theme Builder has three tabs (two when used to edit a Theme Color): Color, Web Color, and Theme Color.
The first tab shows a full-fledged color picker (a modified version of ) that lets you build a valid #RRGGBB or rgb(r,g,b) or rgba(r,g,b,a) color notation.
Drag the picker on any window to select a color from another application. User the Opacity and Lightness sliders to adjust the transparency level and the color brightness.
The second tab shows the list of all known, valid, and cross-browser Web Colors.
The third tab shows all the named colors defined in the theme itself.
When using the new Edge/Chrome viewer in the Theme Builder preview panels you can press F12 or press the button to open the Developer Tools window and inspect the preview.
| Tool | Description | |
|---|---|---|
Live preview is not available for the .
The first time you run ThemeBuilder you may see a message box asking you to install the Microsoft WebView2 SDK from this location:
| Tool | Description |
|---|
You can modify this preview script by clicking the "Edit custom preview script" button in the toolbar. It will load the Windows script into the preview script editor.
You can modify this preview script by clicking the "Edit custom preview script" button in the toolbar. It will load the Windows script into the preview script editor.
You can modify this preview script by clicking the "Edit custom preview script" button in the toolbar. It will load the Windows script into the preview script editor.
| Element | Description |
|---|
Use the save button to update the preview while editing the custom preview script.
Properties are specific to the widget that is using the appearance key where the properties are defined. Some properties are translated to "style" settings on the widget DOM element, while others may only affect internal behavior.
Each widget decides how to use a property. Unlike styles, properties are not limited by CSS specs.
This is the list of the common (shared) properties by all widgets. However, specific widgets may have additional themeable properties that are not listed here. See the Other Properties section for more information on how to find out which properties to use in a theme.
padding
Property group: [ paddingTop, paddingRight, paddingBottom, paddingLeft ]
paddingTop
The top padding in pixels.
paddingRight
The right padding in pixels.
paddingBottom
The bottom padding in pixels.
paddingLeft
The left padding in pixels.
backgroundColor
The background color of the rendered widget. It overrides the backgroundColor set in the styles and it is overridden by the BackColor set in the application.
textColor
The text color of the rendered widget. It is overridden by the ForeColor set in the application.
font
The widget's font. The value is either a font name defined in the fonts section or a full font definition.
opacity
A decimal between 0 (invisible) and 1 (fully visible) that defines the opacity of the widget. See CSS3 opacity.
cursor
The name of the cursor to show when the pointer is over the widget. Allowed values: "default", "crosshair", "pointer", "move", "n-resize", "ne-resize", "e-resize", "se-resize", "s-resize", "sw-resize", "w-resize", "nw-resize", "nesw-resize", "nwse-resize", "text", "wait", "help", "not-allowed", "row-resize", "col-resize".
nativeContextMenu
Determines whether the native context menu should be enabled for this widget. Default: false.
minWidth
The minimum width of the widget in pixels.
maxWidth
The maximum width of the widget in pixels.
width
The preferred width of widget in pixels. The actual size may change depending on the minWidth, maxWidth and the layout engine used by the widget. It is overridden by the Width property set in the application.
minHeight
The minimum height of the widget in pixels.
maxHeight
The maximum height of the widget in pixels.
height
The preferred height of widget in pixels. The actual size may change depending on the minHeight, maxHeight and the layout engine used by the widget. It is overridden by the Height property set in the application.
allowStretchX
Property group: [ allowGrowX, allowShrinkX ]
allowGrowX
Determines whether the widget can grow horizontally. It is used by the internal layout engines.
allowShrinkX
Determines whether the widget can shrink horizontally. It is used by the internal layout engines.
allowStretchY
Property group: [ allowGrowY, allowShrinkY ]
allowGrowY
Determines whether the widget can grow vertically. It is used by the internal layout engines.
allowShrinkY
Determines whether the widget can shrink vertically. It is used by the internal layout engines.
margin
Property group: [ marginTop, marginRight, marginBottom, marginLeft ]
marginTop
The top margin in pixels.
marginRight
The right margin in pixels.
marginBottom
The bottom margin in pixels.
marginLeft
The left margin in pixels.
alignX
Determines the horizontal alignment of the item in the parent layout. It is used (or ignored) by the internal layout engines.
alignY
Determines the vertical alignment of the item in the parent layout. It is used (or ignored) by the internal layout engines.
decoration
Sets the text decoration for text in the widget. Allowed values: "none", "underline", "line-through", "overline".
icon
The URL or theme image name of the icon to show in the widget. It's supported only by widgets that include a child Image element: buttons, labels, check boxes, radio buttons, ...
gap
The space, in pixels, between the icon and the label in the container widget. It's supported only by widgets that include a child Image element: buttons, labels, check boxes, radio buttons, ...
show
Determines whether the widget shows the icon, label, or both. Allowed values: "both", "label", "icon". It's supported only by widgets that include a child Image element: buttons, labels, check boxes, radio buttons, ...
iconPosition
Determines the position of the icon in relation to the text. Allowed values: "top", "right", "bottom", "left", "top-left", "bottom-left", "top-right", "bottom-right". It's supported only by widgets that include a child Image element: buttons, labels, check boxes, radio buttons, ...
center
Determines whether the content should be rendered centrally. It is used (or ignored) by the internal layout engines.
All the properties that are marked themeable in the widget's JavaScript code can be defined in a theme.
One way to find which properties are supported is to use the excellent qooxdoo API viewer and search for a base widget that corresponds to the Wisej.NET control. When using the API Viewer, note that themeable properties show a pencil icon.
Another way is to look at the JavaScript source code for the Wisej.NET widgets and their base classes to determine which properties are themeable.
Property groups are composite properties that can set the values of other properties using a shorthand array. The code below shows a property group used to set related properties. In a theme definition file you can set a property group or a single property or both; they are applied in the order they are declared.
The definition above is equivalent to:
Property groups that contain values for the four sides of an element follow the TRBL pattern (top, right, bottom, left).
States determine which styles (CSS class) and which properties to apply to a widget. During the lifetime of a widget, the state(s) that the widget assumes change dynamically depending on many factors: pointer, property settings, focus, etc.
A widget can assume several states at the same time, i.e. it can be Focused and Hovered at the same time. The state of a widget is usually changed by the widget implementation, but it can also be manipulated by the application:
There are some common states that are supported by most widgets, while individual widgets may add their own states. For example, the wisej.web.TabControl.js widget (corresponding to the Wisej.Web.TabControl control) adds states corresponding to the orientation and alignment of the tabs: barTop, barBottom, barRight, barLeft.
States may also get propagated to internal child widgets, in order to allow the child widgets to adapt their behavior and UI to the owner widget's state.
Here you can find the list of the common (shared) states by most widgets. However, specific widgets may have additional states that are not listed here.
default
The default state is always applied first. The styles and properties defined in the default state may be overridden by the additional states.
active
This is the state used by a Window, which correspond to Wisej.Web.Form, when it is active. Usually there can be only one active window.
maximized
The maximized state is applied to maximized Wisej.Web.Form controls.
disabled
This is the state applied to disabled widgets. The built-in themes set the opacity property to render the widget grayed out.
hovered
This state is applied to a widget when the pointer is over the element, and removed when the pointer moves out.
checked
This state is applied to widgets that support a checked state: check boxes, menu items, tree nodes, ...
undetermined
This state is applied to widgets that support the undetermined state: check boxes, tree nodes, ...
pressed
This state is applied to widgets that support the pressed state: buttons, sliders.
See how the provided themes use this state to emulate the movement of a button when it is pressed:
focused
The focused state is applied to all editable widgets when they gain the focus.
invalid
The invalid state is applied to any editable widget when the application sets the Invalid property to true. Typically a theme can render this state by adding a red border, or an icon, or by changing a color on the widget.
contextmenu
The contextmenu state is applied to widgets that have been assigned a contextual menu.
vertical
This state is applied to widgets that support the vertical state: tab control, sliders, scrollbars.
horizontal
This state is applied to widgets that support the horizontal state: tab control, sliders, scrollbars.
barTop
The barTop state is assigned to a tab control widget when tabs are docked to the top, regardless of the orientation.
barLeft
The barLeft state is assigned to a tab control widget when tabs are docked to the left, regardless of the orientation.
barRight
The barRight state is assigned to a tab control widget when tabs are docked to the right, regardless of the orientation.
barBottom
The barBottom state is assigned to a tab control widget when tabs are docked to the bottom, regardless of the orientation.
selected
The selected state is applied to child items when they are selected: list items, tree nodes.
sortable ****The sortable state is applied to columns that can be sorted by the user.
sorted
The sorted state is applied to columns when they are sorted.
sortedAscending
The sortedAscending state is applied to columns when they are sorted ascending.
opened
The opened state is applied to tree nodes when they expanded.
up, down, left, right
These states are applied to the scrollbar buttons depending on the orientation of the scrollbar.
showingPlaceholder
The showingPlaceholder state is applied to editable controls when they show the placeholder (empty value with watermark text).
drag
The drag state is applied to a widget when it is the target of a drag operation.
Many controls in Wisej have a Tools collection to display small icons inside the control that can be connected to custom actions. These tool icons are managed in a widget using the appearance key "ToolContainer".
You can customize the tools in relation to their container using the following states in the ToolContainer appearance.
editor
ComboBox, DateTimePicker, TextBox
datagrid
DataGridView
caption
Form
listbox
ListBox
listview
ListView
panel
Panel
treeview
TreeView
calendar
MonthCalendar
Styles are all predefined in Wisej.NET and roughly correspond to CSS3 styles. Wisej.NET creates a dynamic CSS class and applies it to the widgets that use the appearance key and match the state that contains the style. It's very similar to using CSS classes with HTML elements.
Some styles can be overridden by properties: i.e. The backgroundColor style is overridden by the backgroundColor property. The main differences between styles and properties are:
An application cannot change a style value, only a theme can.
Styles go into CSS classes named using the appearance key + state that contains the style, while properties are rendered on the widget's DOM element.
Styles are limited to the Decorators supported by the Wisej.NET JavaScript implementation. Decorators are JavaScript classes in charge of converting the styles set in the theme to CSS values.
Properties are unlimited. The JavaScript that defines a widget can add any number of themeable properties.
This is the full list of all the supported styles:
gradientStart
Property group: [startColor, startColorPosition]
Property groups are composite properties that can set the values of other properties using a shorthand array. See Property Group for more information.
gradientEnd
Property group: [ endColor, endColorPosition ]
startColor
Start color of the background gradient.
startColorPosition
Position in percent or pixels where to start the color. It's a number, do not use "%" or "px". Default: 0.
endColor
End color of the background gradient.
endColorPosition
Position in percent or pixels where to start the color. It's a number, do not use "%" or "px". Default: 100.
orientation
The orientation of the gradient. Allowed values: "horizontal", "vertical"
colorPositionUnit
Defines if the given gradient color position values are in % or px.
backgroundColor
Color of the background.
backgroundImage
The URL or theme name of the background image
backgroundRepeat
How the background image should be repeated. Allowed values: "repeat", "repeat-x", "repeat-y", "no-repeat", "scale".
backgroundSize
The background size. Allowed values: "auto", CSS size, i.e. "60px 120px", "cover", "contain". See CSS3 background-size.
fillColor
The fill color for background SVG images.
backgroundPosition
Property group: [ backgroundPositionX, backgroundPositionY ]
backgroundPositionX
Either a string or a number, which defines the horizontal position of the background image. Allowed values: Integer, "center", "left", "right".
backgroundPositionY
Either a string or a number, which defines the vertical position of the background image. Allowed values: Integer, "center", "top", "bottom".
borderImage
Specify an image as the border around an element. This style allows you to specify an image to be used instead of the normal border around an element. See CSS3 border-image.
slice
Property group: [ sliceTop, sliceRight, sliceBottom, sliceLeft ]
sliceTop
The top slice line of the border image in pixels. The slice properties divide the image into nine regions, which define the corner, edge and the center images.
sliceRight
The right slice line of the border image in pixels. The slice properties divide the image into nine regions, which define the corner, edge and the center images.
sliceBottom
The bottom slice line of the border image in pixels. The slice properties divide the image into nine regions, which define the corner, edge and the center images.
sliceLeft
The left slice line of the border image in pixels. The slice properties divide the image into nine regions, which define the corner, edge and the center images.
repeat
Property group: [ repeatX, repeatY ]
repeatX
Specifies how the images for the sides and the middle part of the border image are scaled and tiled horizontally. Allowed values: "stretch", "repeat", "round".
repeatY
Specifies how the images for the sides and the middle part of the border image are scaled and tiled vertically. Allowed values: "stretch", "repeat", "round".
fill
Specifies whether to use the central part of the border image to fill the element. Allowed values: true, false. Default: true.
borderImageMode
Configures the border image mode. Allowed values: "horizontal" (left and right borders), "vertical" (top and bottom borders), "grid" (all edges).
radius
Property group: [ radiusTopLeft, radiusTopRight, radiusBottomRight, radiusBottomLeft ]
radiusTopLeft
Top left corner radius in pixels.
radiusTopRight
Top right corner radius in pixels.
radiusBottomRight
Bottom right corner radius in pixels.
radiusBottomLeft
Bottom left corner radius in pixels.
shadowColor
The color of the shadow.
shadowSpreadRadius
The spread radius of the shadow in pixels.
shadowBlurRadius
The blur radius of the shadow in pixels.
shadowLength
Property group: [ shadowVerticalLength, shadowHorizontalLength ]
shadowVerticalLength
Vertical length of the shadow in pixels.
shadowHorizontalLength
Horizontal length of the shadow in pixels.
inset
Specifies whether the shadows are drawn inside the border. Allowed value: true, false. Default: false.
left
Property group: [ widthLeft, styleLeft, colorLeft ]
right
Property group: [ widthRight, styleRight, colorRight ]
top
Property group: [ widthTop, styleTop, colorTop ]
bottom
Property group: [ widthBottom, styleBottom, colorBottom ]
width
Property group: [widthTop, widthRight, widthBottom, widthLeft ]
widthTop
Top width of border in pixels.
widthRight
Right width of border in pixels.
widthBottom
Bottom width of border in pixels.
widthLeft
Left width of border in pixels.
style
Property group: [ styleTop, styleRight, styleBottom, styleLeft ]
styleTop
Top style of the border. Allowed values: "none", "solid", "dotted", "dashed", "double", "inset", "outset", "ridge", "groove".
styleRight
Right style of the border. Allowed values: "none", "solid", "dotted", "dashed", "double", "inset", "outset", "ridge", "groove".
styleBottom
Bottom style of the border. Allowed values: "none", "solid", "dotted", "dashed", "double", "inset", "outset", "ridge", "groove".
styleLeft
Left style of the border. Allowed values: "none", "solid", "dotted", "dashed", "double", "inset", "outset", "ridge", "groove".
color
Property group: [ colorTop, colorRight, colorBottom, colorLeft ]
colorTop
Top color of the border.
colorRight
Right color of the border.
colorBottom
Bottom color of the border.
colorLeft
Left color of the border.
innerWidth
Property group: [ innerWidthTop, innerWidthRight, innerWidthBottom, innerWidthLeft ]
innerWidthTop
Top inner border width in pixels.
innerWidthRight
Right inner border width in pixels.
innerWidthBottom
Bottom inner border width in pixels.
innerWidthLeft
Left inner border width in pixels.
innerColor
Property group: [ innerColorTop, innerColorRight, innerColorBottom, innerColorLeft ]
innerColorTop
Top inner border color.
innerColorRight
Right inner border color.
innerColorBottom
Bottom inner border color.
innerColorLeft
Left inner border color.
innerOpacity
The opacity of the inner border as a decimal value. Default: 1.
innerStyle
Property group: [ innerStyleTop, innerStyleRight, innerStyleBottom, innerStyleLeft ]
innerStyleTop
Top style of the inner border. Allowed values: "none", "solid", "dotted", "dashed", "double", "inset", "outset", "ridge", "groove".
innerStyleRight
Right style of the inner border. Allowed values: "none", "solid", "dotted", "dashed", "double", "inset", "outset", "ridge", "groove".
innerStyleBottom
Bottom style of the inner border. Allowed values: "none", "solid", "dotted", "dashed", "double", "inset", "outset", "ridge", "groove".
innerStyleLeft
Left style of the inner border. Allowed values: "none", "solid", "dotted", "dashed", "double", "inset", "outset", "ridge", "groove".
clip
Specify the painting area of the background. Allowed values: "border-box", "padding-box", "content-box", "initial", "inherit".
transform
CSS3 transform string. See CSS3 transform.
transition
CSS3 transition string. See CSS3 transition.
This style allows a theme to define simple animations.
css
Custom CSS3 rules.
The css style can define complex CSS3 rules and pseudo element. There is no limit to what can be defined in the css style. This is the animation and pseudo element used in the Material-3 theme when an editable widget gains the focus:
When setting CSS properties directly, Wisej supports both the HTML notation (i.e. "background-color") and the DOM notation (i.e. "backgroundColor").
Property groups are composite properties that can set the values of other properties using a shorthand array. The code below shows a property group used to set related properties. In a theme definition file you can set a property group or a single property or both; they are applied in the order they are declared.
The definition above is equivalent to:
Property groups that contain CSS values for the four sides or four corners of an element follow the TRBL pattern (top, right, bottom, left).
Creates a new theme.
Loads an existing theme.
Saves the theme being edited.
Saves the theme being edited to a different file.
Dropdown list with the preloaded themes. You can switch the theme being edited using this list.
Reloads the current theme. It may be useful if the preview window gets messed up after a while.
Enables or disables the live-update mode. When live update is ON, the preview window shows any change to the theme immediately. Turn it OFF to apply several changes in a sequence and save the time it takes to refresh the preview.
Enables or disables right-to-left alignment and layout. When Right To Left is ON, the preview scripts create the widgets setting the rtl and rtlLayout property to true, which adds the "RightToLeft" state to the widgets that support RTL mode.
Adds a new element or a new value to the theme.
A new element can be a Color, an Image, a Font, an Appearance, a State or a Component.
A new value can be a Style or a Property. The type of element or value that is added depends on the selected node in the components.
Deletes the selected element.
Renames the selected element.
Demotes the selected components. This button is enabled only when the selected element is a child component. Since components are hierarchical, this action lets you change the parent of a component.
Promotes the selected components. This button is enabled only when the selected element is a child component. Since components are hierarchical, this action lets you change the parent of a component.
Moves the selected element down. This button is enabled only when the selected element is a state a component or an appearance.
Moving a state up or down changes the order in which the styles and properties associated with the state are applied to the widget.
The Default state is always the first state in the list.
Moves the selected element up. This button is enabled only when the selected element is a state a component or an appearance.
Moving a state up or down changes the order in which the styles and properties associated with the state are applied to the widget.
The Default state is always the first state in the list.
Shows the full appearance path of the last clicked widget in the preview window. The appearance key may not be present in the theme definition tree for several reasons: a) it could be a custom key defined in your application or an extension; b) it's a child component that is not themed (doesn't need to be); c) it's a new widget that wasn't themed.
The Last Clicked information allows you to add the specific appearance key when needed.
Selected the browser for the preview: Edge or IE. |
Navigates backward and forward. |
Changes the zoom level. |
Opens the Edge/Chrome dev tools window. |
New Feature: Detaches the preview allowing you to use it on a separate monitor. |
Selects the browser: IE or Edge/Chromium. |
Shows the main view. |
Shows the controls view - contains a number of additional controls. |
Shows the grid preview. |
Changes the zoom level in the preview window. |
Opens a JavaScript editor preloaded with the current preview script. You can modify the built-in script or write a new one. |
Loads a custom preview script (.js). |
Saves the current preview script to a JavaScript file. |
Reloads the current preview script. |
Deletes the selected text and copies it to the clipboard. |
Copies the selected text to the clipboard. |
Pastes the text in the clipboard at the current location. |
Tries to format the selected text. |
Reverses the last operation. |
Reapplies the previous operation that was reverted using Undo. |
Changes the size of the font in the editor. |
Updates the preview panel with the preview script in the editor. It doesn't close the editor. You can keep changing the script and click save to see the result in the preview panel. |
Wisej.NET themes can use relative image URLs, absolute image URLs, embedded base64 images, and named images. The supported image formats are: png, gif, svg, jpg and bmp. The table below describes how to use each image type.
| Image Type | Description |
|---|---|
Example of named images:
Notice the baseUrl property under images. It's the root URL that Wisej.NET uses for named images that are defined using a relative URL. i.e. "checkbox": "images/cool-checkbox.png".
Using the baseUrl allows you to switch the entire icon set simply by changing the baseUrl.
The Font Picker has three tabs: Choose Font, Google Fonts, and Theme Fonts. When you are editing a theme font, only the Choose Font and Google Fonts tabs are visible. When selecting a font on a widget, only the Choose Font and Theme Fonts tabs are visible.
The Choose Font tab lets you build a font definition, the Google Fonts tab lets you choose and optionally embed a google font, and the Theme Fonts tab lets you select one of the fonts defined in the theme.
| Element | Description |
|---|---|
The Google Fonts tab allows you pick one of the fonts offered by Google Fonts and either link the source of embed the font in the theme. We usually recommend embedding the font: it loads faster and your users will not require an open internet connection to download the font from Google.
Make sure to use both, the woff and the ttf version of web fonts to make auto sizing work properly. See Tips & Tricks for more details.
The Theme Fonts tab is visible when selecting a font for the font property of a specific appearance.
The settings collection allows you to use placeholders for common values used throughout the theme. By using placeholders for common values, you can alter a theme by tweaking these values in one place instead of having to modify all the styles or properties that are affected by the change.
Define your placeholders using the editor tab in the "settings" section. Use either a string, an array, or a numeric value. The value you specify in that section will replace the placeholder that you use in the theme.
For example, "borderRadius": 3 will replace the "$borderRadius" placeolder in "radius": "$bolderRadius".
"[name]": [value]
The value can be a number, an array or a string.
Use the settings in the theme by prefixing the name with "$" and always in a string.
Now you can change the settings in one place and the entire theme will get automatically updated!
Wisej.NET themes can use Web Fonts, System Fonts, Custom Fonts and Named Fonts. The table below describes each font type.
| Font Type | Description |
|---|---|
Any font property in the theme definition can use the following font definition map:
Please note that if the web font added to the theme is not available to the .NET code on the server, Wisej.NET cannot use it for autosize controls. You need to download the ttf font file and make it part of the server installation. Update: Starting with Wisej.NET 3.2 Enhanced Font Support allows you to use fonts without a server installation.
Notice the family source array, you can specify multiple format files for the same font (IE doesn't support woff2 so you always need .eot fonts to see the font in the Theme Builder or the designer).
You can export and import all the images used in the theme with one operation. This functionality allows graphic designers to work on the icons independently.
Select the Images tab and click either the export or import buttons in the toolbar.
When you click the export button, the Theme Builder will ask you to select a destination folder and then it will export all the images defined in the theme under the images section to the selected folder.
The name of the image is the file name. Files with the same name as the images being exported will be overwritten.
When you click the import button, the Theme Builder will ask you to select the folder with the images to import. All files with these extensions will be base64-encoded and imported in the images section: .jpg, .jpeg, .gif, .png, .svg.
Any image already present in the theme with a name matching an image being imported will be replaced.
You can add any CSS style to a theme in the Stylesheet section. It allows a theme to also style third party widgets and to define CSS rules outside of the .
Click the ... button next to rules in the property grid to show the code editor. In the code editor you can enter plain CSS rules. The image below shows a rule for the .qx-button class. It is applied to all Wisej buttons that don't have a particular active state.
We recommend to use the Stylesheet section only to style third-party widgets. If you use it to change the styles created by the theme system you risk breaking the appearance of the widget and for the CSS rules to be overridden by the theme system.
The Image Picker in the Theme Builder has two tabs: Image Picker and Theme Images
The first tab (Image Picker) lets you pick an image in 3 different ways:
Import from URL
You can type in any image URL, the image picker will download the image and save it in the theme as an embedded base64 string.
Import from Clipboard
Click the paste button next to the field to copy an image that is in the clipboard as a an embedded base64 string.
Link to URL
The last option lets you type in an image URL, or a theme image. The image picker will show the preview of the image immediately. However, the image is added to them as a URL.
The second tab (Theme Images) lets you select an image from the list of icons embedded in the theme.
In addition to the images section in the theme properties, the Theme Builder provides an Image List panel that lets you manage the named images visually.
The Image List shows a preview of all the images (including SVG images) and allows you to import or export all the images at once. It's a great way to update a theme. Simply export all the images in a folder, replace them with new images using the same name, and import them back. Wisej Theme Builder will replace all the icons and images in the theme.
| Element | Description |
|---|
Some themes may require certain CSS values and rules or a combination of CSS styles that cannot be achieved using the predefined styles and properties in the theme engine and the widgets.
Custom CSS can be added to the css style in relation to a . Wisej will use the CSS exactly as entered in the theme when it applies the state to the widget.
The Material-3 theme uses this feature to add an animated focus bar under input fields and under the tabs in the tab view widget.
Note that the syntax in the CSS editor is JSON. For example to set style background-color to red, you have to enter "background-color": "red".
You can use theme colors as well as rgb, rgba, named colors, #RRGGBB, and #RRGGBBAA definitions.
The Theme Builder includes a code editor that you can use when you need to manipulate the theme source code directly. It's particularly useful when you have to copy & paste sections of the theme or you want to apply changes quickly.
| Element | Description |
|---|
The Wisej.NET theme system is quite sophisticated and goes beyond simple CSS or SASS. Themes in Wisej.NET are single JSON files that define colors, images, fonts, and appearances that control all visual aspects of a Wisej.NET control.
Themes are also tightly integrated with the designer and the server side of the controls. The designer in Visual Studio is capable of rendering themes very accurately and the server code behind Wisej.NET controls reads and manages all the metrics and values associated with the appearances and states of all the controls.
, and can be indirected in their respective sections and let a theme designer change their values in a single place to update all the references throughout the theme. While can inherit from other appearances.
The ThemeBuilder application that is included with Wisej.NET is a powerful tool that allows web developers and designers to manage and preview themes as well as apply their changes to a running application to see how the theme works live.
Another unique feature of the theme system is the support for the Wisej.NET supports unlimited, dynamically loaded, mixins. This feature allows developers to create small partial theme files that are targeted to a component, or a part of the application, and can be distributed bundled as embedded resources. Wisej.NET discovers the mixins (runtime and design time) and applies them to the base theme.
This document describes the structure of Wisej.NET's theme files. However, you most likely will not need to edit the theme manually. All aspects of a theme are managed by the Theme Builder application.
The images section contains the list of images used throughout the theme. Each image entry has a name and value that defines the image. It is not necessary to indirect images, all the values that are supported in the images section can be used directly as image sources. However, it's very convenient to specify an image only once and reuse by name.
The image value can be:
Full URL
The full URL of an image can refer to any image anywhere. You can use a http or https or any other protocol that returns an image that can be displayed by a browser. The URL can also specify custom parameters.
Partial URL
A partial URL is the same as the Full URL, except that it doesn't specify the protocol and the server. The URL is either relative to the application using the theme, if baseUrl is not specified, or to the baseUrl setting in the theme.
Base64 Embedded Image
The image value can be the image itself, in any format, using the base64 notation. The advantage of using this format is that all the images are included in the single theme file. It's a lot easier to export and to manage. All the themes that we provide use embedded SVG images.
The application can use any theme image simply by name. Wisej's client framework resolves the image dynamically at runtime. It uses heavy caching and it's extremely fast.
The colors section contains the list of colors used throughout the theme. Each color entry has a name and value that defines the color. It is not necessary to indirect colors, all the values that are supported in the colors section can be used directly in any color property. However, it's very convenient to specify colors in one place and reuse them by name.
The color value can be:
#RRGGBB
rgb(red, green, blue)
rgba(red, green, blue, alpha)
The application can use any theme color simply by name. Wisej.NET's client framework resolves the color dynamically at runtime. It uses heavy caching and it's extremely fast.
The colors section contains the list of fonts used throughout the theme. Each font entry has a name and the font definition properties that defines the font. It is not necessary to indirect fonts, all the values that are supported in the fonts section can be used directly in any font property. However, it's very convenient, especially for fonts, to specify the definition in one place and reuse them by name.
Fonts are a bit more complex than colors and images. The basic definition of a font contains the name, the size in pixels or points, and the family array:
However, the theme engine also supports the full font definition:
The font definition above creates a new theme font named menu, with size 13px, line height 23px, bold, italic and underlined, with a shadow and using Roboto, Slabo and Arial, in that order.
The sources property is an array of font sources. Each source is defined as a map with the family name and the corresponding URLs. Wisej.NET supports the following formats: "eot", "woff", "ttf", "svg", "woff2".
Wisej.NET supports using pixels (px), points (pt), and the default font size (em) in the font definitions.
Appearances are keys that group a set of styles and properties to apply to a widget depending on its state. A widget defines the name of the appearance key that it wants to use. i.e. the Wisej.web.Button widget uses the "button" appearance key. A widget can change which key it uses at any time. There is no limit to the number of appearances in a theme.
An appearance can inherit from another appearance to simplify settings. For example, in the built-in themes, the "button-ok" appearance inherits from the "button" appearance and changes the default background color and the hovered background color.
All styles and properties are grouped in states. The states represent common states, such as "pressed", "clicked", "focused", "hovered", ... and more widget specific states such as "vertical", "active", ... A widget can have multiple states at the same time. The theme engine applies the styles and properties under a matching state in the order they are defined in the theme file.
Wisej .NETsupports composite states to fine tune the order in which styles and properties are applied. i.e. the state "barBottom-vertical" is applied to widgets with the "barBottom" and the "vertical" states in the order it is found in the theme definition.
The styles are all predefined in Wisej.NET and roughly correspond to CSS styles. In fact, Wisej.NET creates a dynamic CSS class and applies it to the widgets that use the appearance key and match the state that contains the style. It's very similar to using CSS classes with HTML elements.
Properties are different from styles and are specific to the widget that is using the owning appearance key. The value of properties is passed to the widget which decides how to render the property value in the DOM. Unlike styles, limited by CSS specs, properties are defined by the widget. For example, the "rowHeight" property of the "table" appearance is used by the Wisej.web.DataGrid widget to set the default height of its rows.
For example, in the built-in themes, the "splitbutton" appearance key contains two components names "button" and "arrow" and since the two child components are actually both buttons, the child appearances both inherit from "button".
In case you need to refer to a child appearance (that is a component in an appearance key), you can address it using a simple path notation: "splitbutton/arrow".
Wisej.NET provides probably the best theme builder on the market. It's a self contained (single executable) tool for Windows that can design and preview the theme files independently. The tool is also capable of loading a running Wisej.NET application and apply theme changes in preview mode.
The tool provides the capability to export/import all the images at once, to edit the source definition in a foldable text editor, and has built-in support for SVG images, including the generation of thumbnails and preview images.
Theme mixins are partial theme files, with the extension .mixin.theme, that define or override only a part of the base theme. The base theme is whatever theme is loaded by the application. There is no limit to the number of mixins that can be applied to a base theme.
This technique allows developers to theme extensions and custom components independently, without having to modify the full themes. It also allows a developer to override aspects of the base theme without having to clone a theme and therefore lose the option to use other themes.
Wisej.NET discovers the mixins dynamically from the embedded resources of all referenced assemblies and the /Theme folder in the running application. The mixins are applied in alphabetical order. An assembly that wants to expose a Wisej.NET resource must have the assembly attribute [assembly:WisejResource].
A mixin can create new appearances, colors, images or fonts and it can override existing ones. When overriding an existing appearance, you can either start from scratch or inherit from the base appearance with the same name and then change only what you want to change. The JSON snippet above shows a mixin where the appearance "button" inherits from the theme appearance "button" (same name) and overrides some of its styles and properties.
Last Clicked
Edge/IE
| Element | Description |
|---|---|
HTML Color Names ()
Wisej.NET translates .NET's to theme colors, if the theme defines colors with the same name with the first character lowercased: i.e. SystemColors.ActiveBorder is translated on the client to the value of "activeBorder" in the colors section.
The textShadow property corresponds to the style.
An appearance contains any number of states (the name of the supported state depends on the widget using the appearance), and a child (not to confuse with child controls). Each state can define a predefined set of and a set of that depend on the widget using the appearance.
For a description of the most common states, see . It's impossible to list all the supported states since they depend on each widget's internal implementation.
For a complete definition of the allowed styles, see . Styles are managed by so-called Decorator classes in the JavaScript framework and are predefined in Wisej.NET.
For a description of the most common properties and their format, see . However, it's impossible to list all the supported properties since they depend on the widgets.
Components are identical to and contain more and . The only difference is that component appearance keys are used by child widgets and depend on the internal name that the owner widget used when creating the child widget.
Relative URL
Any image or icon property or style in the theme can use a relative image URL. i.e. "/images/logo.gif". Wisej will load the image relative to the application's URL.
Absolute URL
Any image or icon property or style in the theme can use an absolute image URL. i.e. "http://google-images.com/fake-image.jpeg".
Embedded base64
Any image or icon property or style in the theme can use the base64 embedded notation. i.e. "data:image/svg+xml;base64,PD9...".
Named Images
In addition to the image URL and embedded base64 images, Wisej.NET themes define their own named images. It's basically an image-indirection table.
Once you declare an image in the images section, the theme can use that image by name. This feature gives you the enormous benefit of being able to change an image (icon) in one place in the theme file without having to change it all over the theme i.e., change the window-close icon to change it in all the components that use window-close.
Font Family
Selects the Google Font.
Embed as Data URI
When checked (default), the font is downloaded and embedded in the theme file as a base64 data URI.
Dimensions
Defines the size of the font in pixels. The Line Height is usually not needed and should be omitted.
Style
Use the Bold and Italic check boxes to specify the font-weight and the font-style. When the check boxes are in the indeterminate state, the font-weight or font-style are not added to the definition. Otherwise the font definition will have a font-weight and a font-style.
The decoration drop down lets you define the text-decoration style.
Text Shadow
Here you can type a CSS font shadow definition. See CSS text-shadow property. i.e. "2px 2px #ff0000".
Web Fonts
These are all the standard Web Fonts. Any font property in the theme can use the Web Font family names.
System Fonts
You may also use font names that are not safe web fonts in the same way you use web fonts. If the user machine has the font installed it will be used by Wisej.NET widgets, otherwise it will fall back to the next valid font name in the list.
Custom Fonts
You can import and use any valid font format: ttf, otf, woff, and woff2. See also Custom Fonts.
Named Fonts
In addition to the Web Fonts and Custom Fonts, Wise.NETj themes define their own named fonts. It's basically a font-indirection table that allows you to define theme fonts, such as "default", "bold", "title", "my-cool-font", ...
Once the font is defined in the font section, every font property in the theme can use the font by name instead of using the full definition. If you change the definition of a named font, i.e. the size or style, all the widgets referring to the font by name use the new style.
The appearances section in the theme file is where all the styles and properties that apply to the widgets are defined. Each widget has an appearance name (corresponds to the AppearanceKey property exposed by the server-side control) that selects which section of the theme applies to the widget.
The appearances are organizes in a hierarchical structure:
See Elements section for a detailed explanation of the theme structure.
Child appearances are reachable using the forward slash. To inherit from the "title" child appearance defined inside "window", use "window/title".
Appearance keys are case sensitive.
Child widgets are not child controls. You cannot refer to child widgets from the server: the Wisej.Web.Button control can only refer to the wisej.web.Button JavaScript widget but cannot reference the internal composition of the widget.
Components refer to child widgets that compose a larger widget. The name of the component is the name used by the parent widget to refer to the child.
The component entry in the Theme is identical to the Appearance entry. A component can include other components in a recursive structure.
In the image above, you can see that the Button appearance contains a component named Icon. Each component has a set of states and for each state it has styles and properties.
Some states are inherited: when the widget adds or removes a state to a widget it will also add it and remove it to child widgets.
Font Family
Defines the list of font names to use in the theme. The browser will use the first supported font family.
Dimensions
Defines the size of the font in pixels. The Line Height is usually not needed and should be omitted.
Style
Use the Bold and Italic check boxes to specify the font-weight and the font-style. When the check boxes are in the indeterminate state, the font-weight or font-style are not added to the definition. Otherwise the font definition will have a font-weight and a font-style.
The decoration drop down lets you define the text-decoration style.
Sources
The sources list lets you add custom font definition files (URLs) and define a new font family. See Fonts for more information.
Text Shadow
Here you can type a CSS font shadow definition. See CSS text-shadow property. i.e. "2px 2px #ff0000".
Adds a new image to the list. |
Edits the selected image. |
Removes the selected image. |
Exports all the images to a folder. |
Import all the images from a folder. |
Deletes the selected text and copies it to the clipboard. |
Copies the selected text to the clipboard. |
Pastes the text in the clipboard at the current location. |
Collapses the outline to the first level. It makes it easier to work with. |
Expands the collapsed outline. |
Reverses the last operation. |
Reapplies the previous operation that was reverted using Undo. |
Opens the Search window. Same as Ctrl-F. |
Opens the Search & Replace window. |
Changes the size of the font in the editor. |
Updates the theme tree and the preview panel. You still need to save the theme to the theme file using the save button in the top toolbar. |
Wisej.NET themes can use Web Colors, HTML Colors, and Named Colors. The table below describes each color type.
| Color Type | Description |
|---|---|
Example of named colors:
Notice that many color names defined in the themes that we provide with Wisej.NET match the colors in System.Drawing.SystemColors. In fact you can use System.Drawing.SystemColors in your Wisej.NET applications, the system will use the colors with the matching name defined in the current theme.
| Element | Description |
|---|---|
Click to add new font and specify where the font files are located.
The dialog shown above lets you define a font family name and associate it with one or more font sources. Once defined, the new font family name can go into the Font Family field. Use the button to import a local file as an embedded base64 data font.
Web Colors
These are all the standard Web Colors. Any color property or style in the theme can use the color name.
HTML Colors
Any color property or style in the theme can use any valid #RGB, #RRGGBB, rbg(r, g, b) or rgba(r, g, b, a) notation.
Named Colors
In addition to the Web Colors and HTML Colors, Wisej.NET themes define their own named colors. It's basically a color-indirection table.
Once you declare a color in the colors section, the theme can use that color by name. This feature gives you the enormous benefit of being able to change the color definition without having to change the color all over the theme i.e., change the buttonFace color to change the color of all the components that use buttonFace.
[appearance key]
Top level appearance key. Widgets that want to use the styles and properties defined under this key must match the key. i.e., wisej.web.Button uses the "button" appearance, but it could use "button-ok" or "button-cancel" to retrieve different styles and properties.
"inherit"
Inherits all the states, styles and properties from another key. i.e., "button-ok" inherits from "button" and overrides the face color.
"text"
The text property is used only by the Theme Builder. It simply changes the text of the appearance in the tree view. i.e. "listview" can be displayed as "ListView". The Theme Builder already converts all appearance keys from first lower to first upper, and converts dashed to spaces. Use the "text" property only when you want to change the text displayed by the Theme Builder.
"states"
The states section contains the list of the states that the appearance should style. See States.
The first state must be default. The theme engine in Wisej applies the styles and properties of all the states that match the widget states in the order they are declared in the theme.
[state name]
The state name depends on the widget using the appearance. Some state are used by most widgets and are suggested by the Theme Builder. However, many widgets use states that depend on the implementation of the widget itself, and can add new states in later releases.
For example, the disabled state is available for most widgets, while the checked, or pressed state is not.
"styles"
Styles used to create the CSS class used by the widget with the matching appearance. See Styles.
"properties"
Property values to assign to the corresponding properties of the widget using the appearance. See Properties.
"components"
The components collection defines child appearances that use the same recursive structure as the main appearance. See Components.
[child key]
Child keys are appearance keys inside another appearance key. They apply their styles and properties to inner widgets. i.e. the icon widget inside a wisej.web.Button uses the styles and properties defined in button/icon.
