====== Introduction to macros ======

==== Overview ====

Macros are a way to automatically call specific functions or set specific values. Macros can be called from workspace buttons, or can be triggered from specific actions (like: from starting a cue in a cue list or – as of Titan v10 – starting a set list track).

Essentially there are two types of macros: macros recorded live on the console, and macros which are written in code. More about this is written in [[macros:recorded_vs._coded_macros]]. However, this wiki is dedicated to coded macros.

While macros are a very powerful tool to customize your console, writing macros is nothing for the faint of heart. Some basic windows knowledge - browsing and copying files across your system - as well as a good text editor are pre-requisites. It is recommended to try your macros on your private computer sporting [[https://www.avolites.com/software/downloads/titan-pc-suite|Avolites Titan Simulator]], and using it on your live console only when you have proven it works and doesn't harm system, show or nerves.

==== Some info and useful links ====

  * the [[http://forum.avolites.com/viewforum.php?f=20|Macro section of the Avolites forum]]
  * the [[https://www.facebook.com/groups/Avolites|Avolites facebook group]]
  * a [[http://www.avosupport.de/downloads/manuals/Avolites%20Titan%20Macros%20v0.9.pdf|short introduction (pdf)]]
  * the official [[http://api.avolites.com/|Avolites API documentation]]

And if you are looking for a comfortable text editor: there are many available, and even Windows notepad will do. However, please **don't use a big word processor (Word, OpenOffice etc.)** - they might have their problems with the xml markup which is used, will make your macro fail to run, and more. Personally I prefer an editor called [[https://notepad-plus-plus.org|Notepad++]] which I can strongly recommend.

==== Writing a macro ====

Writing a macro is easy as macros are text files in a certain format: fire up your text editor, write something like the text below (or simly download it), save this file with a name like //setpaging.xml//, copy it to //My Documents/Titan/Macros//, start (or restart) Titan Simulator -- and when clicking ''<Macro> [Show All]'' you should find a new macro named 'Set PbPaging to NeverHold' like this (that's a real life example - I was looking for a way to make one of my favourite user settings more accessible):

{{:setbpaging.png?200|}}

<file xml setpaging.xml>
<?xml version="1.0" encoding="utf-8"?>
<avolites.macros xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="Avolites.Menus.xsd">
  <!-- Macro to set PlaybackPaging to never. Sebastian Beutel with help by Gregory Haynes 05/09/2016 -->
  <macro id="Avolites.Macros.PagingNeverHold" name="Set PbPaging to NeverHold">
    <description>Sets PlaybackPaging to NeverHold.</description>
    <sequence>
      <step>ActionScript.SetProperty.Enum("Handles.HandlesHeldover", "NeverHold")</step>
    </sequence>
  </macro>
</avolites.macros>
</file>

==== What's next ====

Gotten curious? Welcome to the club - now you know what all this is about. You may go on reading here:
  * a condensed - but helpful - overview about the syntax and formats is available at [[macros:formats_and_syntax]]
  * where exactly are the macro files stored: [[macros:macrolocation|Macro folders]]
  * how to [[macros:deploying|make macros available in Titan]]
  * there is also a [[macros:recorded_vs._coded_macros|section on the differences between recorded and coded macros, complete with a detailled example]]
  * and finally the core of this wiki: a growing [[macros:examples|collection of example macros]] and a [[macros:function_list|documentation of the functions]]

==== P.S. My first Macro Howto ====

This is the prequel of the wiki: back in 2016 I wrote my first documentation for the new macro engine. If you want you may have a look at it: {{ :macros:avolites_titan_macros_v0.9.pdf |}}