Functional explanation
The Color Library holds named colors that the whole project shares. A color setting of a graphical object accepts either a color value or the name of a library entry. When a name is stored, the object resolves it through the library each time it renders.
This makes the library the single place where a project color is defined. Changing the color value of one entry restyles every object that references it, without editing any page. A typical use is a plant color scheme: one entry per meaning, such as a running state, a fault state, or a corporate accent color, referenced by every symbol that shows that meaning.
The library holds one or more themes. Every theme carries the same color names and differs only in the color values, so an operator can switch theme and have every object that references a name repaint at once. A project that needs a single color scheme uses the one theme it starts with and never has to think about themes.
The library is stored with the project configuration and is included in project export and backup. It is available to users in the Administrators group.
Opening the Color Library
Open the design environment and click the Color Library icon in the utility bar at the bottom of the left menu. The library opens with one card per named color.
The list is refreshed from the server each time it opens, so entries added or changed through the Configuration API or MCP are shown.
Managing colors
Each card holds the color swatch, the color name, and the current color value. Cards are dragged by the handle next to the swatch to set the order in which they are listed here and in the color picker.
| Control | Description |
|---|---|
| Add Color | Adds a card with a default color. Enter a name and click the swatch to set the color. |
| Color swatch | Opens the color picker for that entry. The swatch shows transparency on a checkerboard background. |
| Name | Name of the entry, up to 20 characters. This is the value stored on an object that references the entry, so it is also its identity. |
| Delete | Removes the card from the list. |
| Import | Loads a previously exported color library file into the list. |
| Export | Writes the current list to ColorProfile.txt. |
| Save and Close | Saves the list to the project and closes the library. |
No rows match the filter.
Themes
The theme bar at the top of the Color Library selects which theme the cards show. The cards always list the same color names in the same order; only the color values change with the theme. The theme marked with a star is the default theme, which is the theme a client uses until an operator picks another one.
Because every theme carries the same names, adding, deleting, renaming and reordering a color always applies to every theme at once. Only the color value is set per theme. This is what keeps a theme switch safe: a name that existed in one theme only would leave the objects that reference it without a color in the other themes.
A new theme starts as a copy of the theme on screen, so it already holds every color name and can be adjusted value by value.
| Control | Description |
|---|---|
| Theme | Selects the theme the cards show. Switching keeps the edits made to the previous theme. |
| Add | Creates a theme, copied from the theme currently shown, and switches to it. |
| Rename | Renames the theme currently shown. Clients still set to the old name use the default theme until they pick again. |
| Default | Makes the theme currently shown the default theme. |
| Delete | Deletes the theme currently shown. The last remaining theme is kept, because it holds every color value in the library. |
No rows match the filter.
Name rules
Each name must be unique within the library. Two cards with the same name are marked and the library reports which names to change, because the library is keyed by name and one entry would otherwise replace the other.
A name may hold up to 20 characters. It may not start with a number sign, which would make it indistinguishable from a color value, and it may not contain a comma.
Names are matched exactly, including case, so Pump and pump are two separate entries.
Color values and transparency
A color is stored as a hex value. The optional alpha byte sets the opacity, so a library color can be partly or fully transparent in the same way a color chosen directly on an object can.
| Format | Description | Example |
|---|---|---|
| #RGB | Short form, expanded to the six digit form when it is saved. | #0AF |
| #RRGGBB | Red, green and blue. Fully opaque. | #4CAF50 |
| #RRGGBBAA | Red, green and blue plus the alpha byte. AA runs from 00 for fully transparent to FF for fully opaque. | #FF000080 |
| Fully transparent | The value used by the Transparent button of the color picker. | #FFFFFF00 |
No rows match the filter.
Choosing a color
Clicking a color swatch opens the color picker. It is the same picker used by every color setting in the design environment.
| Control | Description |
|---|---|
| Solid and Gradient | Two tabs at the top of the picker. Solid stores one color. Gradient stores a gradient and opens the Gradient section below the opacity slider. The tabs appear only on a setting that can show a gradient, which is an object background or fill. |
| Color field and hue slider | Select the color. The hex field below shows the resulting value and also accepts a typed value. |
| Pick from screen | Reads a color from anywhere on the screen. Available in browsers that provide the eyedropper. |
| Transparent | Sets the color to fully transparent and closes the picker. |
| Opacity | Sets the alpha of the selected color, from 0% to 100%. Below 100% the value gains the alpha byte and becomes a nine character hex value. |
| Select | Confirms the current color and closes the picker. |
| Recent | The colors most recently chosen in this browser. |
| Palette | The standard color palette. |
| Color Library | The named colors of the project, with a search field. Selecting a row stores the name on the object rather than the color value, which is what keeps the object linked to the library. On a setting that accepts a gradient, the Colors and Gradients buttons filter the list between entries that hold a color and entries that hold a gradient. |
No rows match the filter.
Gradients
An entry can hold a gradient instead of a single color. This is how a project gets a named gradient: objects reference it by name in the same way they reference a named color, and because the value is stored per theme, a gradient follows a theme switch as well.
A gradient is built in the Gradient section of the color picker, which appears below the opacity slider once the Gradient tab is selected. The stops are shown on a bar under the gradient preview. Clicking a stop selects it, and the color field, hue slider, hex field, opacity slider, Palette and Recent above then apply to that stop.
| Control | Description |
|---|---|
| Linear | Runs the colors along a straight line. The Angle field and the dial beside it set the direction, in degrees, where 0 runs bottom to top and 90 runs left to right. |
| Radial | Spreads the colors out from a center point. The Center X field sets the horizontal position of that center, as a percentage of the object. |
| Gradient bar | Preview of the gradient with the stops beneath it. Double-clicking the bar adds a stop at that position, taking the color the gradient already shows there. |
| Stop | Position of the selected stop, from 0% at the start of the gradient to 100% at the end. A stop can also be dragged along the bar. |
| Reverse | Mirrors the stop positions, so the gradient runs the other way. |
| Remove stop | Deletes the selected stop. A gradient always keeps at least two stops. |
| Select | Confirms the gradient and closes the picker. |
No rows match the filter.
A gradient paints on object backgrounds and fills: the background of a Square, Circle, Button, Label, Input, Container, Data Table and Alarm Banner, the fill of an SVG, Polygon and Knob, the Slider track and thumb, the DropDown and List Box background settings, the page background, and the color of a dynamic color state.
Every other color setting shows one color: text colors, border and stroke colors, grid lines, scroll bars, chart axes and Trend pen colors. Those settings show only the Solid tab, and their Color Library list shows only the entries that hold a color. If such a setting does reference an entry that was later changed into a gradient, it shows the gradient's first stop.
The stored value of a gradient entry is a single line of text, which is what the Configuration API and MCP read and write:
linear|<angle 0-359>|<stop>|<stop>
radial|<centerX 0-100> <centerY 0-100>|<stop>|<stop>
Each stop is a hex color followed by @ and its position, for example linear|90|#2E7D32@0|#81C784@100. A gradient holds two to sixteen stops, and stop colors are hex values, including the alpha byte for a stop that fades out.
Using a library color on an object
Open the color setting of the object and pick the entry from the Color Library section of the color picker. The object then stores the name and follows the library.
From the same section, the plus icon adds the color currently selected in the picker to the library under a name entered there, and the expand icon opens the full Color Library.
Library names are resolved for the color settings of graphical objects, for the page background and border color, for the color settings on the Parameters page that style the login page, the viewers, the numpad, the keyboard and the alarm states, and for the pen and chart colors in Trend Analyst. The swatches inside the Color Library itself take a color value directly, because those are the values the library is built from.
Switching theme at runtime
A theme is switched with the Select Theme object action. The action takes a theme name, or the name of a variable holding one, so a single button can switch to whatever theme a variable selects. The Theme button next to the field lists the themes defined in the library.
The choice applies to the station that made it and is remembered on that station, so two clients may run different themes against the same project. A client that has never picked a theme uses the default theme. A client set to a theme that has since been renamed or deleted falls back to the default theme.
Selecting a theme reloads the page. The same page is reopened and the operator stays logged in. Open popups are closed and text typed into an input but not yet confirmed is discarded, the same as when the Navigate To action is used.
The selected theme is also published as the client variable client.SelectedTheme, which can be used in conditions and expressions.
| Setting | Description | Example |
|---|---|---|
| Theme | Name of the theme to switch to, or the name of a variable that holds it. | Night |
No rows match the filter.
Renaming and deleting
An object stores the name of the entry, and nothing rewrites those objects when the entry is renamed or deleted. An object that still holds the old name keeps that name as a plain value and no longer resolves to a color.
Before renaming or deleting an entry that is in use, update the objects that reference it, or create the new entry first and move the objects over to it.
Renaming and deleting apply to every theme, so the themes keep the same set of names.
Import and export
Export writes the whole library, including every theme, to a file. Import reads such a file back and replaces the library with its contents, after reporting how many colors and themes it holds. A file that is not a color library is refused rather than loaded.
A file exported before themes were available holds a single color scheme and is read back as one theme.
| File | Content |
|---|---|
| ColorProfile.txt | { "Pump_Running": "#4CAF50", "Pump_Alarm": "#F44336", "Glass_Overlay": "#FFFFFF80" } |
No rows match the filter.
Configuration API and MCP
The Color Library is available through the Configuration API and through the matching MCP tool, so a color scheme can be created, reviewed and adjusted without opening the design environment. The MCP side is a single tool, ManageColorLibrary, where the action argument selects the operation and the items argument carries the entries. Entries are addressed by name. Calls require a user in the Administrators group, and writes are accepted on the primary node.
Reading and updating a color value apply to one theme, selected with the theme query parameter or the theme argument; the default theme is used when it is omitted. Creating, deleting, renaming and reordering a color apply to every theme.
The color field of an entry accepts either a hex value or a gradient value in the form described under Gradients. A value that is neither is refused with a message stating both accepted forms.
| Endpoint | MCP tool | Description |
|---|---|---|
| GET API/Config/ColorLibrary | ManageColorLibrary, action 'get' | Lists the entries in the order the Color Library shows them. |
| POST API/Config/ColorLibrary | ManageColorLibrary, action 'create' | Creates one or more entries. A name that already exists is refused. |
| PUT API/Config/ColorLibrary | ManageColorLibrary, action 'update' | Sets the color value of existing entries, and optionally renames them. |
| POST API/Config/ColorLibrary/Delete | ManageColorLibrary, action 'delete' | Deletes entries by name. |
| GET API/Config/ColorLibrary?theme= | ManageColorLibrary, action 'get', argument theme | Lists the entries of one theme. The default theme is used when the theme is omitted. |
| PUT API/Config/ColorLibrary?theme= | ManageColorLibrary, action 'update', argument theme | Writes the color value into one theme. A rename in the same call applies to every theme. |
| PUT API/Config/ColorLibrary/Order | ManageColorLibrary, action 'reorder' | Sets the order the entries are listed in. The order is shared by every theme. |
| GET API/Config/ColorLibrary/Themes | ManageColorLibrary, action 'getThemes' | Lists the theme names and which one is the default. |
| POST API/Config/ColorLibrary/Themes | ManageColorLibrary, action 'createTheme' | Creates a theme, copied from the theme named in copyFrom or from the default theme. |
| PUT API/Config/ColorLibrary/Themes | ManageColorLibrary, action 'updateTheme' | Renames a theme and sets which theme is the default. |
| POST API/Config/ColorLibrary/Themes/Delete | ManageColorLibrary, action 'deleteTheme' | Deletes one or more themes. The last remaining theme is kept. |
No rows match the filter.
| Field | Description | Example |
|---|---|---|
| name | Name of the entry. Up to 20 characters, and the value an object stores to follow this entry. | Pump_Running |
| color | Color value as #RGB, #RRGGBB or #RRGGBBAA. | #4CAF50 |
| newName | Optional new name on update. The objects that reference the old name are left as they are, so update them as well. | Pump_Started |
| theme | Theme to read or write the color value of. Omitted means the default theme. | Night |
| copyFrom | Theme whose color values a new theme starts from. Omitted means the default theme. | Default |
| isDefault | Set on a theme update to make that theme the default theme. | true |
No rows match the filter.
Behavior
Every change through the design environment or the Configuration API is recorded in the audit trail and is replicated to the standby node in a redundant setup.
A change reaches a running client the next time the client loads the page, because the library is read when the page is opened.
A project created before themes were available opens as a library with a single theme named Default, holding the colors it already had. No conversion step is needed.