IMAGE_PARAM_BUTTON

Active element that displays an image depending on the value of the parameter and that can be clicked to increment the value.

It is as an animation or 'filmstrip' for which the image is chosen depending on the value of the parameter: if the parameter value is equal to its minimum the first image is displayed. If the parameter value is equal to its maximum, the last image is displayed.

The control supports several keyboard shortcuts and mouse click. Each time the user clicks on the button, the parameter is incremented to next value (the number of possible values depending on the number of images). 

Attributes brief detailed show all inherited

	Name	Description	Default
Images
	image	Image file containing the list of images to displayIt is a single image containing a 'film strip' with many images. It can be vertical or horizontal, see the image_orientation attribute	empty
	image_disabled	Image file containing the list of images to display when the control is disabledThis value is optional since by default it is generated from 'image'	'image'...
	image_hover	Image file containing the list of images to display when the mouse is overThis value is optional since by default it is generated from 'image'	'image'...
	image_focus	Image file containing the list of images to display when the control has focusThis value is optional since by default it is generated from 'image'	'image'...
	image_pushed	Image file containing the list of images to display when the button is pushedThis value is optional since by default it is generated from 'image'	'image'...
Transparency masks (mainly for legacy .bmp, because .png supports built-in transparency)
	image_mask	Path to the alpha mask for the appropriate imageThis value is optional since by default it is generated from 'image'	'image'...
	image_disabled_mask	Path to the alpha mask for the appropriate imageThis value is optional since by default it is generated from 'image'	'image_...
	image_hover_mask	Path to the alpha mask for the appropriate imageThis value is optional since by default it is generated from 'image'	'image_...
	image_focus_mask	Path to the alpha mask for the appropriate imageThis value is optional since by default it is generated from 'image'	'image_...
	image_pushed_mask	Path to the alpha mask for the appropriate imageThis value is optional since by default it is generated from 'image'	'image_...
Other settings
	images_count	Number of images in the film strips contained in the image filesAll image files must contain the same number of images	2
	image_orientation	Orientation of the image file containing the film strip images	vertical
	loop	Enable loop for the the button valuesWhen disabled, the button won't loop back to the minimum value when reaching the maximum value	true
Inherited from images
	image_scaling	Scaling of the image1 is 100%, 0.5 is 50%	1
	image_mouse_mask	Path to the image file used to define the 'active' (clickable) zone of the imagethis is the zone of the image where the mouse is detected for clicks and movements. If we want the mouse to be active only on the round part of the knob in the previous example, we can add a sample_mouse_mask.bmp file which defines where the mouse is active. The white parts is active area, black parts - inactive. There is also image_focus_mouse_mask and image_hover_mouse_mask for very specific cases.	empty
	opaque_mouse_mask	When set to 'true' makes the entire area of the widget clickable (if mouse sensitive)Note that image_mouse_mask="" and opaque_mouse_mask="true" seem to do the same. The slight difference is that opaque_mouse_mask entirely bypasses the whole image finding algorithm, so it is faster than having the equivalent such as image_mouse_mask="", image_focus_mouse_mask="", image_hover_mouse_mask="".	false
	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 param_controls
	fine_ratio	Ratio between the fine tuning positions count and the positions_count attributeThe larger this value, the more precise the control is when the 'SHIFT' key is pushed	10
	reset_modifier_key	Modifier key for resetting the parameter value to default with a mouse clickPlease note that changing this value should be done carefuly to ensure consistency	'alt'
Read-only (may work on some controls)
	pushed	Set to true when the control is "pressed" or "pushed". *If it doesn't work use 'mouse_down'Can be used for example like 'control_id.pushed.value_changed' in ACTION_TRIGGER. Can be replaced by "mouse_down" available on all Widgets.
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 param_widgets
	param_id	Identifier of the parameter to displayThis value is mandatory. Param controls cannot not refer to a an output param since output parameters are read-only	empty
	reverse	Parameter widgets displays the parameter value the other way roundFor example a reverse vertical slider will have its value raised when moving from top to bottom instead of bottom to top	false
	positions_count	Number of states of the param control or viewerThis number may be used to limit the number of states that the param widget can have. For example a LINEAR_PARAM_METER that displays 5 LEDs will need 6 states. But if the parameter to display is an integer with only 3 possible values, the real number of states will be 3	Depends...
	response_curve	The response curve of the control or viewer: this is the function used to transform the position of the viewer to the parameter valueThis attribute is very useful when you need different precision of the control (or viewer) in different zones of the parameter value	'linear'
	scale	Parameter pre-scalingThis attribute is very useful when you need a specific scale for the parameter. The main difference between the scale and response_curve attributes is that the scale is computed on the parameters values, whereas the response_curve is used on the positions (0 to 1) range	'linear'
	zoom	Zoom on the parameter rangeThis attribute enables you to zoom the parameter range to display/control a portion of the parameter range only. The exact range is also controlled by the offset parameter	1
	offset	offset on the parameter rangeThis attribute is active only when the zoom parameter has a value different from 1. You can then control where the parameter range starts (0 means that the parameter range starts with its minimum value, 1 means that it ends with its maximum value, and .5 means that the range is centered)	0
	max_zoom	Maximum value allowed for the exposed zoom parameter	1
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...
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
Images
	image	image file path	empty	Image file containing the list of images to display	It is a single image containing a 'film strip' with many images. It can be vertical or horizontal, see the image_orientation attribute
	image_disabled	image file path	'image' value with '_disabled' postfix	Image file containing the list of images to display when the control is disabled	This value is optional since by default it is generated from 'image'
	image_hover	image file path	'image' value with '_hover' postfix	Image file containing the list of images to display when the mouse is over	This value is optional since by default it is generated from 'image'
	image_focus	image file path	'image' value with '_focus' postfix	Image file containing the list of images to display when the control has focus	This value is optional since by default it is generated from 'image'
	image_pushed	image file path	'image' value with '_pushed' postfix	Image file containing the list of images to display when the button is pushed	This value is optional since by default it is generated from 'image'
Transparency masks (mainly for legacy .bmp, because .png supports built-in transparency)
	image_mask	image file path	'image' value with '_mask' postfix	Path to the alpha mask for the appropriate image	This value is optional since by default it is generated from 'image'
	image_disabled_mask	image file path	'image_disabled' value with '_mask' postfix	Path to the alpha mask for the appropriate image	This value is optional since by default it is generated from 'image'
	image_hover_mask	image file path	'image_hover' value with '_mask' postfix	Path to the alpha mask for the appropriate image	This value is optional since by default it is generated from 'image'
	image_focus_mask	image file path	'image_focus' value with '_mask' postfix	Path to the alpha mask for the appropriate image	This value is optional since by default it is generated from 'image'
	image_pushed_mask	image file path	'image_pushed' value with '_mask' postfix	Path to the alpha mask for the appropriate image	This value is optional since by default it is generated from 'image'
Other settings
	images_count	Positive integer	2	Number of images in the film strips contained in the image files	All image files must contain the same number of images
	image_orientation	orientation	vertical	Orientation of the image file containing the film strip images
	loop	boolean	true	Enable loop for the the button values	When disabled, the button won't loop back to the minimum value when reaching the maximum value
Inherited from images
	image_scaling	float	1	Scaling of the image	1 is 100%, 0.5 is 50%
	image_mouse_mask	image file path	empty	Path to the image file used to define the 'active' (clickable) zone of the image	this is the zone of the image where the mouse is detected for clicks and movements. If we want the mouse to be active only on the round part of the knob in the previous example, we can add a sample_mouse_mask.bmp file which defines where the mouse is active. The white parts is active area, black parts - inactive. There is also image_focus_mouse_mask and image_hover_mouse_mask for very specific cases.
	opaque_mouse_mask	boolean	false	When set to 'true' makes the entire area of the widget clickable (if mouse sensitive)	Note that image_mouse_mask="" and opaque_mouse_mask="true" seem to do the same. The slight difference is that opaque_mouse_mask entirely bypasses the whole image finding algorithm, so it is faster than having the equivalent such as image_mouse_mask="", image_focus_mouse_mask="", image_hover_mouse_mask="".
	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 param_controls
	fine_ratio	positive integer	10	Ratio between the fine tuning positions count and the positions_count attribute	The larger this value, the more precise the control is when the 'SHIFT' key is pushed
	reset_modifier_key	'alt' or 'control'	'alt'	Modifier key for resetting the parameter value to default with a mouse click	Please note that changing this value should be done carefuly to ensure consistency
Read-only (may work on some controls)
	pushed	boolean		Set to true when the control is "pressed" or "pushed". *If it doesn't work use 'mouse_down'	Can be used for example like 'control_id.pushed.value_changed' in ACTION_TRIGGER. Can be replaced by "mouse_down" available on all Widgets.
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 param_widgets
	param_id	param id	empty	Identifier of the parameter to display	This value is mandatory. Param controls cannot not refer to a an output param since output parameters are read-only
	reverse	boolean	false	Parameter widgets displays the parameter value the other way round	For example a reverse vertical slider will have its value raised when moving from top to bottom instead of bottom to top
	positions_count	Positive integer	Depends on parameter and control	Number of states of the param control or viewer	This number may be used to limit the number of states that the param widget can have. For example a LINEAR_PARAM_METER that displays 5 LEDs will need 6 states. But if the parameter to display is an integer with only 3 possible values, the real number of states will be 3
	response_curve	response curve	'linear'	The response curve of the control or viewer: this is the function used to transform the position of the viewer to the parameter value	This attribute is very useful when you need different precision of the control (or viewer) in different zones of the parameter value
	scale	'linear' or 'log'	'linear'	Parameter pre-scaling	This attribute is very useful when you need a specific scale for the parameter. The main difference between the scale and response_curve attributes is that the scale is computed on the parameters values, whereas the response_curve is used on the positions (0 to 1) range
	zoom	real number in the [1;+oo] range.	1	Zoom on the parameter range	This attribute enables you to zoom the parameter range to display/control a portion of the parameter range only. The exact range is also controlled by the offset parameter
	offset	real number in the [0;1] range.	0	offset on the parameter range	This attribute is active only when the zoom parameter has a value different from 1. You can then control where the parameter range starts (0 means that the parameter range starts with its minimum value, 1 means that it ends with its maximum value, and .5 means that the range is centered)
	max_zoom	real number in the [1;+oo] range.	1	Maximum value allowed for the exposed zoom parameter
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
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 'On/Off' two states button (in this case a switch and a checkbox) for a boolean parameter from the default skin.

The original image for the switch has two sprites placed vertically.
By the way, using opaque_mouse_mask="true" we can make the whole image react to mouse events (otherwise the empty parts of the image will be ignored).

Another image check_box.svg also has two sprites.

Notice that because it is a vector image it can be scaled freely without loosing sharpness using image_scaling attribute.

Improving user experience

You also can add disabled/hover/focus/pushed images for IMAGE_PARAM_BUTTON to make your control look slighly different in different states. Simple example from the default theme, where "pushed" control displays its thumb centered:

There are two images for that control:

 h_select_switch.png and  h_select_switch_pushed.png

Multiple param values

You can have an image with multiple sprites to control several "steps" of a parameter. Say your parameter can have values from 0 to 20. Then you create an image with 20 sprites and set images_count="20" in IMAGE_PARAM_BUTTON.

Noticed we also used loop="false" so that after reaching last value param doesn't roll back to the first one.

For the demo we used an LED image from the default theme with 21 sprites in it, but in practice the IMAGE_PARAM_BUTTON is used for boolean parameters or integer parameters that do not have more than 3 values.

More info

As with other "IMAGE" controls, IMAGE_PARAM_BUTTON is often used with DEFINE to create a reusable item. See an example in IMAGE_ACTION_BUTTON.

If you need an invisible control with same mouse behaviour (but without the image) see INVISIBLE_PARAM_BUTTON.