Example

====== Quick-Create groups ======

^ by: | Sebastian Beutel |
^ published: | here, June 2021 |
^ description: | quickly create groups with necessary parameter in one go |
^ remarks: | with kind support by Gregory Haynes |

{{tag>quick create quickcreate groups}}

Usually when storing new groups you need to do several steps: [[macros:function:group.storegroup|store the group]] which creates it in the show library, [[macros:example:movehandle|move it]] to the location where you want it, and [[macros:function:handles.setlegend|set its legend]]. Using quickcreate you can do all in one go: create the group with the legend you want in the location you want.
Also pay attention to the function [[:macros:function:Handles.CreateHandleReference]] which creates a reference to a not-yet existing handle. on the contrary something like ''Group.QuickCreateGroup("Location=Groups,1,10", userNumber:10, "Group 10", 0)'' would throw an error and would not work as currently no handle exists with this location.

==== functions ====
  * [[:macros:function:Group.RecallGroup]]
  * [[:macros:function:UserMacros.RecallMacroById]]
  * [[:macros:function:Group.QuickCreateGroup]]
  * [[:macros:function:Handles.CreateHandleReference]]
  * [[:macros:function:Programmer.Editor.Clear]]

==== affected properties ====
  * [[:macros:property:Attribute.Mask.Clear.Value]]
  * [[:macros:property:Programmer.Editor.Fixtures.Clear.Presets]]
  * [[:macros:property;Expert.ClearMenu.FadeTime]]

 
===== Code =====
<code xml QuickCreateGroups.xml>
<?xml version="1.0" encoding="utf-8"?>
<avolites.macros>
  <macro id="Wiki.Macros.QuickCreateGroups" name="QuickCreate Groups">
    <sequence>
    
      <!-- Select group 1, pattern even. Save with Usernumber 10 -->
      <step>Group.RecallGroup(userNumber: 1)</step>
      <step pause="0.001">UserMacros.RecallMacroById("Avolites.Macros.PatternSelection.Odd")</step>
      <step>Group.QuickCreateGroup(Handles.CreateHandleReference("Groups", 1, 10), userNumber:10, "Group 10", 0)</step>
      <step pause="0.01">Programmer.Editor.Clear(Attribute.Mask.Clear.Value, Programmer.Editor.Fixtures.Clear.Presets, false, Expert.ClearMenu.FadeTime)</step>
      
      <!-- Select group 1, pattern even. Save with Usernumber 11 -->
      <step>Group.RecallGroup(userNumber: 1)</step>
      <step pause="0.001">UserMacros.RecallMacroById("Avolites.Macros.PatternSelection.Even")</step>
      <step>Group.QuickCreateGroup(Handles.CreateHandleReference("Groups", 1, 11), userNumber:11, "Group 11", 0)</step>
      <step pause="0.001">Programmer.Editor.Clear(Attribute.Mask.Clear.Value, Programmer.Editor.Fixtures.Clear.Presets, false, Expert.ClearMenu.FadeTime)</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]]

  * ''Group.RecallGroup(userNumber: 1)'' selects group 1
  * ''UserMacros.RecallMacroById("Avolites.Macros.PatternSelection.Odd")'' selects the odd fixtures only
  * ''Group.QuickCreateGroup(Handles.CreateHandleReference("Groups", 1, 10), userNumber:10, "Group 10", 0)'' does the heavy lifting here: it creates the new group
    * on button 11 on page 2 of the groups window, as denoted by ''Handles.CreateHandleReference("Groups", 1, 10)''\\ (we need to use this to create a reference to a not-yet existing handle)
    * with userNumber 10
    * with the legend "Group 10"
    * the function also allows to set the icon if you know its Titan Id
  * ''Programmer.Editor.Clear'' simply clears the selection (a quicker way would be ''Programmer.Editor.ClearAll(true, true)'' while  ''Handles.ClearSelection()'' would not work as selecting fixtures to create a group is a programmer operation)

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

  - [[:macros:deploying|make this macro available]]
  - this is probably more suitable as part of setup macros to quickly create the groups you like in a new show

~~DISCUSSION~~