Example

====== Playback - Set fade-in time - modular ======

^ by: | Sebastian Beutel, April 2021 |
^ published: | here |
^ description: | set some playbacks' fade-in time, modular macros |
^ remarks: | these macros incorporate some newer syntax details: instruction blocks, custom variables, macros refered in other macros |

{{tag>playback fade-in time modular variable new syntax custom blocks}}

The basic functions are best understood when comparing with [[macros:example:setplaybackfadeintime|]]. When using ''Handles.SetSourceHandle()'' which always refers to the handle index on the current page you need to make sure that there is actually something suitable present in this location - hence, some steps need to be conditional. Additionally when you want to make such macros for n different times and m different playbacks you need to repeat many lines of code. 

Using newer syntax with code blocks and custom variables this is way easier: here we create only one macro to set all relevant playbacks' fade time to a variable value (using the block syntax to put a few instructions under one condition). Additionally a number of rather short macros simply sets the time variable to a certain value and then calls the 'apply' macro:

==== functions ====
  * [[:macros:function:Handles.SetSourceHandle]]
  * [[:macros:function:Playbacks.IsCueHandle]]
  * [[:macros:function:ActionScript.SetProperty]]
  * [[:macros:function:Playbacks.Editor.SelectLiveCue]]
  * [[:macros:function:Handles.ClearSelection]]
  * [[:macros:function:UserMacros.RecallMacroById]]

==== affected properties ====
  * [[:macros:property:Handles.SourceHandle]]
  * [[:macros:property:Playbacks.Editor.SelectedPlayback]]
  * [[:macros:property:Playbacks.Editor.Times.CueFadeInTime]]

==== control structures ====
  * [[macros:control_structures|step condition]]

==== specials ====
  * [[macros:syntax:codeblocks|code blocks]]
  * [[macros:syntax:customvariables|custom variables]]
  * [[macros:syntax:referingmacros|refering macros]]
 
===== Code =====
<code xml SetFadeInNew.xml>
<?xml version="1.0" encoding="utf-8"?>
<avolites.macros>
  <macro id="Wiki.Macros.SetFadeIn" name="Set Fade In (2)">
    <variables>
      <object id="Time" type="Avolites.Acw.Titan.AcwTimeSpan" assembly="Avolites.Acw.Titan" value="2" />
    </variables>
    <sequence>
      <step>
        {
          Handles.SetSourceHandle("PlaybackWindow", 0);
          if (Playbacks.IsCueHandle(Handles.SourceHandle) == true)
          {
            ActionScript.SetProperty("Playbacks.Editor.SelectedPlayback", Handles.SourceHandle);
            Playbacks.Editor.SelectLiveCue();
            ActionScript.SetProperty("Playbacks.Editor.Times.CueFadeInTime", Wiki.Macros.SetFadeIn.Time);
          }
          Handles.ClearSelection();
        }
      </step>
      <step>
        {
          Handles.SetSourceHandle("PlaybackWindow", 1);
          if (Playbacks.IsCueHandle(Handles.SourceHandle) == true)
          {
            ActionScript.SetProperty("Playbacks.Editor.SelectedPlayback", Handles.SourceHandle);
            Playbacks.Editor.SelectLiveCue();
            ActionScript.SetProperty("Playbacks.Editor.Times.CueFadeInTime", Wiki.Macros.SetFadeIn.Time);
          }
          Handles.ClearSelection();
        }
      </step>
      <step>
        {
          Handles.SetSourceHandle("PlaybackWindow", 2);
          if (Playbacks.IsCueHandle(Handles.SourceHandle) == true)
          {
            ActionScript.SetProperty("Playbacks.Editor.SelectedPlayback", Handles.SourceHandle);
            Playbacks.Editor.SelectLiveCue();
            ActionScript.SetProperty("Playbacks.Editor.Times.CueFadeInTime", Wiki.Macros.SetFadeIn.Time);
          }
          Handles.ClearSelection();
        }
      </step>
    </sequence>
  </macro>
  <macro id="Wiki.Macros.SetFadeIn0" name="Set Fade In 0">
    <sequence>
      <step>ActionScript.SetProperty("Wiki.Macros.SetFadeIn.Time", time:0)</step>
      <step>UserMacros.RecallMacroById("Wiki.Macros.SetFadeIn")</step>
    </sequence>
  </macro>
  <macro id="Wiki.Macros.SetFadeIn1" name="Set Fade In 1">
    <sequence>
      <step>ActionScript.SetProperty("Wiki.Macros.SetFadeIn.Time", time:1)</step>
      <step>UserMacros.RecallMacroById("Wiki.Macros.SetFadeIn")</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]]

The **Main macro** ''Wiki.Macros.SetFadeIn'' defines a custom variable ''Wiki.Macros.SetFadeIn.Time'', than selects a number of playbacks, and sets them to this time.
  * defining the variable is done in the block <variables>...</variables>
  * in order to define a variable you need to 
    * give it an **id** (this also defines the 'full name' of the variable: it's ''macro id''.''variable id''  This also means that if you change the id of the macro you need to change the variable name wherever it is called, e.g. where the variable is set, changed, or read.
    * the **type** defines the type of the variable, see also [[macros:types|]]
    * the **assembly** is some dotnet specific thing (maybe the variable's scope). I'd guess that ''Avolites.Acw.Titan'' should be a good starting point when testing other variables.
    * the **value** is the initial value the variable is set to when being defined.
  * after this, selecting a playback and setting its time is all done in one step thanks to the [[macros:syntax:codeblocks|code blocks]] syntax:
    * multiple instructions inside one step are bundled with ''{'' curly braces ''}''
    * instructions inside code blocks are separated with semicolons '';''
    * code blocks are also possible as conditional statements, in a very traditional way like 

<code>if (condition)
      {
        code being executed only if condition is true
      }</code>

  * for the instructions see [[macros:example:setplaybackfadeintime|]]

The **calling macros** ''Wiki.Macros.SetFadeIn0'', ''Wiki.Macros.SetFadeIn1'' etc. now are really short:
  * ''ActionScript.SetProperty("Wiki.Macros.SetFadeIn.Time", time:0)'' sets our cusom variable to a new value
  * ''UserMacros.RecallMacroById("Wiki.Macros.SetFadeIn")'' calls our 'main macro' which than sets all playbacks to the new time

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

  - [[:macros:deploying|make this macro available]]
  - if you want to add more playbacks to be affected simply add more steps in the 'main macro' ''Wiki.Macros.SetFadeIn''
  - if you want to add more fade-teime valus then you only need to add some more 'calling macros'


~~DISCUSSION~~