PLUG'N SCRIPT
rapid plugin development
Tutorial
DSP
KUIML
How-to
Scripts
  • Tutorial
  • Element Reference
Language basics
  • SKIN
  • DUMMY
  • INCLUDE
  • INCLUDE_ONCE
  • DEFINE
  • UNDEFINE
  • VARIABLE
  • LOCAL_VARIABLE
  • TEMPLATE
  • TEMPLATE_INNER_CONTENT
  • REPEAT
Data model
  • PARAM
  • ACTION
    • Action types
  • ACTION_TRIGGER
UI Layout and positioning
  • CELL
  • TABLE
UI Widgets
  • TEXT
  • TEXT_FIELD
  • TEXT_EDIT_BOX
  • CANVAS
    • Graphics API
  • svg
Common attrubutes
  • For all elements
  • Widgets
  • Param Widgets
  • Param Controls
  • Param Info Viewers
  • Text Widgets
  • Surface Viewers
  • Curve Viewers
  • 3D Objects
  • Parameters mapping
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 DescriptionDefault
nameName of the skinempty
authorAuthor of the skin. Will be displayed in the about boxempty
commentComment of the author about the skin (description, copyright...)empty
language_versionVersion of the language used for the skinThis value is important to specify which version of the skinning language is expected by the skin designerempty
background_imageThe background imageempty
repeatEnables 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
stretchEnables 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_colorColor used to paint the background of the skinThis attribute is not used if 'background_image' is defined#000000...
show_warningsShow warnings encountered during skin parsingtrue
show_infoShow information about skin parsing processCould be used to find issues in skin in earlier KUIML versions. Not much use now.false
show_messagesShow 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_pathPath 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_msdefault 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 usage50
refresh_prioritypriority 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
Exposed: v. 1.2.5window.opacityOpacity 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 application100%
scalingglobal scaling (zoom) applied to the entire skin (multiplied to dynamic zoom)1.0
Exposed: v. 2.4gui.zoomDynamic 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_includePath 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
Exposed: v. 2.0window.loadedSet to 'true' when the window has been fully loaded and its state restoredfalse
Exposed: v. 2.0aliveSet 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 cellRead about `cell`
Properties Relative to Parent Cell
Exposed: v. 1.5v_alignVertical alignment of the cell in its parent cellcenter
Exposed: v. 1.5h_alignHorizontal alignment of the cell in its parent cellcenter
Exposed: v. 1.9.1 (read only)h_positionHorizontal 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
Exposed: v. 1.9.1 (read only)v_positionVertical 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
Exposed: v. 1.9.1h_offsethorizontal 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 cell0
Exposed: v. 1.9.1v_offsetvertical 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 cell0
Exposed: v. 1.5flexflexibility 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 value0
Exposed: v. 1.5displayinclude/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
Exposed: v. 1.5layout_typeSelects 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
Exposed: v. 1.9.1 (pixels)widthForced width of the cellIf not present, the width will be automatically computed from the children cells widths and layout rules
Exposed: v. 2.0min_widthminimum width allowed for the cellWhen set, the layout engine will ensure that the width of the cell is not smaller than min_width pixels
Exposed: v. 2.0max_widthmaximum width allowed for the cellWhen set, the layout engine will ensure that the width of the cell is not larger than max_width pixels
Exposed: v. 1.9.1 (pixels)heightForced height of the cellIf not present, the height will be automatically computed from the children cells heights and layout rules
Exposed: v. 2.0min_heightminimum height allowed for the cellWhen set, the layout engine will ensure that the width of the cell is not smaller than min_height pixels
Exposed: v. 2.0max_heightmaximum height allowed for the cellWhen set, the layout engine will ensure that the width of the cell is not larger than max_height pixels
marginmargin of the cellMay be overridden by the h_margin or v_margin attributes0
Exposed: v. 1.5h_marginHorizontal margin of the cell0
Exposed: v. 1.5v_marginVertical margin of the cell0
Exposed: v. 1.5spacingSpace between children cells0
spacing_flexFlex value to allocate extra space between children cellsSee the flex attribute for more details0
Exposed: v. 1.5internal_v_alignVertical 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 cellcenter
Exposed: v. 1.5internal_h_alignHorizontal 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 cellcenter
Exposed: v. 2.0reflowwhen 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 widthfalse
Exposed: v. 2.4flipdisplay children cells in reverse order (right to left or bottom to top)currently valid only for COLUMN and ROW elementsfalse
Inheritable properties: these text properties are inherited by children cells (and can be overridden)
font_faceName 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 installedempty
font_sizeSize 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 overriddenSystem...
font_size_modeDefines 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_weightWeight of the font for any text contained in the cellThe value is inherited by children cells but can be overriddenSystem...
font_styleStyle of the font for any text contained in the cellThe value is inherited by children cells but can be overriddenSystem...
font_qualityQuality of the fontThe value is inherited by children cells but can be overriddenSystem...
font_escapementEscapement (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 apply0
text_decorationDecoration of the text for any text contained in the cellThe value is inherited by children cells but can be overriddenSystem...
text_colorColor of any text contained in the cellThe value is inherited by children cells but can be overriddenSystem...
Common attributesRead about `common`
idIdentifier of the elementThe id of an element has to be globally unique. Two elements cannot have the same identifierempty
Name Value type Default Description Comment
namestringemptyName of the skin
authorstringemptyAuthor of the skin. Will be displayed in the about box
commentstringemptyComment of the author about the skin (description, copyright...)
language_versionversion infoemptyVersion of the language used for the skinThis value is important to specify which version of the skinning language is expected by the skin designer
background_imageimage file pathemptyThe background image
repeatbooleanfalseEnables 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)
stretchbooleanfalseEnables 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_colorcolor#000000 (black)Color used to paint the background of the skinThis attribute is not used if 'background_image' is defined
show_warningsbooleantrueShow warnings encountered during skin parsing
show_infobooleanfalseShow information about skin parsing processCould be used to find issues in skin in earlier KUIML versions. Not much use now.
show_messagesbooleantrueShow 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_pathpath to log fileemptyPath 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_msPositive integer50default 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
refresh_priority'idle' or 'normal'idlepriority 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'.
Exposed: v. 1.2.5window.opacitypercentage100%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
scalingreal number1.0global scaling (zoom) applied to the entire skin (multiplied to dynamic zoom)
Exposed: v. 2.4gui.zoompercentage100%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%)
build_time_script_includepath to script fileemptyPath 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.
Read Only Attributes
Exposed: v. 2.0window.loadedbooleanfalseSet to 'true' when the window has been fully loaded and its state restored
Exposed: v. 2.0alivebooleanfalseSet 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...)
Inherited from cellRead about `cell`
Properties Relative to Parent Cell
Exposed: v. 1.5v_alignvertical alignmentcenterVertical alignment of the cell in its parent cell
Exposed: v. 1.5h_alignhorizontal alignmentcenterHorizontal alignment of the cell in its parent cell
Exposed: v. 1.9.1 (read only)h_positionposition in pixelsHorizontal 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
Exposed: v. 1.9.1 (read only)v_positionposition in pixelsVertical 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
Exposed: v. 1.9.1h_offsetposition in pixels0horizontal 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
Exposed: v. 1.9.1v_offsetposition in pixels0vertical 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
Exposed: v. 1.5flexreal number0flexibility 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
Exposed: v. 1.5displaybooleantrueinclude/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)
Cell Properties
Exposed: v. 1.5layout_type'row' or 'column' or 'layer_stack'columnSelects 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)
Exposed: v. 1.9.1 (pixels)widthnumber of pixels or percentage (1.1)Forced width of the cellIf not present, the width will be automatically computed from the children cells widths and layout rules
Exposed: v. 2.0min_widthnumber of pixelsminimum width allowed for the cellWhen set, the layout engine will ensure that the width of the cell is not smaller than min_width pixels
Exposed: v. 2.0max_widthnumber of pixelsmaximum width allowed for the cellWhen set, the layout engine will ensure that the width of the cell is not larger than max_width pixels
Exposed: v. 1.9.1 (pixels)heightnumber of pixels or percentage (1.1)Forced height of the cellIf not present, the height will be automatically computed from the children cells heights and layout rules
Exposed: v. 2.0min_heightnumber of pixelsminimum height allowed for the cellWhen set, the layout engine will ensure that the width of the cell is not smaller than min_height pixels
Exposed: v. 2.0max_heightnumber of pixelsmaximum height allowed for the cellWhen set, the layout engine will ensure that the width of the cell is not larger than max_height pixels
marginnumber of pixels0margin of the cellMay be overridden by the h_margin or v_margin attributes
Exposed: v. 1.5h_marginnumber of pixels0Horizontal margin of the cell
Exposed: v. 1.5v_marginnumber of pixels0Vertical margin of the cell
Exposed: v. 1.5spacingnumber of pixels0Space between children cells
spacing_flexreal number0Flex value to allocate extra space between children cellsSee the flex attribute for more details
Exposed: v. 1.5internal_v_alignvertical alignmentcenterVertical 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
Exposed: v. 1.5internal_h_alignhorizontal alignmentcenterHorizontal 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
Exposed: v. 2.0reflowbooleanfalsewhen 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
Exposed: v. 2.4flipbooleanfalsedisplay 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_facestringemptyName 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
font_sizenumber of pixels or percentage (1.2.2), with or without +/- sign (1.2.2)System default valueSize 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
font_size_mode"cell" or "character"cellDefines 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 valueWeight of the font for any text contained in the cellThe value is inherited by children cells but can be overridden
font_style'italic' or 'normal'System default valueStyle of the font for any text contained in the cellThe value is inherited by children cells but can be overridden
font_quality'default' or 'no_anti_alias' or 'anti_alias' or 'cleartype'System default valueQuality of the fontThe value is inherited by children cells but can be overridden
font_escapementreal number0Escapement (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
text_decoration'underline' or 'none'System default valueDecoration of the text for any text contained in the cellThe value is inherited by children cells but can be overridden
text_colorcolorSystem default valueColor of any text contained in the cellThe value is inherited by children cells but can be overridden
Common attributesRead about `common`
ididentifieremptyIdentifier of the elementThe 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)

  1. <?xml version="1.0" encoding="utf-8" ?>
  2. <SKIN background_color="#000000" author="Blue Cat Audio" language_version="1.0"/>

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

  1. <?xml version="1.0" encoding="utf-8" ?>
  2. <SKIN background_image="bg.bmp" author="Blue Cat Audio" language_version="1.0">
  3. </SKIN>

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

  1. <?xml version="1.0" encoding="utf-8" ?>
  2. <SKIN author="Blue Cat Audio" name="Skin with Bg" language_version="1.0" background_image="bg.bmp"
  3. repeat="true" layout_type="row" h_margin="5" v_margin="10" spacing="5">
  4. <IMAGE image="black_square.bmp" />
  5. <IMAGE image="black_square.bmp" />
  6. <IMAGE image="black_square.bmp" />
  7. <IMAGE image="black_square.bmp" />
  8. <IMAGE image="black_square.bmp" />
  9. <IMAGE image="black_square.bmp" />
  10. </SKIN>

 


Comments

2020 © Plug'n Script and KUIML by Blue Cat Audio  |  Site by LetiMix