| 1 |
.. _about_macros: |
| 2 |
|
| 3 |
Macros |
| 4 |
====== |
| 5 |
|
| 6 |
.. meta:: |
| 7 |
:description: How to use macros in DataLab, the open-source data analysis and visualization platform |
| 8 |
:keywords: DataLab, data analysis, data visualization, open-source, Python, macros |
| 9 |
|
| 10 |
Overview |
| 11 |
-------- |
| 12 |
|
| 13 |
There are many ways to extend DataLab with new functionality (see :ref:`about_plugins` |
| 14 |
or :ref:`ref-to-remote-control`). The easiest way to do so is by using macros. Macros |
| 15 |
are small Python scripts that can be executed from the "Macro Panel" in DataLab. |
| 16 |
|
| 17 |
.. figure:: ../../images/shots/macro_panel.png |
| 18 |
:align: center |
| 19 |
:alt: Macro Panel |
| 20 |
|
| 21 |
The Macro Panel in DataLab. |
| 22 |
|
| 23 |
Macros can be used to automate repetitive tasks, or to create new functionality. |
| 24 |
As the plugin and remote control system, macros rely on the DataLab high-level API |
| 25 |
to interact with the application. This means that you can reuse the same code snippets |
| 26 |
in macros, plugins, and remote control scripts. |
| 27 |
|
| 28 |
.. warning:: |
| 29 |
|
| 30 |
DataLab handles macros as Python scripts. This means that you can use the full |
| 31 |
power of Python to create your macros. Even though this is a powerful feature, |
| 32 |
it also means that you should be careful when running macros from unknown sources, |
| 33 |
as they can potentially harm your system. |
| 34 |
|
| 35 |
.. seealso:: |
| 36 |
|
| 37 |
The DataLab high-level API is documented in the :ref:`api` section. |
| 38 |
The plugin system is documented in the :ref:`about_plugins` section, and the |
| 39 |
remote control system is documented in the :ref:`ref-to-remote-control` section. |
| 40 |
|
| 41 |
Main features |
| 42 |
------------- |
| 43 |
|
| 44 |
The Macro Panel is a simple interface to: |
| 45 |
|
| 46 |
- Create new macros, using the "New macro" |libre-gui-add| button. |
| 47 |
- Rename existing macros, using the "Rename macro" |libre-gui-pencil| button. |
| 48 |
- Import/export macros from/to files, using the "Import macro" |fileopen_py| |
| 49 |
and "Export macro" |filesave_py| buttons. |
| 50 |
- Execute macros, using the "Run macro" |libre-camera-flash-on| button. |
| 51 |
- Stop the execution of a macro, using the "Stop macro" |libre-camera-flash-off| button. |
| 52 |
|
| 53 |
.. |libre-gui-add| image:: ../../../datalab/data/icons/libre-gui-add.svg |
| 54 |
:width: 24px |
| 55 |
:height: 24px |
| 56 |
:class: dark-light no-scaled-link |
| 57 |
|
| 58 |
.. |libre-gui-pencil| image:: ../../../datalab/data/icons/libre-gui-pencil.svg |
| 59 |
:width: 24px |
| 60 |
:height: 24px |
| 61 |
:class: dark-light no-scaled-link |
| 62 |
|
| 63 |
.. |fileopen_py| image:: ../../../datalab/data/icons/io/fileopen_py.svg |
| 64 |
:width: 24px |
| 65 |
:height: 24px |
| 66 |
:class: dark-light no-scaled-link |
| 67 |
|
| 68 |
.. |filesave_py| image:: ../../../datalab/data/icons/io/filesave_py.svg |
| 69 |
:width: 24px |
| 70 |
:height: 24px |
| 71 |
:class: dark-light no-scaled-link |
| 72 |
|
| 73 |
.. |libre-camera-flash-on| image:: ../../../datalab/data/icons/libre-camera-flash-on.svg |
| 74 |
:width: 24px |
| 75 |
:height: 24px |
| 76 |
:class: dark-light no-scaled-link |
| 77 |
|
| 78 |
.. |libre-camera-flash-off| image:: ../../../datalab/data/icons/libre-camera-flash-off.svg |
| 79 |
:width: 24px |
| 80 |
:height: 24px |
| 81 |
:class: dark-light no-scaled-link |
| 82 |
|
| 83 |
Macros are embedded in the DataLab workspace, so they are saved together with the rest |
| 84 |
of the data (i.e. with signals and images) when exporting the workspace to a HDF5 file. |
| 85 |
This means that you can share your macros with other users simply by sharing the |
| 86 |
workspace file. |
| 87 |
|
| 88 |
.. note:: |
| 89 |
|
| 90 |
Macro are executed in a separate process, so they won't block the main DataLab |
| 91 |
application. This means that you can continue working with DataLab while a macro |
| 92 |
is running and that *you can stop a macro at any time* using the |
| 93 |
|libre-camera-flash-off| button. |
| 94 |
|
| 95 |
Example |
| 96 |
------- |
| 97 |
|
| 98 |
For a detailed example of how to create a macro, see the :ref:`tutorial_custom_func` |
| 99 |
tutorial. |