Example

====== Cuelist - Set Option FireFirstCue ======

^ by: | Sebastian Beutel, June 2021 |
^ published: | here |
^ description: | Set some Cuelists' option to Fire First Cue on/off |
^ remarks: | with kind support by Gregory Haynes |

{{tag>cuelist set option range fire first}}

This example shows how to select playbacks, how to set their options, and how to reference macros in other macros.

==== functions ====
  * [[:macros:function:Handles.FilterHandleOptions]]
  * [[:macros:function:ActionScript.SetProperty.Boolean]]
  * [[:macros:function:Handles.ClearSelection]]
  * [[:macros:function:Handles.ClearHandleOptionsFilter]]
  * [[:macros:function:Handles.SetSourceHandleFromHandle]]
  * [[:macros:function:UserMacros.RecallMacroById]]
  * [[:macros:function:Handles.SetSourceHandleRange]]

==== affected properties ====
  * [[:macros:property:HandleOptions.CueLists.FireFirstCue]]

==== control structures ====
  * [[macros:step_pause|]]

Tests showed that these macros require a step_pause to function properly.

===== Code =====
<code xml SetCuelistOptionFFQ.xml>
<?xml version="1.0" encoding="utf-8"?>
<avolites.macros>

<!-- Macros to set a cuelists options to fire first cue -->
<!-- Sebastian Beutel, June 2021 -->
<!-- xxx macros are used within the macros further down -->

  <macro id="Wiki.Macros.Cuelists.SetOption.FFQ.On" name="xxx Set PB option to FFQ On">
    <sequence>
      <step pause="0.05">Handles.FilterHandleOptions()</step>
      <step pause="0.05">ActionScript.SetProperty.Boolean("HandleOptions.CueLists.FireFirstCue",true)</step>
      <step pause="0.05">Handles.ClearSelection()</step> 
      <step pause="0.05">Handles.ClearHandleOptionsFilter()</step>
    </sequence>
  </macro>	
		  
  <macro id="Wiki.Macros.Cuelists.SetOption.FFQ.Off" name="xxx Set PB option to FFQ Off">
    <sequence>
      <step pause="0.05">Handles.FilterHandleOptions()</step>
      <step pause="0.05">ActionScript.SetProperty.Boolean("HandleOptions.CueLists.FireFirstCue",false)</step>
      <step pause="0.05">Handles.ClearSelection()</step> 
      <step pause="0.05">Handles.ClearHandleOptionsFilter()</step>
    </sequence>
  </macro>
  
<!-- these macros reference the xxx macros above -->
  
  <macro id="Wiki.Macros.Cuelists.SetOption.FFQ1.On" name="Set CL 101 to FFQ On">		
    <sequence>  
      <step pause="0.05">Handles.SetSourceHandleFromHandle("playbackHandleUN=101")</step>
      <step pause="0.05">UserMacros.RecallMacroById("Wiki.Macros.Cuelists.SetOption.FFQ.On")</step>
    </sequence>
  </macro>
        
  <macro id="Wiki.Macros.Cuelists.SetOption.FFQ1.Off" name="Set CL 101 to FFQ Off">		
    <sequence>  
      <step pause="0.05">Handles.SetSourceHandleFromHandle("playbackHandleUN=101")</step>
      <step pause="0.05">UserMacros.RecallMacroById("Wiki.Macros.Cuelists.SetOption.FFQ.Off")</step>
    </sequence>
  </macro>
      
<!-- setting the option for a range works only if the first in the range needs to be changed -->
<!-- that's why here it is set the other way before the range is set as intended -->     
      
  <macro id="Wiki.Macros.Cuelists.SetOption.FFQ1thro4.On" name="Set PB 1 thro 4 to FFQ On">		
    <sequence>
      <step pause="0.05">Handles.SetSourceHandle("Playbacks", 0)</step>
      <step pause="0.05">UserMacros.RecallMacroById("Wiki.Macros.Cuelists.SetOption.FFQ.Off")</step>
      <step pause="0.05">Handles.SetSourceHandleRange("Playbacks", {0, 1, 2, 3})</step>
      <step pause="0.05">UserMacros.RecallMacroById("Wiki.Macros.Cuelists.SetOption.FFQ.On")</step>
   </sequence>
  </macro> 
       
  <macro id="Wiki.Macros.Cuelists.SetOption.FFQ1thro4.Off" name="Set PB 1 thro 4 to FFQ Off">		
    <sequence>
      <step pause="0.05">Handles.SetSourceHandle("Playbacks", 0)</step>
      <step pause="0.05">UserMacros.RecallMacroById("Wiki.Macros.Cuelists.SetOption.FFQ.On")</step>
      <step pause="0.05">Handles.SetSourceHandleRange("Playbacks", {0, 1, 2, 3})</step>
      <step pause="0.05">UserMacros.RecallMacroById("Wiki.Macros.Cuelists.SetOption.FFQ.Off")</step>
   </sequence>
  </macro>
   
</avolites.macros>
</code>


===== Explanation =====

This explains the functional steps within the sequence. For all the other XML details please refer to [[:macros:formats_and_syntax#xml_format|Formats and syntax]]

Note that this is an example for reusing code by referencing other macros. Of course this works only if the correct MacroIds are used: the first two macros do the real work - the other macros just select the very playback or cuelist and then call the work macros.

**Please note that these macros require a certain step_pause in order to function properly.**

The 'base' macros:
  * ''Handles.FilterHandleOptions()'' sets the filter so that options can be set
  * ''ActionScript.SetProperty.Boolean("HandleOptions.CueLists.FireFirstCue",true)'' actually sets the option as required to true or false
  * ''Handles.ClearSelection()'' clears the selection
  * ''Handles.ClearHandleOptionsFilter()'' clears the filter

The select macros:
  * ''Handles.SetSourceHandleFromHandle("playbackHandleUN=101")'' selects a particular playback by its user number
  * ''UserMacros.RecallMacroById("Wiki.Macros.Cuelists.SetOption.FFQ.On")'' then calls one of the 'base' macros to do the work

For ranges of playbacks something special needs to be taken into account: tests revealed that setting an option for a range works only if the first item needs to be toggled, i.e. wouldn't work if the first item is already set correctly and only some other elements need to be set. Thus here the first element is deliberately set the other way, and then the range is set as intended:

  * ''Handles.SetSourceHandle("Playbacks", 0)'' selects the first handle of the range
  * ''UserMacros.RecallMacroById("Wiki.Macros.Cuelists.SetOption.FFQ.Off")'' calls the base macro to set the option in the wrong way
  * ''Handles.SetSourceHandleRange("Playbacks", {0, 1, 2, 3})'' now selects the whole range
  * ''UserMacros.RecallMacroById("Wiki.Macros.Cuelists.SetOption.FFQ.On")'' finally calls the base macro to set the option of the range correctly

===== How to use it =====

  - [[:macros:deploying|make this macro available]]
  - fire the 'select' macros as needed. The 'base' macros with xxx in their name are only useful with a cuelist selected.


~~DISCUSSION~~