KUIMLElement ReferenceSKIN

December 14, 2022

SKIN

Root element for the skin. This element is mandatory for the skin to be valid. It describes the skin meta data and main window properties. It inherits properties from CELL element: it is the root cell of the window.

The SKIN element should also be a root element for the contents of KUIML_WIDGET (it's like loading a skin inside a skin). However some SKIN attributes when used inside KUIML_WIDGET may have to effect or be inherited from the parent SKIN.

That's why some of the attributes may not "work" when you're using them in your .kuiml file, because it is loaded inside the main skin via KUIML_WIDGET. The main skin has an .xml extension and is usually called "default.xml", you can find it in plugin's data directory or in user's documents.

Attributes brief detailed show all inherited

	Name	Description	Default
	name	Name of the skin	empty
	author	Author of the skin. Will be displayed in the about box	empty
	comment	Comment of the author about the skin (description, copyright...)	empty
	language_version	Version of the language used for the skinThis value is important to specify which version of the skinning language is expected by the skin designer	empty
	background_image	The background image	empty
	repeat	Enables or disables the repetition of the background imageIf set to 'true' and if a background image has been set, it will be repeated to cover the whole skin surface (incompatible with stretch attribute)	false
	stretch	Enables or disables background image stretching (resize)If set to 'true' and if a background image has been set, it will be stretched to correspond to the size of the skin (incompatible with repeat attribute)	false
	background_color	Color used to paint the background of the skinThis attribute is not used if 'background_image' is defined	#000000...
	show_warnings	Show warnings encountered during skin parsing	true
	show_info	Show information about skin parsing processCould be used to find issues in skin in earlier KUIML versions. Not much use now.	false
	show_messages	Show messages in a popup window in case of skin loading error.Could be used with log_file_path to suppress error messages and save errors to file. Can be used to disable interactive error messages display when already redirected to a log file. Do not use in production or skin loading may fail silently.	true
	log_file_path	Path to a file where skin builder messages should be logged to (errors, warnings and info).Helpful for debugging skin building issues. Do not use this in production.	empty
	refresh_time_ms	default refresh rate (expressed as a period) in the user interface for the plugin parameters and curvesUse this parameter is you have a very complex user interface with output parameters and curves that refresh too often. Setting the refresh_time_ms to a higher value will help you minimize CPU usage	50
	refresh_priority	priority for user interface refreshsThe higher the priority, the softer the user interface will respond to changes but the more CPU it will use. The 'normal' priority can cause troubles to other plugins in the DAW, so you better stay 'idle'.	idle
	window.opacity	Opacity of the top-level window containing the skinUse this parameter to specify the opacity of the top level window containing the skin. Warning: this option may work differently depending on the host application	100%
	scaling	global scaling (zoom) applied to the entire skin (multiplied to dynamic zoom)	1.0
	gui.zoom	Dynamic zooming for the entire skin, can be modified by the userUse this parameter to specify the level of zoom for the user interface (from 70% to 200%)	100%
	build_time_script_include	Path to build time script file to includeBuild time script include defines classes, objects or functions that can be used at build time to generate the content of VARIABLE elements (experimental) Use absolute path or relative to skin file.	empty
Read Only Attributes
	window.loaded	Set to 'true' when the window has been fully loaded and its state restored	false
	alive	Set to 'true' when the data model has been built and is activeThis attribute is set to false by the engine everytime its state is being restored (loaded from file, restored from memory when window is reopened...)	false
Inherited from cell
Properties Relative to Parent Cell
	v_align	Vertical alignment of the cell in its parent cell	center
	h_align	Horizontal alignment of the cell in its parent cell	center
	h_position	Horizontal position of the cell in its parent cellIf defined, it deactivates the h_align property. Use this attribute for horizontal pixel-positioning. The position is relative to the parent cell
	v_position	Vertical position of the cell in its parent cellIf defined, it deactivates the v_align property. Use this attribute for vertical pixel-positioning. The position is relative to the parent cell
	h_offset	horizontal offset of the cell from the position computed by the layout engineUsing this property lets you move a cell without changing the layout around it. The position is relative to the parent cell	0
	v_offset	vertical offset of the cell from the position computed by the layout engineUsing this property lets you move a cell without changing the layout around it. The position is relative to the parent cell	0
	flex	flexibility of the cellThis attribute is used when the parent cell is a row or a column and has free space to distribute to children cells (for example for a fixed size parent cell that is larger than the sum of its children cell sizes). The remaining space will be distributed among children cells according to the flex attribute value	0
	display	include/exclude the cell from the layoutWhen set to false, the content of the cell is not displayed (not visible) AND is not taken into account to compute the layout (the cell is ignored)	true
Cell Properties
	layout_type	Selects a layout type: row, column or layer_stackDetermines how the children cells will be disposed inside the cell: as a row, a column or a stack of layers (each cell on top of each other, the first cell in the background, and the last one on the foreground)	column
	width	Forced width of the cellIf not present, the width will be automatically computed from the children cells widths and layout rules
	min_width	minimum width allowed for the cellWhen set, the layout engine will ensure that the width of the cell is not smaller than min_width pixels
	max_width	maximum width allowed for the cellWhen set, the layout engine will ensure that the width of the cell is not larger than max_width pixels
	height	Forced height of the cellIf not present, the height will be automatically computed from the children cells heights and layout rules
	min_height	minimum height allowed for the cellWhen set, the layout engine will ensure that the width of the cell is not smaller than min_height pixels
	max_height	maximum height allowed for the cellWhen set, the layout engine will ensure that the width of the cell is not larger than max_height pixels
	margin	margin of the cellMay be overridden by the h_margin or v_margin attributes	0
	h_margin	Horizontal margin of the cell	0
	v_margin	Vertical margin of the cell	0
	spacing	Space between children cells	0
	spacing_flex	Flex value to allocate extra space between children cellsSee the flex attribute for more details	0
	internal_v_align	Vertical alignment of children cells group inside the cellThis attribute is useful only if the cell has a fixed size, and the sum of the sizes of the layouted children cells is different from the cell size. In this case you may want to choose how you align the children cells group inside the parent cell. Used only for 'column' type cell, the horizontal alignment being set individually for each child cell	center
	internal_h_align	Horizontal alignment of children cells group inside the cellThis attribute is useful only if the cell has a fixed size, and the sum of the sizes of the layouted children cells is different from the cell size. In this case you may want to choose how you align the children cells group inside the parent cell. Used only for 'row' type cell, the vertical alignment being set individually for each child cell	center
	reflow	when set to true, the layout engine will treat chidren cell as reflowable elements. For a fixed height column, the width is computed accordingly, and for a fixed width row, the height is computed accordinglyvalid only for columns with fixed height or rows with fixed width	false
	flip	display children cells in reverse order (right to left or bottom to top)currently valid only for COLUMN and ROW elements	false
Inheritable properties: these text properties are inherited by children cells (and can be overridden)
	font_face	Name of the font for text contained in the cell and sub cellsFonts are not the same on all systems, so you should carefuly select the fonts or ensure that users have specific fonts installed	empty
	font_size	Size of the font for any text contained in the cellIf the value starts with + or -, the resulting font size is incremented by this value from the current font size. If the value ends with a %, the resulting font size is the corresponding proportion of the current font size. This value is inherited by children cells but can be overridden	System...
	font_size_mode	Defines how font size is computed to select the right font.Default value is cell mode for backward compatibility reasons but it has been deprecated. It is however recommended to use "character" mode for more precise font size selection. Using the cell size to select the font is less precise and not compatible with standard font sizes expressed in character height.	cell
	font_weight	Weight of the font for any text contained in the cellThe value is inherited by children cells but can be overridden	System...
	font_style	Style of the font for any text contained in the cellThe value is inherited by children cells but can be overridden	System...
	font_quality	Quality of the fontThe value is inherited by children cells but can be overridden	System...
	font_escapement	Escapement (angle in degrees) of the fontThe value is inherited by children cells but can be overridden. If the escapement of the font is non null, the formating options of the text widgets won't apply	0
	text_decoration	Decoration of the text for any text contained in the cellThe value is inherited by children cells but can be overridden	System...
	text_color	Color of any text contained in the cellThe value is inherited by children cells but can be overridden	System...
Common attributes
	id	Identifier of the elementThe id of an element has to be globally unique. Two elements cannot have the same identifier	empty

	Name	Value type	Default	Description	Comment
	name	string	empty	Name of the skin
	author	string	empty	Author of the skin. Will be displayed in the about box
	comment	string	empty	Comment of the author about the skin (description, copyright...)
	language_version	version info	empty	Version of the language used for the skin	This value is important to specify which version of the skinning language is expected by the skin designer
	background_image	image file path	empty	The background image
	repeat	boolean	false	Enables or disables the repetition of the background image	If set to 'true' and if a background image has been set, it will be repeated to cover the whole skin surface (incompatible with stretch attribute)
	stretch	boolean	false	Enables or disables background image stretching (resize)	If set to 'true' and if a background image has been set, it will be stretched to correspond to the size of the skin (incompatible with repeat attribute)
	background_color	color	#000000 (black)	Color used to paint the background of the skin	This attribute is not used if 'background_image' is defined
	show_warnings	boolean	true	Show warnings encountered during skin parsing
	show_info	boolean	false	Show information about skin parsing process	Could be used to find issues in skin in earlier KUIML versions. Not much use now.
	show_messages	boolean	true	Show messages in a popup window in case of skin loading error.	Could be used with log_file_path to suppress error messages and save errors to file. Can be used to disable interactive error messages display when already redirected to a log file. Do not use in production or skin loading may fail silently.
	log_file_path	path to log file	empty	Path to a file where skin builder messages should be logged to (errors, warnings and info).	Helpful for debugging skin building issues. Do not use this in production.
	refresh_time_ms	Positive integer	50	default refresh rate (expressed as a period) in the user interface for the plugin parameters and curves	Use this parameter is you have a very complex user interface with output parameters and curves that refresh too often. Setting the refresh_time_ms to a higher value will help you minimize CPU usage
	refresh_priority	'idle' or 'normal'	idle	priority for user interface refreshs	The higher the priority, the softer the user interface will respond to changes but the more CPU it will use. The 'normal' priority can cause troubles to other plugins in the DAW, so you better stay 'idle'.
	window.opacity	percentage	100%	Opacity of the top-level window containing the skin	Use this parameter to specify the opacity of the top level window containing the skin. Warning: this option may work differently depending on the host application
	scaling	real number	1.0	global scaling (zoom) applied to the entire skin (multiplied to dynamic zoom)
	gui.zoom	percentage	100%	Dynamic zooming for the entire skin, can be modified by the user	Use this parameter to specify the level of zoom for the user interface (from 70% to 200%)
	build_time_script_include	path to script file	empty	Path to build time script file to include	Build time script include defines classes, objects or functions that can be used at build time to generate the content of VARIABLE elements (experimental) Use absolute path or relative to skin file.
Read Only Attributes
	window.loaded	boolean	false	Set to 'true' when the window has been fully loaded and its state restored
	alive	boolean	false	Set to 'true' when the data model has been built and is active	This attribute is set to false by the engine everytime its state is being restored (loaded from file, restored from memory when window is reopened...)
Inherited from cell
Properties Relative to Parent Cell
	v_align	vertical alignment	center	Vertical alignment of the cell in its parent cell
	h_align	horizontal alignment	center	Horizontal alignment of the cell in its parent cell
	h_position	position in pixels		Horizontal position of the cell in its parent cell	If defined, it deactivates the h_align property. Use this attribute for horizontal pixel-positioning. The position is relative to the parent cell
	v_position	position in pixels		Vertical position of the cell in its parent cell	If defined, it deactivates the v_align property. Use this attribute for vertical pixel-positioning. The position is relative to the parent cell
	h_offset	position in pixels	0	horizontal offset of the cell from the position computed by the layout engine	Using this property lets you move a cell without changing the layout around it. The position is relative to the parent cell
	v_offset	position in pixels	0	vertical offset of the cell from the position computed by the layout engine	Using this property lets you move a cell without changing the layout around it. The position is relative to the parent cell
	flex	real number	0	flexibility of the cell	This attribute is used when the parent cell is a row or a column and has free space to distribute to children cells (for example for a fixed size parent cell that is larger than the sum of its children cell sizes). The remaining space will be distributed among children cells according to the flex attribute value
	display	boolean	true	include/exclude the cell from the layout	When set to false, the content of the cell is not displayed (not visible) AND is not taken into account to compute the layout (the cell is ignored)
Cell Properties
	layout_type	'row' or 'column' or 'layer_stack'	column	Selects a layout type: row, column or layer_stack	Determines how the children cells will be disposed inside the cell: as a row, a column or a stack of layers (each cell on top of each other, the first cell in the background, and the last one on the foreground)
	width	number of pixels or percentage (1.1)		Forced width of the cell	If not present, the width will be automatically computed from the children cells widths and layout rules
	min_width	number of pixels		minimum width allowed for the cell	When set, the layout engine will ensure that the width of the cell is not smaller than min_width pixels
	max_width	number of pixels		maximum width allowed for the cell	When set, the layout engine will ensure that the width of the cell is not larger than max_width pixels
	height	number of pixels or percentage (1.1)		Forced height of the cell	If not present, the height will be automatically computed from the children cells heights and layout rules
	min_height	number of pixels		minimum height allowed for the cell	When set, the layout engine will ensure that the width of the cell is not smaller than min_height pixels
	max_height	number of pixels		maximum height allowed for the cell	When set, the layout engine will ensure that the width of the cell is not larger than max_height pixels
	margin	number of pixels	0	margin of the cell	May be overridden by the h_margin or v_margin attributes
	h_margin	number of pixels	0	Horizontal margin of the cell
	v_margin	number of pixels	0	Vertical margin of the cell
	spacing	number of pixels	0	Space between children cells
	spacing_flex	real number	0	Flex value to allocate extra space between children cells	See the flex attribute for more details
	internal_v_align	vertical alignment	center	Vertical alignment of children cells group inside the cell	This attribute is useful only if the cell has a fixed size, and the sum of the sizes of the layouted children cells is different from the cell size. In this case you may want to choose how you align the children cells group inside the parent cell. Used only for 'column' type cell, the horizontal alignment being set individually for each child cell
	internal_h_align	horizontal alignment	center	Horizontal alignment of children cells group inside the cell	This attribute is useful only if the cell has a fixed size, and the sum of the sizes of the layouted children cells is different from the cell size. In this case you may want to choose how you align the children cells group inside the parent cell. Used only for 'row' type cell, the vertical alignment being set individually for each child cell
	reflow	boolean	false	when set to true, the layout engine will treat chidren cell as reflowable elements. For a fixed height column, the width is computed accordingly, and for a fixed width row, the height is computed accordingly	valid only for columns with fixed height or rows with fixed width
	flip	boolean	false	display children cells in reverse order (right to left or bottom to top)	currently valid only for COLUMN and ROW elements
Inheritable properties: these text properties are inherited by children cells (and can be overridden)
	font_face	string	empty	Name of the font for text contained in the cell and sub cells	Fonts are not the same on all systems, so you should carefuly select the fonts or ensure that users have specific fonts installed
	font_size	number of pixels or percentage (1.2.2), with or without +/- sign (1.2.2)	System default value	Size of the font for any text contained in the cell	If the value starts with + or -, the resulting font size is incremented by this value from the current font size. If the value ends with a %, the resulting font size is the corresponding proportion of the current font size. This value is inherited by children cells but can be overridden
	font_size_mode	"cell" or "character"	cell	Defines how font size is computed to select the right font.	Default value is cell mode for backward compatibility reasons but it has been deprecated. It is however recommended to use "character" mode for more precise font size selection. Using the cell size to select the font is less precise and not compatible with standard font sizes expressed in character height.
	font_weight	'bold' or 'normal'	System default value	Weight of the font for any text contained in the cell	The value is inherited by children cells but can be overridden
	font_style	'italic' or 'normal'	System default value	Style of the font for any text contained in the cell	The value is inherited by children cells but can be overridden
	font_quality	'default' or 'no_anti_alias' or 'anti_alias' or 'cleartype'	System default value	Quality of the font	The value is inherited by children cells but can be overridden
	font_escapement	real number	0	Escapement (angle in degrees) of the font	The value is inherited by children cells but can be overridden. If the escapement of the font is non null, the formating options of the text widgets won't apply
	text_decoration	'underline' or 'none'	System default value	Decoration of the text for any text contained in the cell	The value is inherited by children cells but can be overridden
	text_color	color	System default value	Color of any text contained in the cell	The value is inherited by children cells but can be overridden
Common attributes
	id	identifier	empty	Identifier of the element	The id of an element has to be globally unique. Two elements cannot have the same identifier

Examples

Empty skin with black background (minimum size of a skin is 20x20 pixels, so that the user can click on the background to change the skin)

Empty skin with 'bg.bmp' image as background:

Skin with 'bg.bmp' image as background (repeated), with 5 images (black square) shown in a row, spaced by 5 pixels: