March 30, 2021

KUIML_WIDGET

Widget that can dynamically load KUIML code ("sub-skin") via a file or string. It can be used to load different content depending on the context, or load parts of a skin dynamically, only when required.

Warning: because all objects in KUIML may be stripped when not used by the skin, you need to make sure that the data accessed by the content of a sub-skin that is loaded at runtime will not be stripped, using for example the REQUIRED_OBJECTS element.

Attributes brief detailed show all inherited

	Name	Description	Default
	src	path to the kuiml file to load (relative to current skin path, root_path attribute or absolute)	empty
	innerKUIML	KUIML code to be loaded by the widgetOverrides the src attribute when set (loads KUIML code from a string instead of file)	empty
	root_path	List of root directories that can be used as root paths, separated by ';'Root paths used to find skin files defined by relative paths. This is useful when the root location of the skin files may change (Mac vs Windows, or username dependent paths etc.)	empty
	persistent	Sets the persistency of the widgetWhen this property is set to 'true', the content of the KUIML widget is persistent: this includes the source (file or string) as well as the content of all persistent objects created inside the sub-skin	false
	load_enabled	When set to false, KUIML content is not loaded even when explicitly set by a script or linkThis attribute can be used for lazy loading KUIML widgets (loading on demand). Set to false by default and set to true when skin loading required	true
	import_templates	Import TEMPLATEs from parent skinSet this to false if you don't need parent skin templates and thus speed up loading	true
	import_defines	Import DEFINEs from parent skinSet this to false if you don't need parent skin defines and thus speed up loading	true
	import_variables	Import VARIABLEs from parent skinSet this to false if you don't need parent skin variables and thus speed up loading	true
Inherited from widgets
	opacity	Opacity of the widget0% is totally transparent, 100% is opaque	100%
	visible	Show/hide the widget, does not impact the layout, as opposed to the cell's display attribute	true
	enabled	Enable/disable the widget. When disabled, the widget does not react to mouse or keyboard events. it is displayed but inactive.	true
	cursor	Cursor to display when the mouse is over the active part of the widgetThis property works only for mouse sensitive (aka non-passive) widgets	System...
	mouse_sensitive	Enables or disables mouse control on widgetsWarning: for advanced users only. Do not use this property that is set according to widget type, except if you really want to force mouse sensitivity (to enable cursor change etc.)	Dependi...
	auto_focus	Enables or disables auto focusWhen enabled, a widget gets focus when the mouse is over it (you do not need to click on it). When a widget has focus it receives the keyboard events. auto_focus works for mouse_sensitive widgets	Dependi...
	handled_keys	List of keys handled by the widget, which will trigger key_pressed and key_released events(Experimental) Use the character correponding to the selected key or 'all' for all keys, or one of the following for system keys: F1-F20, Enter, Space, Tab, Esc, Shift, Alt, Cmd, Ctrl, ArrowUp, ArrowDown, ArrowLeft, ArrowRight, PgUp, PgDn, Insert, Delete, BackSpace	empty
	default_keys_enabled	Enable or disable the default keys handled natively by the widget.(Experimental) you can disable the default keyboard behavior for any widget if you want to write your own.	true
Drag and Drop Attributes
	drag_source_ids	List of objects to use as drag sources for drag and drop operations (each one may have a different applicative type)	empty
	drag_applicative_types	List of applicative types to use for each drag source defined by the drag_source_ids list Experimental since 2.7: use the system::text applicative type to drag the content of a parameter or string as system text (can be dropped into any application that supports drag and drop of text content)	empty
	drag_operations	List of drag operations allowed. 'copy' or 'move' operations are currently supported	empty
	drag_context	Optional string to define the serialization context used for the drag operation	empty
	drag_enabled	Enable drag operations on the widget	true
	drop_target_ids	List of objects to use as drop targets for drag and drop operations (each one may have a different applicative type)	empty
	drop_applicative_types	List of applicative types to use for each drop target defined by the drop_target_ids list. Experimental since 2.7: use the system::text applicative type to drop text directly into a parameter or string	empty
	drop_file_types	List of supported file types to use for each drop target defined by the drop_target_ids list. Each wild card may contain several extensions, separated by ','. For example, with ".;.doc,.txt", the first drop target will accept all files, and the second one will accept only .doc and .txt files	empty
	dropped_file_path_string_ids	List of string objects than can receive the path of a file that was dropped, for each drop target defined by the drop_target_ids list	empty
	drop_context	Optional string to define the deserialization context used for the drop operation	empty
	drop_enabled	Enable drop operations on the widget	true
Exposed Attributes And Events (read-only)
	mouse_over	Set to true when the mouse is over the active area of the widget	false
	mouse_down	Bit field containing the state of mouse buttons: first bit is left button, second is right and third is mid button. When no button is pushed, the value of mouse_down is zeroExperimental	0
	mouse_position.x	Horizontal position of the mouse in the widget (relative to the upper left corner of the widget)The value is valid only when the mouse is over the widget or being dragged out of it (experimental)
	mouse_position.y	Vertical position of the mouse in the widget (relative to the upper left corner of the widget)The value is valid only when the mouse is over the widget or being dragged out of it (experimental)
	mouse_screen_position.x	Absolute horizontal position of the mouse on the screenThe value is valid only when the mouse is over the widget or being dragged out of it (experimental)
	mouse_screen_position.y	Absolute vertical position of the mouse on the screenThe value is valid only when the mouse is over the widget or being dragged out of it (experimental)
	focus	Set to true when the widget has keyboard focus and receives keyboard events	false
	key_pressed	Event fired when a key (filtered by the handled_key list) is pressedExperimental
	key_pressed.key	last virtual key that was pressedExperimental: enum values are subject to change, check the displayed value (text)
	key_pressed.character	Character(s) corresponding to the last pressed key, if it was a character key (key_pressed.key=0)Experimental
	key_released	Event fired when a key (filtered by the handled_key list) is released
	key_released.key	last virtual key that was releasedExperimental: enum values are subject to change, check the displayed value (text)
	key_released.character	Character(s) corresponding to the last released key, if it was a character key (key_released.key=0)Experimental
	dragging	Set to true when a dragging operation is in progress for this widget	false
	drag_operation	type of the current drag operation (None, Copy, Move)Experimental: enum values are subject to change	enumera...
	dropping	Set to true when a dropping operation is in progress for this widget	false
	drop_operation	type of the current drop operation (None, Copy, Move)Experimental: enum values are subject to change	enumera...
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
	src	File path	empty	path to the kuiml file to load (relative to current skin path, root_path attribute or absolute)
	innerKUIML	string	empty	KUIML code to be loaded by the widget	Overrides the src attribute when set (loads KUIML code from a string instead of file)
	root_path	string	empty	List of root directories that can be used as root paths, separated by ';'	Root paths used to find skin files defined by relative paths. This is useful when the root location of the skin files may change (Mac vs Windows, or username dependent paths etc.)
	persistent	boolean	false	Sets the persistency of the widget	When this property is set to 'true', the content of the KUIML widget is persistent: this includes the source (file or string) as well as the content of all persistent objects created inside the sub-skin
	load_enabled	boolean	true	When set to false, KUIML content is not loaded even when explicitly set by a script or link	This attribute can be used for lazy loading KUIML widgets (loading on demand). Set to false by default and set to true when skin loading required
	import_templates	boolean	true	Import TEMPLATEs from parent skin	Set this to false if you don't need parent skin templates and thus speed up loading
	import_defines	boolean	true	Import DEFINEs from parent skin	Set this to false if you don't need parent skin defines and thus speed up loading
	import_variables	boolean	true	Import VARIABLEs from parent skin	Set this to false if you don't need parent skin variables and thus speed up loading
Inherited from widgets
	opacity	percentage	100%	Opacity of the widget	0% is totally transparent, 100% is opaque
	visible	boolean	true	Show/hide the widget, does not impact the layout, as opposed to the cell's display attribute
	enabled	boolean	true	Enable/disable the widget. When disabled, the widget does not react to mouse or keyboard events. it is displayed but inactive.
	cursor	cursor	System Default	Cursor to display when the mouse is over the active part of the widget	This property works only for mouse sensitive (aka non-passive) widgets
	mouse_sensitive	boolean	Depending on widget	Enables or disables mouse control on widgets	Warning: for advanced users only. Do not use this property that is set according to widget type, except if you really want to force mouse sensitivity (to enable cursor change etc.)
	auto_focus	boolean	Depending on widget, usually 'true' for mouse_sensitive widgets	Enables or disables auto focus	When enabled, a widget gets focus when the mouse is over it (you do not need to click on it). When a widget has focus it receives the keyboard events. auto_focus works for mouse_sensitive widgets
	handled_keys	list of keys, separated by ;	empty	List of keys handled by the widget, which will trigger key_pressed and key_released events	(Experimental) Use the character correponding to the selected key or 'all' for all keys, or one of the following for system keys: F1-F20, Enter, Space, Tab, Esc, Shift, Alt, Cmd, Ctrl, ArrowUp, ArrowDown, ArrowLeft, ArrowRight, PgUp, PgDn, Insert, Delete, BackSpace
	default_keys_enabled	boolean	true	Enable or disable the default keys handled natively by the widget.	(Experimental) you can disable the default keyboard behavior for any widget if you want to write your own.
Drag and Drop Attributes
	drag_source_ids	list of identifiers, separated by ';'	empty	List of objects to use as drag sources for drag and drop operations (each one may have a different applicative type)
	drag_applicative_types	list of applicative types, separated by ';'	empty	List of applicative types to use for each drag source defined by the drag_source_ids list Experimental since 2.7: use the system::text applicative type to drag the content of a parameter or string as system text (can be dropped into any application that supports drag and drop of text content)
	drag_operations	list of drag operations separated by ';'	empty	List of drag operations allowed. 'copy' or 'move' operations are currently supported
	drag_context	string	empty	Optional string to define the serialization context used for the drag operation
	drag_enabled	boolean	true	Enable drag operations on the widget
	drop_target_ids	list of identifiers, separated by ';'	empty	List of objects to use as drop targets for drag and drop operations (each one may have a different applicative type)
	drop_applicative_types	list of applicative types, separated by ';'	empty	List of applicative types to use for each drop target defined by the drop_target_ids list. Experimental since 2.7: use the system::text applicative type to drop text directly into a parameter or string
	drop_file_types	list of file types wildcards, separated by ';'	empty	List of supported file types to use for each drop target defined by the drop_target_ids list. Each wild card may contain several extensions, separated by ','. For example, with ".;.doc,.txt", the first drop target will accept all files, and the second one will accept only .doc and .txt files
	dropped_file_path_string_ids	list of string object identifiers types, separated by ';'	empty	List of string objects than can receive the path of a file that was dropped, for each drop target defined by the drop_target_ids list
	drop_context	string	empty	Optional string to define the deserialization context used for the drop operation
	drop_enabled	boolean	true	Enable drop operations on the widget
Exposed Attributes And Events (read-only)
	mouse_over	boolean	false	Set to true when the mouse is over the active area of the widget
	mouse_down	integer	0	Bit field containing the state of mouse buttons: first bit is left button, second is right and third is mid button. When no button is pushed, the value of mouse_down is zero	Experimental
	mouse_position.x	integer		Horizontal position of the mouse in the widget (relative to the upper left corner of the widget)	The value is valid only when the mouse is over the widget or being dragged out of it (experimental)
	mouse_position.y	integer		Vertical position of the mouse in the widget (relative to the upper left corner of the widget)	The value is valid only when the mouse is over the widget or being dragged out of it (experimental)
	mouse_screen_position.x	integer		Absolute horizontal position of the mouse on the screen	The value is valid only when the mouse is over the widget or being dragged out of it (experimental)
	mouse_screen_position.y	integer		Absolute vertical position of the mouse on the screen	The value is valid only when the mouse is over the widget or being dragged out of it (experimental)
	focus	boolean	false	Set to true when the widget has keyboard focus and receives keyboard events
	key_pressed	event		Event fired when a key (filtered by the handled_key list) is pressed	Experimental
	key_pressed.key	enum		last virtual key that was pressed	Experimental: enum values are subject to change, check the displayed value (text)
	key_pressed.character	string		Character(s) corresponding to the last pressed key, if it was a character key (key_pressed.key=0)	Experimental
	key_released	event		Event fired when a key (filtered by the handled_key list) is released
	key_released.key	enum		last virtual key that was released	Experimental: enum values are subject to change, check the displayed value (text)
	key_released.character	string		Character(s) corresponding to the last released key, if it was a character key (key_released.key=0)	Experimental
	dragging	boolean	false	Set to true when a dragging operation is in progress for this widget
	drag_operation	boolean	enumeration	type of the current drag operation (None, Copy, Move)	Experimental: enum values are subject to change
	dropping	boolean	false	Set to true when a dropping operation is in progress for this widget
	drop_operation	boolean	enumeration	type of the current drop operation (None, Copy, Move)	Experimental: enum values are subject to change
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

Notes on using "sub-skins"

Separate script space. Every subskin has its own scripting space. So if you have a function or an object/variable in the script of the main SKIN, it won't be available in the subskin. It also means that scripts in skin and subskin cannot communicate directly through script variables, only through the main skin's params and strings (exposed to both skin and sub-skin scripts).
Subskin can import DEFINES, TEMPLATES, and VARIABLES that were defined in the parent skin before the KUIML_WIDGET element (by default it imports all of them, but you can disable importing of any type to speed up loading). VARIABLES set inside the main SKIN are accessible inside the subskin, though only those that were defined before that KUIML_WIDGET. Also if you change these VARIABLES inside "sub-skin" they won't update in the main SKIN (because the main skin is loaded and parsed before subskins).
Subskins can communicate with the parent skin via params and strings defined in the main skin. Usually, these params should be explicitly mentioned in EXPOSED_OBJECTS (to be used in scripts) and REQUIRED_OBJECTS (to be not stripped and available inside the subskin).