Example

====== Set a Handle's Halo ======

^ by: | Gregory Haynes, February 2018 |
^ published: | email |
^ description: | example of how to set an item's halo |

{{tag>halo}}

==== functions ====
  * [[:macros:function:Handles.SetSourceHandleFromHandle]]
  * [[:macros:function:Handles.SetPendingHaloToSystemColour]]
  * [[:macros:function:Handles.ClearSelection]]


===== Code =====
<code xml chase22_green.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 name="Chase 22 Green Halo" id="UserMacro.Chase22.Halo.Green">
    <description>Sets chaser 22 to green halo.</description>
    <sequence>
      <step>Handles.SetSourceHandleFromHandle("chaseHandleUN=22")</step>
      <step>Handles.SetPendingHaloToSystemColour("Light Green")</step>
      <step>Handles.ClearSelection()</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]]

''Handles.SetSourceHandleFromHandle("chaseHandleUN=22")'' selects the chase with usernumber 22 as source handle for the following steps.\\ 
''Handles.SetPendingHaloToSystemColour("Light Green")'' sets the selected handle's halo to light green.\\
''Handles.ClearSelection()'' clears the selection.

Until Titan 11.1 it is not possible to set the halo to a random RGB colour, as the halo property is of type [[macros:type:object:AcwColour]] and there is no automatic conversion. Hence, the only option is to use the available system colours which are Red, Orange, Brown, Yellow, Green, Light Green, Blue, Cyan, Violet, Red Violet.

From Titan 11.2 on it is expected to be possible to set an arbitrary RGB colour.

> Add a converter for AcwColour which allows macros and WebAPI to specify a colour value for any properties or methods that use one e.g. for halos. The prefix for this cast will be "colour" and value can either be a hexadecimal string or an integer value (not hexadecimal).
>
> For example it should be possible to call the following in a macro:
>
> ActionScript.SetProperty("Handles.PendingHalo", colour:"#ffff0000")


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

  * [[:macros:deploying|make this macro available]]
  * Using a macro to set a halo might not seem very intelligent. However, this might be a way to give some feedback. 




~~DISCUSSION~~