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

<c74object name="ossia.parameter" module="Ossia" category="Ossia">

	<digest>
		Declare a parameter and its attributes
	</digest>

	<description>
				ossia.parameter declares a parameter in the ossia tree - it is somehow similar to the pattr object, while enabling a number of additional features offered by libossia.
	</description>
	<discussion>
    The parameter is an access point for controlling the processing of the patch. 
    The parameter enables inter-application communication. The parameter is provided with a unique global OSC address. Parameters can also be declared on the network in order for other applications such as score to inspect and control models.
  </discussion>
	
	<!--METADATA-->
	<metadatalist>
		<metadata name="author">Ossia</metadata>
		<metadata name="tag">Ossia</metadata>
		<metadata name="tag">Network</metadata>
	</metadatalist>

	
	<!--INLETS-->
	<inletlist>
		<inlet id="0" name="Value input" type="any">
			<digest>Value to set the parameter to.</digest>
			<description>Value to set the parameter to.</description>
		</inlet>
	</inletlist>


	<!--OUTLETS-->
	<outletlist>
		<outlet id="0" name="Value output" type="any">
			<digest>Value the parameter was set to.</digest>
			<description>Value the parameter was set to.</description>
		</outlet>
		<outlet id="1" name="Dump outlet" type="any">
			<digest>Various information messages</digest>
			<description>Messages and information in reply to various messages</description>
		</outlet>
	</outletlist>
	
	<!--ARGUMENTS-->
	<objarglist>
		<objarg name="node name" optional="0" type="symbol">
			<digest>
				Name in ossia namespace
			</digest>
			<description>
				<o>ossia.parameter</o> requires an argument defining a node name in the ossia namespace.
				 This is mandatory, and each <o>ossia.parameter</o> within an ossia model must have a unique name - if several  nodes are named similarly, instances (such as name.1, name.2, etc...) will be created.
			</description>
		</objarg>
	</objarglist>

	<!--METHODS-->	
	<methodlist>
		 
		<method name="address">
			<arglist>
				<arg name="node address" type="symbol" optional="0"/>
			</arglist>
			<digest>
				Set node name
			</digest>
			<description>
				The message <m>address</m> followed by a symbol sets the name of the node. This temporary replaces the name provided initially as an argument to the object and allows to address nodes dynamically. Without any argument, <m>address</m> message will set the node address back to as defined as argument to the object.
			</description>
		</method> 
		
		
		<method name="anything">
			<arglist>
				<arg name="input" optional="0" type="list"/>
			</arglist>
			<digest> Feed values to ossia.parameter or access attributes by their names
			</digest>
			<description>
				If the first symbol equals the name of a setable attribute, the value for that attribute can be updated. Else the incoming message is interpreted as a new value for <o>ossia.parameter</o>. Depending on the <m>type</m> it might be converted to one or more floats (<m>type float</m> or <m>tuple</m>) or an int (<m>type int</m>).
			</description> 
		</method>

		<method name="bang">
			<arglist/>
			<digest>
				Output current value
			</digest>
			<description>
				A bang at leftmost inlet outputs ossia.parameter's current value
			</description>
		</method>

		<method name="dump">
			<arglist/>
			<digest>
				Dump all attributes settings to rightmost outlet
			</digest>
			<description>
				The message <m>dump</m> outputs all attribute settings to rightmost outlet
			</description>
		</method>

		<method name="float">
			<digest>
				Set and output value
			</digest>
			<description>
				A float at leftmost inlet sets and outputs the value. Depending on the <at>type</at> attribute, the value might get converted into a int value if the <at>type</at> attribute is <m>int</m> or into a symbol if the <at>type</at> attribute is <m>symbol</m>
			</description>
		</method>
		
		<method name="int">
			<digest>
				Set and output value
			</digest>
			<description>
				An int at leftmost inlet sets and outputs the value. Depending on the <at>type</at> attribute, the value might get converted into a float value if the <at>type</at> attribute is <m>float</m> or <m>tuple</m> or into a symbol if the <at>type</at> attribute is <m>symbol</m>
			</description>
		</method>
		
		<method name="list">
			<digest>
				Set and output value
			</digest>
			<description>
				A list at the leftmost inlet sets and outputs the value. If the <at>type</at> is <m>float</m>, <m>int</m> or <m>symbol</m>, only the first list member will be used to set the value, and the type of this list member might be converted to fit the specified <at>type</at> of the parameter<br/>

			</description>
		</method>

		<method name="reset">
			<arglist/>
			<digest>
				Reset to default value
			</digest>
			<description>
				The message <m>reset</m> sent to the leftmost inlet reset the current value to the value defined by the <at>default</at> attribute
			</description>
		</method>
		
		<method name="select">
			<arglist>
				<arg name="node address" type="symbol" optional="0"/>
			</arglist>
			<digest>
				Select node(s) 
			</digest>
			<description>
				The message <m>select</m> followed by a symbol specifying a node address or address pattern, select one or many addresses within the addresses matched by the pattern set as argument to the object. This can be useful for example to send value only to one or several addresses of the one matched by the pattern defined as argument to the object box. 
				<br/>
				<br/>Note that contrary to the <m>address</m> message which destroys and recreates the namespace as needed to set the remote address, <m>select</m> only scan through the addresses already matched by the remote and is thus much faster.
			</description>
		</method>

		<method name="send">
			<arglist>
				<arg name="node address" optional="0" type="symbol" />
				<arg name="value" optional="0" type="any" />
			</arglist>
			<digest>
				Send value to a particular parameter instance
			</digest>
			<description>
				When using addresses pattern in <o>ossia.parameter</o> such as 'my_spat/source.{1..3}/gain', the <m>send</m> message followed by a node address and value (ie <m>send my_spat/source.2/gain 0.5</m>) send the value of that particular parameter instance
			</description>
		</method>


	</methodlist>


	<!--ATTRIBUTES-->
	<attributelist>
		
		<attribute name="clip" get="1" set="1" type="symbol" size="1">
			<digest>
				Set how values exceeding range will be clipped
			</digest>
			<description>
				The <at>clip</at> attribute defines how values exceeding the range will be managed. Available clipmodes are:
				<ul><li><m>free</m>: when set to <m>free</m> (default), exceeding values will be left untouched</li><li><m>low</m>: when set to <m>low</m>, values exceeding the lower bound will be clipped. Values exceeding the upper bound will be left untouched</li><li><m>high</m>: when set to <m>high</m>, values exceeding the upper bound will be clipped. Values exceeding the lower bound will be left untouched</li><li><m>both</m>: when set to <m>both</m>, values exceeding lower or upper bounds will be clipped</li><li><m>wrap</m>: when set to <m>wrap</m>, values exceeding lower or upper bound will wrapped around the opposite bound</li><li><m>fold</m>: when set to <m>fold</m>, values exceeding lower or upper bound will folded back within the defined range</li></ul>
			</description>
			<attributelist>
				<attribute name="basic" get="1" set="1" type="int" size="1" value="0" />
				<attribute name="category" get="1" set="1" type="symbol" size="1" value="ossia" />
				<attribute name="label" get="1" set="1" type="symbol" size="1" value="Clip Mode" />
			</attributelist>
		</attribute>
		<attribute name="critical" get="1" set="1" type="int" size="1">
			<digest>
				Mark parameter as critical
			</digest>
			<description>
				The <at>critical</at> attribute allows to use a sending method that ensure data is received.
				Not all protocol support this feature.
				With OSCQuery, for example, a critical parameter value will be send through websocket (so with TCP/IP delivery check) instead of OSC (which transit over UDP that doesn't have such a verification mechanism).
			</description>
		</attribute>  
		<attribute name="default" get="1" set="1" type="int" size="1">
			<digest>
				Default value
			</digest>
			<description>
				The <at>default</at> attribute sets the value to output at the leftmost outlet on model initialization. The default value can be overridden by the default model preset
			</description>
		</attribute>	

		<attribute name="description" get="1" set="1" type="atom" size="1">
			<digest>
				Descrption of this node
			</digest>
			<description>
				The <at>description</at> attribute allows to agive a textual description for this node. This helps documenting the parameter.
			</description>
		</attribute>
		
		<attribute name="enable" get="1" set="1" type="int" size="1">
			<digest>
				Enable node
			</digest>
			<description>
				The <at>enable</at> attribute allows to enable (default: 1) or disable a node
			</description>
		</attribute>  

		<attribute name="invisible" get="1" set="1" type="symbol" size="1">
			<digest>
				Hide parameter node in remote client
			</digest>
			<description>
				The <at>invisible</at> attribute allows a remote client to hide this parameter - this can be useful e.g. for "internal" or setup parameters that we don't want to give access to.
			</description>
		</attribute>
		
		<attribute name="max" get="1" set="1" type="list" size="2">
			<digest>
				Value range maximum
			</digest>
			<description>
				The <at>max</at> attribute defines the maximum value of expected range of possible values. Depending on the <at>clip</at> attribute, this might be a recommended or mandatory range. In the case of Vecnf's and tuples, this can be a list of floats in order to set different maximum values for each Vec/tuple member.
			</description>
		</attribute>	

		<attribute name="min" get="1" set="1" type="list" size="2">
			<digest>
				Value range minimum
			</digest>
			<description>
				The <at>min</at> attribute defines the minimum value of expected range of possible values. Depending on the <at>clip</at> attribute, this might be a recommended or mandatory range. In the case of Vecnf's and tuples, this can be a list of floats in order to set different minimum values for each Vec/tuple member.
			</description>
		</attribute>	

		<attribute name="mode" get="1" set="1" type="symbol" size="1">
			<digest>
			Define access mode of parameter : GET, SET, or both (BI)
			</digest>
			<description>
			Defines the way the value of ossia.parameter will be accessible : when set at GET, the value can only be retrieved, when at SET, it can only be set, and when at BI, it can be both set and retrieved.
			However, when `@mode` is set as SET, it is possible to retrieve the last value it has received, without any guarantee this will reflect the system's current/actual state.
			</description>
		</attribute>
		
		<attribute name="mute" get="1" set="1" type="boolean" size="1">
			<digest>
				Mute parameter (off by default)
			</digest>
			<description>
				The <at>mute</at> attribute allows to prevent the parameter from outputting local (i.e. fed from the input) values - Remotely sent values will still come out
			</description>
		</attribute>

		<attribute name="priority" get="1" set="1" type="int" size="1">
			<digest>
				Set priority
			</digest>
			<description>
				The <at>priority</at> attribute allows one to order how several values of a same hierarchical level can be recalled. The higher the number, the higher the priority. Higher prioritized parameters are recalled first.
			</description>
		</attribute>

		<attribute name="range" get="1" set="1" type="list" size="2">
			<digest>
				Value range
			</digest>
			<description>
				The <at>range</at> attribute defines the expected range of possible values. Depending on the <at>clip</at> attribute, this might be a recommended or mandatory range.
			</description>
		</attribute>		

		<attribute name="rate" get="1" set="1" type="integer" size="1">
			<digest>
				An optional value that says how often a value should be updated.			
			</digest>
			<description>
				The <at>rate</at> attribute is an optional value that says how often a value should be updated. Currently does nothing in Max but remote application can use it to limit the data rate of that parameter.
			</description>
		</attribute>


		<attribute name="repetitions" get="1" set="1" type="boolean" size="1">
			<digest>
				Allow value repetitions (on by default)
			</digest>
			<description>
				The <at>repetitions</at> attribute defines whether identical values will be repeated (on by default)
			</description>
			<attributelist>
				<attribute name="basic" get="1" set="1" type="int" size="1" value="0" />
				<attribute name="category" get="1" set="1" type="symbol" size="1" value="ossia" />
				<attribute name="label" get="1" set="1" type="symbol" size="1" value="Allow Repetitions" />
			</attributelist>
		</attribute>
		
		<attribute name="tags" get="1" set="1" type="atom" size="1">
			<digest>
				Tags associated with this node
			</digest>
			<description>
				The <at>tags</at> attribute allows to associate a variable number of tags for this node. This helps documenting the parameter.
			</description>
		</attribute>
		<attribute name="trim_address" get="1" set="1" type="boolean" size="1">
			<digest>
				Output absolute or relative address path
			</digest>
			<description>
				The <a>trim_address</a> attribute sets whether the address is output as a relative or absolute path
			</description>
		</attribute>
		<attribute name="type" get="1" set="1" type="symbol" size="1">
			<digest>
				Value type
			</digest>
			<description>
				The <at>type</at> attribute defines the type of the value. Possible types are:
				<li><m>float</m> (default)</li><li><m>int</m></li><li><m>bool</m> </li> <li><m>tuple</m> </li> <li><m>symbol</m></li><li><m>impulse</m></li>
			</description>
		</attribute>

		<attribute name="unit" get="1" set="1" type="symbol" size="1">
			<digest>
				Unit used by the parameter
			</digest>
			<description>
				The <at>unit</at> attribute defines the unit used by this parameter. Values will get output according to this unit.
			</description>
		</attribute>
	</attributelist>



	<!--SEEALSO-->
	<seealsolist>
		<seealso name="ossia.model"/>
		<seealso name="ossia.view"/>
		<seealso name="ossia.remote"/>
	</seealsolist>

	
</c74object>
