How to customize view labels and icons in predefined controllers

There are several ways to customize display labels and icons when using a predefined controller such as ChangePassword or Logout.

A controller defines its default display labels and icon by defining the public methods GetDefaultDisplayLabel and GetDefaultImageName (see the unit Kitto.Html.ChangePassword for an example). These methods, if existing, are called if no alternative options are used. You can override these by specifying the keys DisplayLabel and ImageName at the tree view node level:

Folder: User options
  View:
    Controller: ChangePassword
    ImageName: vpn_key
    DisplayLabel: My text

or at the view level (that is, directly in the view definition file) if the view is persistent.

Icon system

Kitto^x uses Material Design Icons (2122 SVG icons × 5 styles, Apache 2.0 license). Icons are rendered via CSS mask-image, making them automatically adapt to the current theme colors (light/dark).

Five icon styles are available: filled, outlined, round, sharp, two-tone. The style is configurable per application via the Theme/IconStyle setting in Config.yaml:

Theme: Light
  IconStyle: filled      # filled (default), outlined, round, sharp, two-tone
  IconSize: Medium       # Small (1em), Medium (1.4em, default), Large (1.8em)

The two-tone style has two <path> elements in each SVG, the second with opacity=".3". With the CSS mask-image technique, this produces a natural two-tone effect without additional CSS.

How icon resolution works

When you specify an ImageName in YAML metadata, Kitto^x resolves it through multiple levels:

1. Kitto^x name mapping — A built-in map translates legacy Kitto^x icon names (e.g., accept, delete_record, email_go) to MDI names (e.g., check_circle, delete, email). This ensures backward compatibility with existing YAML files.

2. Direct MDI name — You can use any Material Design Icon name directly (e.g., schedule, bar_chart, picture_as_pdf). MDI uses underscores (e.g., chevron_left, not chevron-left). The icon is loaded from Home/Resources/icons/{style}/{name}.svg.

3. Hyphen-to-underscore conversion — If the name contains hyphens, Kitto^x automatically tries the underscore variant.

4. Filled fallback — If the icon is not found in the configured style (e.g., outlined), Kitto^x falls back to the filled style, which has the most complete coverage.

5. PNG fallback — If no matching SVG is found, Kitto^x falls back to looking for a PNG image in Home/Resources/images/.

Built-in icon name mapping

The following table shows the most common Kitto^x icon names and their Material Design Icon equivalents:

Kittox name	MDI name	Usage
accept	check_circle	Save/confirm actions
cancel	cancel	Cancel actions
close	close	Close buttons
delete_record	delete	Delete record
dup_record	content_copy	Duplicate record
edit_record	edit	Edit record
new_record	add_circle	Add new record
view_record	visibility	View record (read-only)
save	save	Save
refresh	refresh	Refresh data
find	search	Search/lookup
login	login	Login
logout	logout	Logout
password	vpn_key	Password/key
user	person	User
download	download (direct)	Download
excel_document	table_chart	Excel export
pdf_document	picture_as_pdf	PDF document
email_go	email	Send email
home	home	Home
settings	settings	Settings
chart_bar	bar_chart	Bar chart
chart_pie	pie_chart	Pie chart

A compatibility layer also maps old Bootstrap Icon names (hyphenated) to their MDI equivalents (e.g., chevron-right → chevron_right, bar-chart-line → bar_chart).

For the complete mapping, see Kitto.Html.Utils.pas (InitIconMap procedure).

Icon sizes

Icons can be rendered in four sizes:

Value	CSS class	Size	Typical use
isDefault	(from Theme)	configurable	All icons (default)
isSmall	kx-icon-sm	1em	Compact contexts
isMedium	kx-icon-md	1.4em	General UI (default for isDefault)
isLarge	kx-icon-lg	1.8em	Form action buttons (Save, Cancel, Edit), auth dialogs (Login, ChangePassword)

Sizes use em units so they scale proportionally with the font size configured in the theme.

The default size (isDefault) can be overridden per application via Theme/IconSize in Config.yaml (values: Small, Medium, Large). When not specified, the default is Medium.

Custom icons

You can add your own SVG icons by placing .svg files in Home/Resources/icons/{style}/ (e.g., Home/Resources/icons/filled/my_icon.svg). Use the file name (without extension) as the ImageName value. Custom icons in the configured style directory take precedence over built-in MDI icons with the same name.

You can also still use PNG images by placing them in Home/Resources/images/, but SVG icons are preferred because they adapt to the current theme colors.

Migrating icons from Kitto1

Kitto1 applications used PNG icons stored in Home/Resources/. When migrating to Kitto^x, you should replace icon names in your YAML files with the corresponding Material Design Icon names, which are listed at fonts.google.com/icons.

Common icon name changes

Many Kitto1 applications used Material Design icon names for their PNG files, but some names have changed or don't exist as MDI SVG icons:

Kitto1 name	Kittox (MDI) name	Notes
calendar	calendar_month	calendar doesn't exist in MDI; use calendar_month or calendar_today
info_outline	info	In MDI "filled" style, the outlined variant is just info
*_large (e.g., child_care_large)	base name (e.g., child_care)	Kitto1 used _large suffix for bigger PNGs; Kittox icon size is controlled by CSS, not the file name

The _large suffix

In Kitto1, icons like sentiment_satisfied_large.png were separate PNG files at a larger pixel size. In Kitto^x, icon sizes are controlled via CSS classes (kx-icon-sm, kx-icon-md, kx-icon-lg) and the Theme/IconSize setting — there is no need for size suffixes in icon names.

When migrating:

1. Replace ImageName: some_icon_large with ImageName: some_icon in view/model YAML
2. Replace %IMAGE(some_icon_large)% with %IMAGE(some_icon)% in SQL expressions

Icons used in %IMAGE(...)% expressions

The %IMAGE(...)% macro in YAML model expressions (typically used in Expression fields to embed images in grid cells) resolves to a PNG URL via GetImageURL. This means:

• The macro looks for .png files in Home/Resources/ (application-level) or the framework Resources
• It does not use SVG icons from icons/{style}/
• You must keep the PNG files in your app's Home/Resources/ directory for these expressions

Example:

Expression: |
  '<img src="'+
  CASE
    WHEN {Q}STATUS = 'OK' THEN '%IMAGE(sentiment_satisfied)%'
    WHEN {Q}STATUS = 'KO' THEN '%IMAGE(sentiment_dissatisfied)%'
  END+'" width="40" />'

This requires sentiment_satisfied.png and sentiment_dissatisfied.png in Home/Resources/.

Migration checklist

1. Search all YAML files for ImageName: and %IMAGE(...)% references
2. Check each icon name against the MDI icon catalog
3. Remove _large, _small, _16, _24, _32, _48 suffixes — use just the base MDI name
4. Replace renamed icons (e.g., calendar → calendar_month, info_outline → info)
5. For %IMAGE(...)% references: ensure the PNG file exists in Home/Resources/ with the new name
6. Delete unused PNG files from Home/Resources/ that have been replaced by MDI SVGs