.. meta::
    :description: Extensions Macros

Macros
======

This section explains how to create and edit macros.

Usage
-----
A macro is used to execute repetitive tasks.

A macro is a Python file that the application can analyze and execute like a script.

A macro is usually started using the :mod:`OrsPythonPlugins.OrsMacroPlayer.OrsMacroPlayer` plugin,
or by a contextual menu.

.. _filesLocationMacroExtension:

File location
-------------
To be recognized by the application, macros should be located in one of these folders:

- %LocalAppData%/ORS/Dragonfly(*version*)/pythonUserExtensions/Macros (available for the current user)
- %ProgramData%/ORS/Dragonfly(*version*)/pythonAllUsersExtensions/Macros (available for all users)
- %ProgramData%/ORS/Dragonfly(*version*)/python/OrsMacros (distributed with the application)

File creation
-------------
To create a macro, start the application, start the :mod:`OrsPythonPlugins.OrsMacroPlayer.OrsMacroPlayer`
(found in *Tools/Macro Player*),
start the recording and perform the tasks to be recorded in the macro.
This plugin can also create empty macro files.

File edition
------------
The plugin :mod:`OrsPythonPlugins.OrsMacroPlayer.OrsMacroPlayer` can be used to perform simple modifications.

For more advanced modifications, changes can be made directly into the file.
(See :class:`ORSServiceClass.macro.macroplayer.MacroPlayer` for more information about the structure of a macro file.)

.. note::
    When a macro file is modified, there is no need to restart the application for changes to take effect.
    The contextual menus will be automatically updated.
    When using the :mod:`OrsPythonPlugins.OrsMacroPlayer.OrsMacroPlayer` plugin, use the *reload* button
    to update the code to run.

Demos
-----

Source code example:

#. Download the :download:`file </Documentation/Demos/DemoMacroCreateDatasetAndROI_45ecd7b1a51c11e78db5448a5b5d70c0.py>`;
#. Put that file into a :ref:`macro extension folder <filesLocationMacroExtension>`;
#. Start the application;
#. Go to *Tools/Macro Player* to start the Macro Player;
#. Select the macro *DemoMacroCreateDatasetAndROI*;
#. Execute the macro.