source: branches/lib/HELP_SOURCE/source/gde_menus.hlp

UP      arb.hlp
UP      agde.hlp
UP      glossary.hlp
UP      save.hlp

TITLE           Customizing GDE menus

DESCRIPTION     ARB uses the GDE menus to plugin external tools

                This helpfile contains parts of the original GDE helpfile
                and has been modified to fit to the way
                GDE menus are used inside ARB.

SECTION Description of GDE menus as used in ARB

        The GDE uses a menu description language to
        define what external programs it can call, and what
        parameters and data to pass to each function. This
        language allows users to customize their own
        environment to suite individual needs.

        The following is how the GDE handles external
        programs when selected from a menu:

        Each step in this process is described in the file

                $ARBHOME/lib/gde/arb.menu

        The directory $ARBHOME/lib/gde also contains other .menu-files
        for separate external tool integration (e.g. raxml8, sativa).

        You may integrate any external tool into the ARB interface
        by adding files with suffix '.menu' either into
        the global directory '$ARBHOME/lib/gde/' (menus defined there will
        be available to all users) or into '~/.arb_prop/gde/' (menus defined
        there will not be available to other users).


SECTION GDE menus language

        The language used in this file describes three phases
        to an external function call. The first phase
        describes the menu item as it will appear, and the
        Unix command line that is actually run when it is
        selected. The second phase describes how to prompt
        for the parameters needed by the function. The third
        phase describes what data needs to be passed as
        input to the external function, and what data (if any)
        needs to be read back from its output.

        The form of the language is a simple keyword/value
        list delimited by the colon (:) character. The
        language retains old values until new ones are set.
        For example, setting the menu name is done once for
        all items in that menu, and is only reset when the
        next menu is reached.

        The keywords for phase one are:

                menu:menu name      Name of current menu
                menumeta:meta_key   Meta key equivalence (quick keys)
                menumask:expert     Whole menu will be inaccessible in ARBs novice mode

                item:item name

                          Name of current menu item

                          Please do not change 'item name' for cosmetic
                          purposes - doing so will invalidate user-stored-configs!


                itemmeta:meta_key   Meta key equivalence (quick keys)
                itemhelp:help_file  Help file (either full path, or in $ARBHOME/lib/help)
                itemmethod:         Unix command
                itemmask:expert     Whole menu will be inaccessible in ARBs novice mode

                seqtype:TYPE
                        Known TYPEs:
                              'A' -> select amino acid sequences
                              'N' -> select nucleotide sequences
                              '*' -> select ANY sequences
                              '-' (or whole entry missing) -> do not select sequences

        The itemmethod command is a bit more involved, it
        is the Unix command that will actually run the
        external program intended.

        It is one line long, and can be up to 4096 characters in
        length. It can have embedded variable names (starting
        with a '$') that will be replaced with appropriate values
        later on.

        It can consist of multiple Unix commands separated by
        semi-colons (;) and may contain shell scripts and
        background processes as well as simple command names.

        If one of the commands needs access to the running ARB, the
        whole command should be run asynchronously, i.e. be run
        using '( command ) &'. Otherwise the command may lock.

        ARB provides synchronisation in this case, i.e. the GUI will
        be inaccessible and ARB waits for your command to finish.
        This is required for proper macro excution: otherwise the macro
        would continue before the asynchronous command has finished.

        The keywords for phase two are:

            arg:argument_variable_name

                        Name of this variable. It will appear
                        in the itemmethod: line with a dollar
                        sign ($) in front of it.

                        Please do not change 'argument_variable_name' for cosmetic
                        purposes - doing so will invalidate user-stored-configs!

            argtype:TYPE
                        The type of graphic object
                        representing this argument.

                        Known types are

                              choice_list
                              choice_menu
                              chooser
                              filename
                              sai
                              slider
                              text
                              tree
                              weights

            arglabel:descriptive label

                        A short description of what this
                        argument represents

            argmin:minimum_value (integer)

                        Used for sliders.

            argmax:maximum_value (integer)

                        Used for sliders.

            argvalue:default_value

                        It is the numeric value associated with
                        sliders or the default choice in
                        choosers, choice_menus, and choice_lists
                        (the first choice is 0, the second is 1 etc.)

            argtext:default value

                        text: Default value
                        filename: default extension


            argchoice:displayed value:passed value

                        Used for choosers and
                        choice_menus. The first value is
                        displayed on screen, and the second
                        value is passed to the itemmethod
                        line.

            argmask:expert

                        Whole arg will be inaccessible in ARBs novice mode


        The keywords for phase three are as follows:

            in:input_file

                        GDE will replace this name with a randomly generated temporary file
                        name. It will then write the selected data out to this file.

                        Convention: always use TmpInputFile as placeholder

            informat:file_format

                        Write data to this file for input to
                        this function. Currently support
                        values are Genbank, and flat.

            intyped:DETAILS

                        Whether to save sequence type information.

                        Known DETAILS:

                              basic        default; plain sequences exported
                              detailed     -> prefix sequence name by IDCHAR

                        Known IDCHARs:

                              '#'       RNA / DNA
                              '%'       PROTEIN
                              '@'       MASK (obsolete)
                              '"'       TEXT or unknown

            insave:

                        Do not remove this file after running
                        the external function. This is useful
                        for functions put in the background.

            out:output_file

                        GDE will replace this name with a randomly generated temporary file
                        name. It is up to the external function to fill this file with any results that
                        might be read back into the GDE.

                        Convention: always use TmpOutputFile as placeholder

            outformat:file_format

                        The data in the output file will be in
                        this format. Currently support
                        values are colormask, Genbank, and
                        flat.

            outaligned:yes

                        GDE assumes external tool is an aligner or similar
                        which only changes the alignment of bases.
                        Sequence data will be re-imported w/o asking questions.

                        Several minor changes in sequence data (by external tool)
                        will be accepted and silently reverted. This includes
                             - changing 'U' into 'T' (or vv)
                             - case changes
                             - gap changes ('.' to '-' or vv)

            outsave:

                        Do not remove this file after reading.
                        This is useful for background tasks.


        Here is a sample dialog box, and it's entry in the
        .GDEmenus file:

        Using the default parameters given in the dialog
        box, the executed Unix command line would be:

             (tr '[a-z]' '[A-Z]' < .gde_001 >.gde_001.tmp ; mv .gde_001.tmp CAPS ; gde CAPS -Wx medium ; rm .gde_001 ) &

        where .gde_001 is the name of the temporary file
        generated by the GDE which contains the selected
        sequences in flat file format. Since the GDE runs
        this command in the background ('&' at the end) it
        is necessary to specify the insave: line, and to
        remove all temporary files manually. There is no
        output file specific because the data is not loaded
        back into the current GDE window, but rather a new
        GDE window is opened on the file. A simpler
        command that reloads the data after conversion
        might be:

              item:          All caps
              itemmethod:    tr '[a-z]' '[A-Z]' <INPUT > OUTPUT
              in:            INPUT
              informat:      flat
              out:           OUTPUT
              outformat:     flat

        In this example, no arguments are specified, and so
        no dialog box will appear. The command is not run
        in the background, so the GDE can clean up after
        itself automatically. The converted sequence is
        automatically loaded back into the current GDE
        window.

        In general, the easiest type of program to integrate
        into the GDE is a program completely driven from a
        Unix command line. Interactive programs can be
        tied in (MFOLD for example), however shell scripts
        must be used to drive the parameter entry for these
        programs. Programs of the form:

                program_name -a1 argument1 -a2 argument2 -f inputfile -er errorfile > outputfile

        can be specified in the .GDEmenus file directly. As
        this is the general form of most one Unix commands,
        these tend to be simpler to implement under the
        GDE.

        As functions grow in complexity, they may begin to
        need a user interface of their own. In these cases, the
        command line calling arguments are still necessary
        in order to allow the GDE to hand them the
        appropriate data, and possible retrieve results after
        some external manipulation.



SECTION Copyright Notice

        The Genetic Data Environment (GDE) software and
        documentation are not in the public domain.
        Portions of this code are owned and copyrighted by
        the The Board of Trustees of the University of
        Illinois and by Steven Smith. External functions
        used by GDE are the proporty of, their respective
        authors. This release of the GDE program and
        documentation may not be sold, or incorporated into
        a commercial product, in whole or in part without
        the expressed written consent of the University of
        Illinois and of its author, Steven Smith.

        All interested parties may redistribute the GDE as
        long as all copies are accompanied by this
        documentation, and all copyright notices remain
        intact. Parties interested in redistribution must do
        so on a non-profit basis, charging only for cost of
        media. Modifications to the GDE core editor should
        be forwarded to the author Steven Smith. External
        programs used by the GDE are copyright by, and are
        the property of their respective authors unless
        otherwise stated.


        While all attempts have been made to insure the
        integrity of these programs:

SECTION Disclaimer

        THE UNIVERSITY OF ILLINOIS, HARVARD
        UNIVERSITY AND THE AUTHOR, STEVEN
        SMITH GIVE NO WARRANTIES, EXPRESSED
        OR IMPLIED FOR THE SOFTWARE AND
        DOCUMENTATION PROVIDED, INCLUDING,
        BUT NOT LIMITED TO WARRANTY OF
        MERCHANTABILITY AND WARRANTY OF
        FITNESS FOR A PARTICULAR PURPOSE.
        User understands the software is a research tool for
        which no warranties as to capabilities or accuracy are
        made, and user accepts the software "as is." User
        assumes the entire risk as to the results and
        performance of the software and documentation. The
        above parties cannot be held liable for any direct,
        indirect, consequential or incidental damages with
        respect to any claim by user or any third party on
        account of, or arising from the use of software and
        associated materials. This disclaimer covers both the
        GDE core editor and all external programs used by
        the GDE.