<?xml version='1.0' encoding='UTF-8'?> 
<?xml-stylesheet href="./_c74_ref.xsl" type="text/xsl"?> 
<!-- Data marked TEXT_HERE, INLET_TYPE, OUTLET_TYPE, ARG_NAME and ARG_TYPE need to be filled in --> 
<c74object name='live.path' category='M4L' module='m4l'>
  <digest> Navigate to objects in the Live application </digest>
  <description> 
    <o>live.path</o>
    is used to navigate to Live objects on which the 
    <o>live.object</o>
     , 
    <o>live.observer</o>
     and 
    <o>live.remote~</o>
     objects operate. The navigation is purely path-based and is independent of
    the objects currently present in Live (navigating to a nonexistent path will
    result in the message 
    <m>id 0</m>
     being sent out the left and middle outputs rather than an error message). 
     <br/>
     <br/>
 	<i>Note: The Live API runs in the main thread in Live, and that all messages to and from the API are automatically deferred.</i>
  </description>
  <!--METADATA-->
  <metadatalist>
    <metadata name='author'> Cycling '74, Ableton </metadata>
    <metadata name='tag'> Live </metadata>
  </metadatalist>
  <inletlist/>
  <outletlist/>
  <!--INLETS-->
  <apiinletlist>
    <inlet name='Single inlet' id='0'>
      <description>
      	 Gets all command messages described below. </description>
    </inlet>
  </apiinletlist>
  <!--OUTLETS-->
  <apioutletlist>
    <outlet name='Left outlet' id='0'>
      <description>      	
        Sends the message 
        <m>
           id 
          <i>nn</i>
        </m>
         in response to a 
        <m>goto</m>
         , 
        <m>bang</m>
         or 
        <m>getid</m>
         message 
        <b>only</b>
         . Use this outlet if you want to keep working with a particular object
        determined at goto or bang time, even if its position in Live changes. 
        <br/>
        <br/>
         For example, consider a fresh Live set with two tracks, "1 Audio" as
        the leftmost track and "2 MIDI" to the right of it. If you navigate to
        the "2 MIDI" track ( 
        <m>goto live_set tracks 1</m>
         ) and you create a new Audio track between "1 Audio" and "2 MIDI", your
        original MIDI track now would be at 
        <m>live_sets tracks 2</m>
         . But since the id number of the MIDI track would stay the same and no
        new id is sent out to the left outlet, the live.xxx objects connected to
        this outlet keep working with the MIDI track, until you sent another
        goto. 
      </description>
    </outlet>
    <outlet name='Middle outlet' id='1'>
      <description>      	
        Sends 
        <m>
           id 
          <i>nn</i>
        </m>
         whenever the id of the object at the current path changes (because the
        current path is changed or because the object at this place in Live has
        changed, for example. Use this outlet if you want to keep working with
        the same path, whatever object there might be. This outlet is very
        useful for things like 
        <m>live_set view detail_clip</m>
         . 
        <br/>
        <br/>
         Consider the example above. If the live.xxx objects would be connected
        to the middle outlet of 
        <o>live.path</o>
         , then they would work with the newly created audio track. 
        <br/>
        <br/>
         The spontaneous sending of object ids out of the middle outlet, i.e.
        without an inlet message causing it, but caused by a change in Live, is
        called a notification. 
        <br/>
        <b>Note:</b>
         It is not possible to modify the Live set from such a notification. 
      </description>
    </outlet>
    <outlet name='Right outlet' id='2'>
      <description>      	
        Sends responses to 
        <m>getpath</m>
         , 
        <m>getchildren</m>
         , 
        <m>getcount</m>
         . 
      </description>
    </outlet>
  </apioutletlist>
  <!--ARGUMENTS-->
  <objarglist>
    <objarg name='initial path' optional='1' type='symbol'>
      <description>      	
        Specify an initial path as argument to 
        <o>live.path</o>
         , without any quotes. 
      </description>
    </objarg>
  </objarglist>
  <!--MESSAGES-->
  <methodlist>
    <method name='goto'>
      <arglist>
        <arg name='path' optional='0' type='symbol'/>
      </arglist>
      <digest>
         Arguments: 
        <br/>
        <m>
          <i>path</i>
        </m>
         is an absolute path (starts with live_app, live_set or control_surfaces
        
        <i>N</i>
         ) 
      </digest>
      <description>      	
        Arguments: 
        <br/>
        <m>
          <i>path</i>
        </m>
         is an absolute path (starts with live_app, live_set or control_surfaces
        
        <i>N</i>
         ) or a relative path, or 
        <m>up</m>
        <br/>
        <br/>
         Operation: 
        <br/>
         Navigates to given path and sends id of the object at that path out the
        left and middle outlets. If there is no object at the path, 
        <m>id 0</m>
         is sent. 
        <br/>
        <br/>
         Remarks: 
        <br/>
         You cannot go to a list property, only to one of its members. 
        <br/>
         invalid: 
        <m>goto live_set scenes</m>
        <br/>
         correct: 
        <m>goto live_set scenes 3</m>
        <br/>
        <br/>
        <table>
          <tr>
            <th>Outlet</th>
            <th>Output</th>
            <th>Example</th>
          </tr>
          <tr>
            <td>left</td>
            <td>
              <m>
                 id 
                <i>nn</i>
              </m>
            </td>
            <td>
              <m>id 5</m>
            </td>
          </tr>
          <tr>
            <td>middle</td>
            <td>
              <m>
                 id 
                <i>nn</i>
              </m>
            </td>
            <td>
              <m>id 5</m>
            </td>
          </tr>
        </table>
     
    	</description>
    </method>
    <method name='path'>
      <arglist>
        <arg name='absolute-path' optional='0' type='symbol'/>
      </arglist>
      <digest>
         Same as 
        <m>goto</m>
         but limited to absolute paths that start with a root object name like 
        <m>live_app</m>
         , 
        <m>live_set</m>
         , 
        <m>this_device</m>
         or 
        <m>
           control_surfaces 
          <i>N</i>
        </m>
         . 
      </digest>
      <description>      	
        Same as 
        <m>goto</m>
         but limited to absolute paths that start with a root object name like 
        <m>live_app</m>
         , 
        <m>live_set</m>
         , 
        <m>this_device</m>
         or 
        <m>
           control_surfaces 
          <i>N</i>
        </m>
         . 
     
    	</description>
    </method>
    <method name='bang, getid'>
      <digest>
         Operation: 
        <br/>
         Sends the id of the object at the current path to left and middle
        outlets. 
      </digest>
      <description>      	
        Operation: 
        <br/>
         Sends the id of the object at the current path to left and middle
        outlets. Sends 
        <m>id 0</m>
         if there is no object at the current path. 
        <br/>
        <br/>
        <table>
          <tr>
            <th>Outlet</th>
            <th>Output</th>
            <th>Example</th>
          </tr>
          <tr>
            <td>left</td>
            <td>
              <m>
                 id 
                <i>nn</i>
              </m>
            </td>
            <td>
              <m>id 5</m>
            </td>
          </tr>
          <tr>
            <td>middle</td>
            <td>
              <m>
                 id 
                <i>nn</i>
              </m>
            </td>
            <td>
              <m>id 5</m>
            </td>
          </tr>
        </table>
     
    	</description>
    </method>
    <method name='getpath'>
      <digest>
         Operation: 
        <br/>
         Sends a path message with the current path to the right outlet. 
      </digest>
      <description>      	
        Operation: 
        <br/>
         Sends a path message with the current path to the right outlet. 
        <br/>
        <br/>
        <table>
          <tr>
            <th>Outlet</th>
            <th>Output</th>
            <th>Example</th>
          </tr>
          <tr>
            <td>right</td>
            <td>
              <m>
                 path 
                <i>path</i>
              </m>
            </td>
            <td>
              <m>path live_set scenes 1</m>
            </td>
          </tr>
        </table>
     
    	</description>
    </method>
    <method name='getchildren'>
      <digest>
         Operation: 
        <br/>
         Sends a list of children of the object at the current path, if any, to
        the right outlet. 
      </digest>
      <description>      	
        Operation: 
        <br/>
         Sends a list of children of the object at the current path, if any, to
        the right outlet. 
        <br/>
        <br/>
         Remarks: 
        <br/>
         The child names are the same names as used in the goto message. 
        <br/>
        <br/>
        <table>
          <tr>
            <th>Outlet</th>
            <th>Output</th>
            <th>Example</th>
          </tr>
          <tr>
            <td>right</td>
            <td>
              <m>
                 children 
                <i>list-of-child-names</i>
              </m>
            </td>
            <td>
              <m>children canonical_parent clip_slots</m>
            </td>
          </tr>
        </table>
     
    	</description>
    </method>
    <method name='getcount'>
      <arglist>
        <arg name='child-name' optional='0' type='symbol'/>
      </arglist>
      <digest>
         Arguments: 
        <br/>
        <m>child-name</m>
         is the name of a child of the object at the current path. 
      </digest>
      <description>      	
        Arguments: 
        <br/>
        <m>child-name</m>
         is the name of a child of the object at the current path. 
        <br/>
        <br/>
         Operation: 
        <br/>
         Sends a count message to the right outlet, containing the name of the
        child and its number of entries. 
        <br/>
        <br/>
         Remarks: 
        <br/>
         The given child must be a list. 
        <br/>
        <br/>
        <table>
          <tr>
            <th>Outlet</th>
            <th>Output</th>
            <th>Example</th>
          </tr>
          <tr>
            <td>right</td>
            <td>
              <m>
                 count 
                <i>child-name</i>
                <i>count</i>
              </m>
            </td>
            <td>
              <m>count clip_slots 2</m>
            </td>
          </tr>
        </table>
     
    	</description>
    </method>
  </methodlist>
  <attributelist/>
  <!--ATTRIBUTES-->
  <!--EXAMPLE-->
  <examplelist>
    <example img='live.path.png' />
  </examplelist>
  <!--SEEALSO-->
  <seealsolist>
    <seealso name='live_api_overview' module='core' type='vignette' display='Live API Overview'/>
    <seealso name='live_object_model' module='core' type='vignette' display='Live Object Model'/>
    <seealso name='live.object'/>
    <seealso name='live.observer'/>
    <seealso name='live.remote~'/>
    <seealso name='live_api' module='core' type='vignette' display='Using the Live API'/>
    <seealso name='jsliveapi' module='js' type='vignette' display='The LiveAPI JavaScript Object (jsliveapi)'/>
  </seealsolist>
</c74object>