<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<?xml-stylesheet href="./_c74_ref.xsl" type="text/xsl"?>

<c74object name="icst.button" module="ICST Ambisonics">

    <digest>
	A graphical user interface as button or toggle-switch.
    </digest>

    <description>
		A graphical user interface as button or toggle-switch with extended graphical elements: labels, prefix, borders, icons and images. <br/>
		The object operates in two modes:
		<ul>
			<li><bi>switch</bi> between 0 and 1 or settable message(s).</li>			
			<li><bi>button</bi> outputs a bang or settable message(s).</li>
		</ul>
	</description>

    <!--METADATA-->
    <metadatalist>
	<metadata name="author">ICST | Zurich University of the Arts</metadata>
	<metadata name="tag">ICST Ambisonics</metadata>
	<metadata name="copyright">
	 © 2009 - 2021 ICST | Zurich University of the Arts
	</metadata>
	<metadata name="version">
	1.3 (Build 02/2021)
	</metadata>
    </metadatalist>

    <!--DISCUSSION-->
    <discussion>

    </discussion>

    <!--INLETS-->
    <!--do not use-->
    <inletlist>
    </inletlist>

    <!--OUTLETS-->
    <!--do not use-->
    <outletlist>
    </outletlist>

    <!--ARGUMENTS-->
    <!-- <objarglist>
    </objarglist> -->

    <!--MESSAGES-->
    <methodlist>
	<method name="bang">
	    <description>
			<p>In mode <bi>switch</bi>: flips state and outputs new state.</p>
			<p>In mode <bi>button</bi>: triggers button and outputs bang message.</p>
	    </description>
	</method>
	
	<method name="int">
	    <description>
			<p>In mode <bi>switch</bi>: non-zero value sets state to 1/on and outputs input-value, zero-value sets state to 0/off and outputs 0.</p>
			<p>In mode <bi>button</bi>: any value triggers button and outputs bang message.</p>
	    </description>
	</method>	

	<method name="float">
	    <description>
			<p>In mode <bi>switch</bi>: greater than 1/-1 value sets state to 1/on and outputs input-value, truncated zero-value sets state to 0/off and outputs 0.</p>
			<code>
				state = fabs(f) >= 1. ? (int)f : 0;
			</code>
			<p>In mode <bi>button</bi>: any value triggers button and outputs bang message.</p>

	    </description>
	</method>		

	<method name="list">
	    <description>
			<p>In mode <bi>switch</bi>: first element is treated as an <m>int</m> or <m>float</m> message, other elements are discarded.</p>
			<p>In mode <bi>button</bi>: any value triggers button and outputs bang message.</p>
	    </description>
	</method>
	
	<method name="anything">
	    <description>
			<p>In mode <bi>switch</bi>: anything is treated as an <m>bang</m> message.</p>
			<p>In mode <bi>button</bi>: anything triggers the button and outputs bang message.</p>
	    </description>
	</method>
	
	<method name="set">
	    <description>
			<p>In mode <bi>switch</bi>: set value and paint it without output.</p>
			<p>In mode <bi>button</bi>: receive and paint bang without output.</p>
	    </description>
	</method>
	
	<method name="version">
	    <description>
			Print version information to Max' console window.
	    </description>
	</method>
	<method name="report">
	    <description>
			Print version information to Max' console window.
	    </description>
	</method>
    </methodlist>

    <!--ATTRIBUTES-->
    <attributelist>
	<attribute name="mode" get="0" set="0" type="symbol" size="1" value="Button Mode">
	    <description>
			Modes: switch and button.
		</description>
	</attribute>
	
	<attribute name="blinktime" get="0" set="0" type="int" size="1" value="Button Blink Duration">
	    <description>
			In mode <bi>button</bi>: When triggered from outside, the duration of painted ON state (default value is 100 ms).
	    </description>
	</attribute>
	
	<!-- Border-->
	<attribute name="borderstyle" get="0" set="0" type="int" size="1" value="Border Style Off">
	    <description>
			<p>The style for the border in OFF state (default: Rectangle).</p>
			<p>Options are:</p>
			<ul>
				<li>Off</li>
				<li>Rectangle</li>
				<li>Rounded Rectangle</li>
				<li>Brackets Vertical</li>
				<li>Brackets Horizontal</li>
				<li>Brackets Horizontal</li>
				<li>Corners</li>
				<li>Triangles</li>
				<li>Dots</li>
			</ul>
	    </description>
	</attribute>
	
	<attribute name="on_borderstyle" get="0" set="0" type="int" size="1" value="Border Style On">
	    <description>
			<p>The style for the border in ON state (default: Rectangle).</p>
			<p>Options are:</p>
			<ul>
				<li>Off</li>
				<li>Rectangle</li>
				<li>Rounded Rectangle</li>
				<li>Brackets Vertical</li>
				<li>Brackets Horizontal</li>
				<li>Brackets Horizontal</li>
				<li>Corners</li>
				<li>Triangles</li>
				<li>Dots</li>
			</ul>
	    </description>
	</attribute>
	
	<attribute name="borderwidth" get="0" set="0" type="float" size="1" value="Border Style Off">
	    <description>
			<p>The width of the border in OFF state (default: 1.0).</p>
	    </description>
	</attribute>
	
	<attribute name="on_borderwidth" get="0" set="0" type="float" size="1" value="Border Style On">
	    <description>
			<p>The width of the border in ON state (default: 2.0).</p>
	    </description>
	</attribute>
	
	<attribute name="bordersize" get="0" set="0" type="float" size="1" value="Border Element Size Off">
	    <description>
			<p>The size of the border element in OFF state (default: 4.0).</p>
	    </description>
	</attribute>
	
	<attribute name="on_bordersize" get="0" set="0" type="float" size="1" value="Border Element Size On">
	    <description>
			<p>The size of the border element in ON state (default: 4.0).</p>
	    </description>
	</attribute>
	
	<attribute name="bordercode" get="0" set="0" type="int" size="1" value="Border Element Size Off">
	    <description>
			<p>The code for the painting the border elements in OFF state (default: 15).</p>
			<p>Binary code to activate brackets, corners, triangles and dots.</p>
	    </description>
	</attribute>
	
	<attribute name="on_bordercode" get="0" set="0" type="int" size="1" value="Border Element Size On">
	    <description>
			<p>The code for the painting the border elements in ON state (default: 15).</p>
			<p>Binary code to activate brackets, corners, triangles and dots.</p>
	    </description>
	</attribute>
	
	<!-- ICON-->
	<attribute name="iconstyle" get="0" set="0" type="int" size="1" value="Icon Style">
	    <description>
			<p>The style of the icon (default: Cross).</p>
			<p>Options are:</p>
			<ul>
				<li>Off</li>
				<li>Cross</li>
				<li>Checkmark</li>
				<li>Revert Arrow</li>
				<li>Power Icon</li>
				<li>Play</li>
				<li>Stop</li>
				<li>Pause</li>
				<li>Record</li>
				<li>Fwd</li>
				<li>Rew</li>
				<li>Jump to Start</li>
				<li>Jump to End</li>
				<li>Round Dot</li>
				<li>Square Dot</li>
			</ul>
	    </description>
	</attribute>
	
	<attribute name="iconbackground" get="0" set="0" type="int" size="1" value="Icon Background">
	    <description>
			<p>The style of the icon background (default: Square Filled).</p>
			<p>Options are:</p>
			<ul>
				<li>Off</li>
				<li>Square Filled</li>
				<li>Circle Filled</li>
				<li>Square Frame</li>
				<li>Circular Frame</li>
			</ul>
	    </description>
	</attribute>

	<attribute name="iconsize" get="0" set="0" type="int" size="1" value="Icon Size">
	    <description>
			<p>The size of the icon (default: 19).</p>
	    </description>
	</attribute>
	

	<attribute name="iconlinewidth" get="0" set="0" type="int" size="1" value="Icon Foreground Line Width">
	    <description>
			<p>The line-width of the icon's foreground element (default: 2).</p>
	    </description>
	</attribute>
	
	<attribute name="iconbglinewidth" get="0" set="0" type="int" size="1" value="Icon background Line Width">
	    <description>
			<p>The line-width of the icon's background element (default: 2).</p>
	    </description>
	</attribute>
	
	<attribute name="iconoffset" get="0" set="0" type="float" size="2" value="Icon Position Offset">
	    <description>
			<p>The icon's position offset (default: 0.0 0.0).</p>
	    </description>
	</attribute>
	
	<!-- Image-->
	<attribute name="usesvg" get="0" set="0" type="int" size="1" value="Image Background Enabled">
	    <description>
			<p>Enable/Disable the use of an SVG image as background (default: 0/off).</p>
			<bluebox>
				<p>See image format in help-patcher, re: format of four states in a single image file.</p>
			</bluebox>
	    </description>
	</attribute>
	
	<attribute name="svgfile" get="0" set="0" type="file" size="1" value="SVG Background File">
	    <description>
			<p>The selected SVG image file.</p> 
	    </description>
	</attribute>
	
	
		<!-- Text-->
	<attribute name="uselabeltext" get="0" set="0" type="int" size="1" value="Enable Text Label">
	    <description>
			<p>Enable/Disable the text label in the button/switch (default: off).</p>
	    </description>
	</attribute>	

	<attribute name="useoutmessage" get="0" set="0" type="symbol" size="1" value="Message Output Type">
	    <description>
			<p>The message output type (default: Off).<br/><br/> Options are:</p> 
			<ul>
				<li>Off</li>
				<li>Prefix</li>
				<li>Label</li>
				<li>Message</li>
			</ul>
			
			<p><m>Prefix</m> is prepended to state-value</p> 
			<p><m>Label</m> is output instead of state-value, reflecting the on/off state</p> 
			<p><m>Message</m> is output instead of state-value, reflecting the on/off state</p> 	
	    </description>
	</attribute>	

	<attribute name="onlabeltext" get="0" set="0" type="symbol" size="1" value="Label Text On (Switch)">
	    <description>
			<p>Label text on. Mode switch (default: 'On')</p> 
	    </description>
	</attribute>

	<attribute name="offlabeltext" get="0" set="0" type="symbol" size="1" value="Label Text Off (Switch and Button)">
	    <description>
			<p>Label text off. Mode switch (default: 'Off')</p> 
	    </description>
	</attribute>
	
	<attribute name="onoutputtext" get="0" set="0" type="symbol" size="1" value="Message Text On (Switch)">
	    <description>
			<p>Message text on. Mode switch (default: 'On')</p> 
	    </description>
	</attribute>

	<attribute name="offoutputtext" get="0" set="0" type="symbol" size="1" value="Message Text Off (Switch and Button)">
	    <description>
			<p>Message text off. Mode switch (default: 'Off')</p> 
	    </description>
	</attribute>
	
	<attribute name="prefixtext" get="0" set="0" type="symbol" size="1" value="Prefix Text">
	    <description>
			<p>The prefix text (default: 'set').</p> 
	    </description>
	</attribute>
	
	<attribute name="textoffset" get="0" set="0" type="float" size="2" value="Offset Text Position">
	    <description>
			<p>Offset text position (default: 0.0 0.0).</p>
	    </description>
	</attribute>
	
	<attribute name="textalignment" get="0" set="0" type="int" size="1" value="Text Alignment">
	    <description>
			<p>Sets the text-alignment used. Options: <m>left</m>, <m>centered</m>, <m>right</m> (default: centered).</p>
	    </description>
	</attribute>
	
	<attribute name="onfontstyle" get="0" set="0" type="float" size="1" value="Font Style On">
	    <description>
			<p>Sets the type style used in the ON state. Options: <m>regular</m>, <m>bold</m>, <m>italic</m>, <m>bold italic</m> (default: bold).</p>
	    </description>
	</attribute>
	
	<attribute name="pviewfontsize" get="0" set="0" type="float" size="1" value="Presentation Font Size">
	    <description>
			<p>Sets the objects presentation font size [different from the patching font-size] (default: 12).</p>
	    </description>
	</attribute>
	
	
		
	<!-- Value-->
	<attribute name="outmultiplier" get="0" set="0" type="int" size="1" value="Output Value Multiplier">
	    <description>
			<p>Output value multiplier, i.e., multiplied with output value (default: 1).</p>
	    </description>
	</attribute>	
	
	<attribute name="outoffset" get="0" set="0" type="int" size="1" value="Enable Text Label">
	    <description>
			<p>Output value offset, i.e., added to output value (default: 0).</p>
	    </description>
	</attribute>
	

	<!-- Colors -->
	<attribute name="textcolor" get="0" set="0" type="rgba" size="1" value="Text Color">
	    <description>
			<p>Text label colour (default: 0.0 0.0 0.0 1.0).</p>
	    </description>
	</attribute>			
	
	<attribute name="on_down_textcolor" get="0" set="0" type="rgba" size="1" value="Color On Down Text">
	    <description>
			<p>On down text colour (default: 0.0 0.0 0.0 1.0).</p>
	    </description>
	</attribute>	
	
	<attribute name="off_up_textcolor" get="0" set="0" type="rgba" size="1" value="Color Off Up Text">
	    <description>
			<p>Off up text colour (default: 0.5 0.5 0.5 1.0).</p>
	    </description>
	</attribute>	
	
	<attribute name="off_down_textcolor" get="0" set="0" type="rgba" size="1" value="Color Off Down Text">
	    <description>
			<p>Off down text colour (default: 0.5 0.5 0.5 1.0).</p>
	    </description>
	</attribute>	

	<attribute name="on_up_fg_color" get="0" set="0" type="rgba" size="1" value="Color On Up Border">
	    <description>
			<p>On up border colour (default: 0.5 0.5 0.5 1.0).</p>
	    </description>
	</attribute>			

	<attribute name="on_up_bg_color" get="0" set="0" type="rgba" size="1" value="Color On Up Background">
	    <description>
			<p>On up background colour (default: 1.0 1.0 1.0 1.0).</p>
	    </description>
	</attribute>				

	<attribute name="on_down_fg_color" get="0" set="0" type="rgba" size="1" value="Color On Down Border">
	    <description>
			<p>On down border colour (default: 0.5 0.5 0.5 1.0).</p>
	    </description>
	</attribute>			

	<attribute name="on_down_bg_color" get="0" set="0" type="rgba" size="1" value="Color On Down Background">
	    <description>
			<p>On down background colour (default: 0.5 0.5 0.5 1.0).</p>
	    </description>
	</attribute>
		
	<attribute name="off_up_fg_color" get="0" set="0" type="rgba" size="1" value="Color Off Up Border">
	    <description>
			<p>Off up border colour (default: 0.5 0.5 0.5 1.0).</p>
	    </description>
	</attribute>			

	<attribute name="off_up_bg_color" get="0" set="0" type="rgba" size="1" value="Color Off Up Background">
	    <description>
			<p>Off up background colour (default: 1.0 1.0 1.0 1.0).</p>
	    </description>
	</attribute>				

	<attribute name="off_down_fg_color" get="0" set="0" type="rgba" size="1" value="Color Off Down Border">
	    <description>
			<p>Off down border colour (default: 0.5 0.5 0.5 1.0).</p>
	    </description>
	</attribute>			

	<attribute name="off_down_bg_color" get="0" set="0" type="rgba" size="1" value="Color Off Down Background">
	    <description>
			<p>Off down background colour (default: 1.0 0.8 0.0 1.0).</p>
	    </description>
	</attribute> 
	
	
	
	<attribute name="on_up_icon_fg_color" get="0" set="0" type="rgba" size="1" value="Color On Up Icon Foreground">
	    <description>
			<p>On up icon foreground colour (default: 0.25 0.25 0.25 1.0).</p>
	    </description>
	</attribute>			

	<attribute name="on_up_icon_bg_color" get="0" set="0" type="rgba" size="1" value="Color On Down Icon Foreground">
	    <description>
			<p>On down icon foreground colour (default: 1.0 1.0 1.0 1.0).</p>
	    </description>
	</attribute>				

	<attribute name="on_down_icon_fg_color" get="0" set="0" type="rgba" size="1" value="Color On Down Icon Foreground">
	    <description>
			<p>On down icon foreground colour (default: 0.5 0.5 0.5 1.0).</p>
	    </description>
	</attribute>			

	<attribute name="on_down_bicon_g_color" get="0" set="0" type="rgba" size="1" value="Color On Down Icon Background">
	    <description>
			<p>On down icon background colour (default: 1.0 1.0 1.0 1.0).</p>
	    </description>
	</attribute>
		
	<attribute name="off_up_icon_fg_color" get="0" set="0" type="rgba" size="1" value="Color Off Up Icon Foreground">
	    <description>
			<p>Off up icon foreground colour (default: 0.75 0.75 0.75 1.0).</p>
	    </description>
	</attribute>			

	<attribute name="off_up_icon_bg_color" get="0" set="0" type="rgba" size="1" value="Color Off Up Icon Background">
	    <description>
			<p>Off up icon background colour (default: 1.0 1.0 1.0 1.0).</p>
	    </description>
	</attribute>				

	<attribute name="off_down_icon_fg_color" get="0" set="0" type="rgba" size="1" value="Color Off Down Icon Foreground">
	    <description>
			<p>Off down icon foreground colour (default: 0.75 0.75 0.75 1.0).</p>
	    </description>
	</attribute>			

	<attribute name="off_down_icon_bg_color" get="0" set="0" type="rgba" size="1" value="Color Off Down Icon Background">
	    <description>
			<p>Off down icon background colour (default: 1.0 1.0 1.0 1.0).</p>
	    </description>
	</attribute>
	
		
	
    </attributelist>
	
	
    <misc name = "Input">
	<entry name ="Inlet 1 [bang, int, float, list, anything]">
	    <description>
			<p>In mode <bi>switch</bi>: value to set and output state.</p>
			<p>In mode <bi>button</bi>: bang, anything to output bang..</p>
	    </description>
	</entry>
    </misc>

    <misc name = "Output">
	<entry name ="Outlet 1 [list]">
	    <description>
			<p>In mode <bi>switch</bi>: outputs value or message.</p>
			<p>In mode <bi>button</bi>: outputs bang on mouse-down.</p>
	    </description>
	</entry>
	<entry name ="Outlet 2 [bang]">
	    <description>
			<p>In mode <bi>button</bi>: outputs bang on mouse-up.</p>
	    </description>
	</entry>
    </misc>
	
    <misc name = "Pattr">
	<entry name ="">
	    <description>
			<p>Object is exposed to the pattr-system when its scripting name is set and it is attached via a <m>pattr</m> or <m>autopattr</m>.</p>
			<p>Setvalueof propagates state-change to a connected <m>pattrstorage</m> when storing in a preset slot.</p>
			<p>Getvalueof receives state-change when affected in connected <m>pattrstorage</m> by recalling a preset slot.</p>  
			<bluebox>
				See corresponding tab in help-patcher.
			</bluebox>
	    </description>
	</entry>
    </misc>

    <misc name = "Keywords">
	<entry name ="">
	    <description>
		icst.button, graphics, prefix, labels, icons, offset, multiply
	    </description>
	</entry>
    </misc>
	
    <!--SEEALSO-->
	<seealsolist>

		<!-- <seealso name="icst.button"/> -->
		<seealso name="icst.intui"/>
		<seealso name="icst.floatui"/>
		<seealso name="icst.listui"/>
		
		<seealso name="icst.map"/>
		<seealso name="icst.random"/>
		<seealso name="icst.spline"/>
		<!-- <seealso name="splines"/> -->
		
		<seealso name="ambimonitor"/>
		<seealso name="ambicontrol"/>
		<seealso name="ambipoint"/>

		<seealso name="ambiencode~"/>
		<seealso name="ambidecode~"/>
		<seealso name="ambipanning~"/>
				
		<seealso name="mc.ambiencode~"/>
		<seealso name="mc.ambidecode~"/>
		<seealso name="mc.ambipanning~"/>
		
	</seealsolist>

</c74object>
