IMAGE

Passive element (does not respond to mouse or keyboard) that displays a single image.

For more information about image files, see the Images section.

Attributes brief detailed show all inherited

	Name	Description	Default
	image	Path to the image to displayFor more information see the Images section	empty
	image_mask	Path to the alpha mask for the image (optional)This value is optional since by default it uses the same path as the 'image' attributes, to which it concatenates '_mask'. See examples below	Image v...
	stretch	Enables or disables background image stretching (resize)If set to 'true' and if the widget contains other widgets or has its size set, the image will be stretched to cover the whole surface of the resulting cell (incompatible with the repeat attribute)	false
	repeat	Enables or disables the repetition of the imageIf set to 'true' and if the widget contains other widgets or has its size set, the image will be repeated to cover the whole surface of the resulting cell (incompatible with the stretch attribute)	false
Inherited from images
	image_scaling	Scaling of the image1 is 100%, 0.5 is 50%	1
	ignore_mask_file	When set to "true" mask file is not used
	ignore_mouse_mask_file	When set to "true" mouse mask file is not used
	ignore_mask_files	When set to "true" mask files are not used	false
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
	accept_focus	When set to false, the widget will not accept keyboard focus (ignored). (Experimental)	true
	buffered	Enable or disable buffering of the widget.For example CANVAS with buffered="true" will make the render_script to run less often, because the buffered image would be used for redraw.	false
	transparent	Enable or disable transparency for the widget.Can help with performance issues.	false
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 listExperimental 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)
	mouse_wheel_up	Event fired when a mouse wheel is turned upExperimental
	mouse_wheel_down	Event fired when a mouse wheel is turned upExperimental
	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.characters	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.characters	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...
Common attributes
	id	Identifier of the elementThe id of an element has to be globally unique. Don't start with a digit for AngelScript compatibility.	empty
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 cells ("Arial")Fonts 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 cell ("12" or "+2" or "120%")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	System...
	font_weight	("bold" or "normal") Weight of the font for any text contained in the cellThe value is inherited by children cells but can be overridden	System...
	font_style	("italic" or "normal") 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 font ("default" or "no_anti_alias" or "anti_alias" or "cleartype")The value is inherited by children cells but can be overridden	System...
	font_escapement	Escapement - angle in degrees to rotate text ("90")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	0
	text_decoration	("underline" or "none") Decoration of the text for any text contained in the cellThe value is inherited by children cells but can be overridden. * Note by editor: works sometimes, not very stable	System...
	text_color	Color of any text contained in the cell ("#FF0000")The value is inherited by children cells but can be overridden	System...

	Name	Value type	Default	Description	Comment
	image	image file path	empty	Path to the image to display	For more information see the Images section
	image_mask	image file path	Image value with _mask postfix	Path to the alpha mask for the image (optional)	This value is optional since by default it uses the same path as the 'image' attributes, to which it concatenates '_mask'. See examples below
	stretch	boolean	false	Enables or disables background image stretching (resize)	If set to 'true' and if the widget contains other widgets or has its size set, the image will be stretched to cover the whole surface of the resulting cell (incompatible with the repeat attribute)
	repeat	boolean	false	Enables or disables the repetition of the image	If set to 'true' and if the widget contains other widgets or has its size set, the image will be repeated to cover the whole surface of the resulting cell (incompatible with the stretch attribute)
Inherited from images
	image_scaling	float	1	Scaling of the image	1 is 100%, 0.5 is 50%
	ignore_mask_file			When set to "true" mask file is not used
	ignore_mouse_mask_file			When set to "true" mouse mask file is not used
	ignore_mask_files	boolean	false	When set to "true" mask files are not used
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.
	accept_focus	boolean	true	When set to false, the widget will not accept keyboard focus (ignored). (Experimental)
	buffered	boolean	false	Enable or disable buffering of the widget.	For example CANVAS with buffered="true" will make the render_script to run less often, because the buffered image would be used for redraw.
	transparent	boolean	false	Enable or disable transparency for the widget.	Can help with performance issues.
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 listExperimental 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)
	mouse_wheel_up	event		Event fired when a mouse wheel is turned up	Experimental
	mouse_wheel_down	event		Event fired when a mouse wheel is turned up	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.characters	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.characters	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
Common attributes
	id	identifier	empty	Identifier of the element	The id of an element has to be globally unique. Don't start with a digit for AngelScript compatibility.
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 ("Arial")	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 ("12" or "+2" or "120%")	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_weight	'bold' or 'normal'	System default value	("bold" or "normal") 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	("italic" or "normal") 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 ("default" or "no_anti_alias" or "anti_alias" or "cleartype")	The value is inherited by children cells but can be overridden
	font_escapement	real number	0	Escapement - angle in degrees to rotate text ("90")	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		System default value	("underline" or "none") Decoration of the text for any text contained in the cell	The value is inherited by children cells but can be overridden. * Note by editor: works sometimes, not very stable
	text_color	color	System default value	Color of any text contained in the cell ("#FF0000")	The value is inherited by children cells but can be overridden

Examples

Display an opaque image, with default attributes values:

Now let's play with repeat and stretch attributes. For that we need to set width/height for the image. Also note the use of image_scaling.

Transparency

If we want to add transparency to our image, we could either use image formats that support transparency (like .png) or just add a mask file named 'image_mask.bmp' in the same directory, the system will automatically find it and associate it to our image which file name is 'image.bmp'. Read more about image file naming conventions in the Images section.

The image is fully transparent when the image mask is black, and fully opaque when the image mask is white. The intermediate values (grey) are taken into account and the image then becomes partially transparent (visible here on the shadow of the image).

Nested images

Another use of images is to serve as background for other widgets. We can use for example a repeated image as background for other widgets (we used the same image here as widget). The widgets just need to be inserted inside the background IMAGE tag, and since the IMAGE widget is a layout cell, we can adjust the layout properties of the included widgets (with 'layout_type' and 'spacing' attributes here):

For more advanced capabilities, see the IMAGE_GROUP_BOX widget: it adapts the size of the graphics to the size of the contained widgets.