source: trunk/HELP_SOURCE/source/macro.hlp

#       main topics:
UP      arb.hlp
UP      glossary.hlp

#       sub topics:
#SUB     subtopic.hlp

# format described in ../help.readme


TITLE           Macros

OCCURRENCE      ARB_NT

DESCRIPTION     Macros are used to combine a set of menu-actions. They work like
                a tape recorder, which records all buttons presses, every input
                to data fields, ...

                To record a new macro, go to the directory where the new macro
                should be placed, enter a macro name and press <RECORD>. The
                button label will switch to <STOP>.

                Now perform all actions you like to record, then press <STOP>.

                If you like to expand an existing macro, check the 'Expand?' toggle
                before pressing <RECORD>. You can also check the 'Run before?' toggle
                to execute the existing macro before expanding it.

                Press 'Interrupt' while recording,
                to plan a later interruption during playback.
                See LINK{macro_interruption.hlp} for details.

                To execute an existing macro, select the macro and press <EXECUTE>.

                Press <Execute with each marked species> to execute the selected macro
                multiple times: once for each marked species.

                         * this loop is performed in database order (see LINK{sp_sort_fld.hlp}).
                         * before each call of the macro, one species will be marked AND
                           selected - all other species will be unmarked.
                         * afterwards the original species marks will be restored.

                Press <EDIT> to edit the selected macro.

                Press <DELETE> to delete the selected macro.

SECTION What gets recorded?

                The macro recorder only records elements like buttons, menues and
                values (like input fields, radio buttons, selection lists, toggles, ...).
                Actions in the main area (e.g. tree view) will not be recorded!

                Elements of a window are unknown to the macro playback if the window was not
                opened before. So - if you just record some changes and clicks in an already
                open window, you need to open that window everytime before you run that macro.

                Best practice is to CLOSE ALL SUBWINDOWS before you start recording a macro, then
                open them (again) and then perform your clicks. In that case your macro will run
                regardless whether the window has been opened before or not.
                Note: You can also record "closing a window".

                If you want to make sure that some field or toggle is set to a specific value
                by your recorded macro, you need to CHANGE that value. If it already has the
                desired value, change it to something different and then change it back to your
                desired value - otherwise nothing will be recorded!

                You may also use this as an feature: If you do NOT change a value during macro
                record, you can change it manually before calling the macro and that way perform
                similar, but different actions with one macro.

                This may as well be helpful when using submacros (see below).

SECTION         Calling submacros

                Macros can call other macros. To do this simply select the macro you like to call
                as submacro and press execute. That will be recorded like any other action.

                Calling submacros is a good way to compose complex macros.

                It offers you the possibility to change (or fix) small parts of a complex
                macro without the need to record it from scratch.

SECTION         Scripting arb

                You can run macros automatically at startup by using:

                        arb --execute macroname your_database.arb

                These macros can even shut down ARB, letting you fully automate tasks. If a macro
                invokes shutdown, ARB will not prompt before closing. Ensure your macro saves the
                database to prevent data loss.

                Sometimes ARB exits with an error (for example if a client like ARB_EDIT4 or ARB_PARSIMONY
                is still running). To avoid this, close all client processes when they're no longer needed.

                If a client fails to close properly, the arb script will pause and wait for a key press
                before continuing. By default, this timeout is three days. In automated environments,
                you may want to customize this wait period by setting the environment variable
                ARB_SCRIPTED_SECS_WAIT_ON_ERROR to the desired number of seconds (see also
                LINK{arb_envar.hlp}).

EXAMPLES        You can find some examples in $ARBHOME/lib/macros (this directory is reachable
                in the macro selection box by pressing the ARBMACRO line).

SECTION         Enhanced techniques

                Macros are perl scripts. So if you know perl or have someone @ your lab who does
                or just feel keen enough, macros can be easily extended to act more sophisticated.

                Some examples:

                     * to create a macro that works with the CURRENTLY SELECTED alignment
                       - record a macro using an explicit alignment (e.g. 'ali_16s') wherever needed
                       - edit the recorded macro file:
                         * above the 1st '# recording started'-line insert the following lines:

                           my $ali_selected = BIO::remote_read_awar($gb_main,'ARB_NT','presets/use');
                           if ((not defined $ali_selected) or ($ali_selected =~ /\?/)) {
                             die "Please select a valid alignment";
                           }

                         * below replace all

                                 occurrences of         with
                                'ali_16s'               $ali_selected

                           Note the single quotes!

                     * to create a macro that works with two corresponding dna and protein alignments
                       - record a macro using two explicit alignments (e.g. 'ali_dna' and 'ali_pro') wherever needed
                       - edit the recorded macro file:
                         * above the 1st '# recording started'-line insert the following lines:

                           use lib "$ENV{'ARBHOME'}/PERL_SCRIPTS/lib";
                           use ali_dnapro;
                           my ($ali_dna,$ali_pro) =  get_dnapro_alignments($gb_main);

                         * below replace all

                                 occurrences of         with
                                'ali_dna'               $ali_dna
                                'ali_pro'               $ali_pro

                           Note the single quotes!
                       - Notes:
                         * works only if the alignment names contain 'dna' and 'pro' and both
                           only differ by these terms.
                         * you may select either the dna or the protein alignment before
                           running the macro.

                The method used in the first example above also works for other
                selected things, like

                    * the selected tree using

                          my $tree_selected =  BIO::remote_read_awar($gb_main,'ARB_NT','focus/tree_name');

                    * the LINK{selected.hlp} using

                          my $species_selected =  BIO::remote_read_awar($gb_main,'ARB_NT','tmp/focus/species_name');
                          die "no species selected" if not defined $species_selected; # show error in ARB message window and abort

                    * the current cursor position in the editor

                          my $cursor_position =  BIO::remote_read_awar($gb_main,'ARB_NT','tmp/focus/cursor_position');


WARNINGS        None

BUGS            None