Debian Codegraph @

doc/features/advanced/macros.rst

raw
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.