source: branches/stable/HELP_SOURCE/oldhelp/macro.hlp

Last change on this file was 18446, checked in by westram, 6 years ago
  • document key bindings for paging.
  • show howto handle undefined result from remote_read_awar.
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 6.6 KB
Line 
1#Please insert up references in the next lines (line starts with keyword UP)
2UP      arb.hlp
3UP      glossary.hlp
4
5#Please insert subtopic references  (line starts with keyword SUB)
6#SUB    subtopic.hlp
7
8# Hypertext links in helptext can be added like this: LINK{ref.hlp|http://add|bla@domain}
9
10#************* Title of helpfile !! and start of real helpfile ********
11TITLE           Macros
12
13OCCURRENCE      ARB_NT
14
15DESCRIPTION     Macros are used to combine a set of menu-actions. They work like
16                a tape recorder, which records all buttons presses, every input
17                to data fields, ...
18
19                To record a new macro, go to the directory where the new macro
20                should be placed, enter a macro name and press <RECORD>. The
21                button label will switch to <STOP>.
22
23                Now perform all actions you like to record, then press <STOP>.
24
25                If you like to expand an existing macro, check the 'Expand?' toggle
26                before pressing <RECORD>. You can also check the 'Run before?' toggle
27                to execute the existing macro before expanding it.
28
29                To execute an existing macro, select the macro and press <EXECUTE>.
30
31                Press <Execute with each marked species> to execute the selected macro
32                multiple times: once for each marked species.
33
34                         * this loop is performed in database order (see LINK{sp_sort_fld.hlp}).
35                         * before each call of the macro, one species will be marked AND
36                           selected - all other species will be unmarked.
37                         * afterwards the original species marks will be restored.
38
39                Press <EDIT> to edit the selected macro.
40
41                Press <DELETE> to delete the selected macro.
42
43SECTION What gets recorded?
44
45                The macro recorder only records elements like buttons, menues and
46                values (like input fields, radio buttons, selection lists, toggles, ...).
47                Actions in the main area (e.g. tree view) will not be recorded!
48
49                Elements of a window are unknown to the macro playback if the window was not
50                opened before. So - if you just record some changes and clicks in an already
51                open window, you need to open that window everytime before you run that macro.
52
53                Best practice is to CLOSE ALL SUBWINDOWS before you start recording a macro, then
54                open them (again) and then perform your clicks. In that case your macro will run
55                regardless whether the window has been opened before or not.
56                Note: You can also record "closing a window".
57
58                If you want to make sure that some field or toggle is set to a specific value
59                by your recorded macro, you need to CHANGE that value. If it already has the
60                desired value, change it to something different and then change it back to your
61                desired value - otherwise nothing will be recorded!
62
63                You may also use this as an feature: If you do NOT change a value during macro
64                record, you can change it manually before calling the macro and that way perform
65                similar, but different actions with one macro.
66
67                This may as well be helpful when using submacros (see below).
68
69SECTION Calling submacros
70
71                Macros can call other macros. To do this simply select the macro you like to call
72                as submacro and press execute. That will be recorded like any other action.
73
74                Calling submacros is a good way to compose complex macros.
75
76                It offers you the possibility to change (or fix) small parts of a complex
77                macro without the need to record it from scratch.
78
79NOTES           You can run macros directly on startup by calling arb by
80
81                        arb --execute macroname your_database.arb
82
83                Such macros can even shutdown ARB, so you can use this to automate ARB.
84
85EXAMPLES        You can find some examples in $ARBHOME/lib/macros (this directory is reachable
86                in the macro selection box by pressing the ARBMACRO line).
87
88SECTION         Enhanced techniques
89
90                Macros are perl scripts. So if you know perl or have someone @ your lab who does
91                or just feel keen enough, macros can be easily extended to act more sophisticated.
92
93                Some examples:
94
95                     * to create a macro that works with the CURRENTLY SELECTED alignment
96                       - record a macro using an explicit alignment (e.g. 'ali_16s') wherever needed
97                       - edit the recorded macro file:
98                         * above the 1st '# recording started'-line insert the following lines:
99
100                           my $ali_selected = BIO::remote_read_awar($gb_main,'ARB_NT','presets/use');
101                           if ((not defined $ali_selected) or ($ali_selected =~ /\?/)) {
102                             die "Please select a valid alignment";
103                           }
104
105                         * below replace all
106
107                                 occurrences of         with
108                                'ali_16s'               $ali_selected
109
110                           Note the single quotes!
111
112                     * to create a macro that works with two corresponding dna and protein alignments
113                       - record a macro using two explicit alignments (e.g. 'ali_dna' and 'ali_pro') wherever needed
114                       - edit the recorded macro file:
115                         * above the 1st '# recording started'-line insert the following lines:
116
117                           use lib "$ENV{'ARBHOME'}/PERL_SCRIPTS/lib";
118                           use ali_dnapro;
119                           my ($ali_dna,$ali_pro) =  get_dnapro_alignments($gb_main);
120
121                         * below replace all
122
123                                 occurrences of         with
124                                'ali_dna'               $ali_dna
125                                'ali_pro'               $ali_pro
126
127                           Note the single quotes!
128                       - Notes:
129                         * works only if the alignment names contain 'dna' and 'pro' and both
130                           only differ by these terms.
131                         * you may select either the dna or the protein alignment before
132                           running the macro.
133
134                The method used in the first example above also works for other
135                selected things, like
136
137                    * the selected tree using
138
139                          my $tree_selected =  BIO::remote_read_awar($gb_main,'ARB_NT','focus/tree_name');
140
141                    * the LINK{selected.hlp} using
142
143                          my $species_selected =  BIO::remote_read_awar($gb_main,'ARB_NT','tmp/focus/species_name');
144                          die "no species selected" if not defined $species_selected; # show error in ARB message window and abort
145
146                    * the current cursor position in the editor
147
148                          my $cursor_position =  BIO::remote_read_awar($gb_main,'ARB_NT','tmp/focus/cursor_position');
149
150
151WARNINGS        None
152
153BUGS            None
154
155
156
Note: See TracBrowser for help on using the repository browser.