6.19. Handling Menus

6.19.1. Introduction

Selecting from a list of options is often necessary in molecular biology programs. Two ACD datatypes (list and selection) provide slightly different styles of list but both present a user with a list of options they can choose from. For the user, the difference between the list and selection datatype is minimal and lies only in the way the choices are labelled. In a selection datatype the choices are numbered automatically from 1 upwards. In a list datatype the choices can be labelled by any arbitrary text. The user can choose one of the options by either typing the number (for a selection type) or the label text (for a list type), or (both list types) a non-ambiguous part of the descriptive text itself given after the number or label. In practice, the list data type is preferred.

6.19.2. AJAX Library Files

There is no specific AJAX library file for handling menus (see Table 6.32, “AJAX Library Files for Handling Menus”). Selections from menus are handled as strings or arrays of strings. You should consult the documentation for further information about string handling. Library file documentation is available online at:

http://emboss.open-bio.org/rel/dev/libs/
Table 6.32. AJAX Library Files for Handling Menus
Library File DocumentationDescription
ajstrString handling

ajstr.h/cDefines the string object (AjPStr) used for handling strings from the ACD file (see Section 6.4, “Handling "Simple" ACD Datatypes”). They contain most of the functions you will ever need for general string handling (Section 6.5, “Handling Strings”).

6.19.3. ACD Datatypes

There are two ACD datatypes for handling menus:

list

A list of options (text descriptions) with text labels. The user is presented with a limited list of options they can choose from. The choices can be labelled by any arbitrary text label. The option descriptions are usually more verbose than for the selection datatype.

selection

A list of options (text descriptions) with automatically-generated numerical labels. The user is presented with a limited list of options they can choose from. The choices are numbered automatically from 1 upwards.

6.19.4. ACD Data Definition

6.19.4.1. list menu

A typical ACD definition for a list menu:

list: frame  [
    standard: "Y"
    help: "Allows selection from a set of reading frames"
    default: "1"
    minimum: "1"
    maximum: "1"
    header: "Translation frames"
    values: "1:1, 2:2, 3:3, F:Forward three frames, -1:-1, -2:-2, -3:-3, R:Reverse three frames, 6:All six frames"
    delimiter: ","
    codedelimiter: ":"
    information: "Frame(s) to translate"
]

The user will be presented with the title of the menu from the header: attribute. After that will appear the tag/text information from the values: attribute. Following that will be the prompt from the information attribute:. It will look something like this:

Translation frames

   1     1
   2     2
   3     3
   F     Forward three frames
  -1    -1
  -2    -2
  -3    -3
   R     Reverse three frames
   6     All three frames

Frame(s) to translate[1]:

The user is allowed (generally) to supply a comma-separated list of options from the above; this depends on the minimum and maximum values. In the above example both the minimum number of selections and the maximum number of selections are set to one, therefore only one selection value is allowed. Selection is done by typing the tag values, therefore if the maximum count had been set to 3 then a user entry of "-1,F,6" would be a valid input.

The codedelimiter attribute allows you to select any character to separate the tags from the text in the values attribute. The delimiter attribute allows you to choose a character to separate the tag/text pairs within the values attribute.

6.19.4.2. selection menu

A typical ACD definition for a selection menu:

select: order  
[
    casesensitive: "N"
    default: "score"
    delimiter: ","
    header: "Sort order of results"
    help: "Name of the output file which holds the results of the analysis."
    information: "Sort order of results"
    maximum: "1"
    minimum: "1"
    information: "Select sort order of results"
    standard: "Y"
    values: "length, position, score"
]

Note

The selection datatype is very similar to the list datatype. The values: attribute just contains a delimiter-separated list of text entries (leading whitespace is ignored). Selection takes place on the text values, there are no tags. Also, note that there is a casesensitive: attribute which is often set to "N" so that shifted and non-shifted characters are equally acceptable. The user can select on the text down to a length of text that has no ambiguity with other values.

6.19.4.3. Parameter Name

Parameter names for menus should be intuitive but no standards are enforced.

6.19.4.4. Common Attributes

Attributes that are typically specified are summarised below. They are datatype-specific (Section A.5, “Datatype-specific Attributes”) unless they are indicated as being global attributes (Section A.4, “Global Attributes”).

values: For both the list and selection datatype menus the values that the user can choose from are defined in the values: attribute as a string.

delimiter: For both the list and selection datatype menus the values in the values: string are delimited by the character given by the delimiter: attribute, which defaults to ';' (semi-colon).

codedelimiter: For the list datatype the character defined by the codedelimiter: attribute is the delimiter that separates the label from the value, which defaults to ':' (colon).

minimum: Defines the minimum number of selections a user can make.

maximum: Defines the maximum number of selections a user can make.

header: Holds the text that is displayed above the list of options.

information: This global attribute (defined for all datatypes) defines text to be used as a prompt after the list.

casesensitive: Controls whether or not the options are case sensitive. Regardless of the case used by the user, the value of the parameter will be exactly what the corresponding list value is.

button: This attribute is provided for interface developers. It is a boolean which is either "Y" (Yes) or "N" (No), indicating whether a graphical button such as radio-button, checkbox or selection list should be used to select a value, or if the list should be displayed with a text entry box to enter the option.

6.19.5. AJAX Datatypes

The AJAX string datatype is used for handling menus defined in the ACD file is:

AjPStr *

Array of strings (for list and selection ACD datatypes).

6.19.6. ACD File Handling

Datatypes and functions for handling menus via the ACD file are shown below (Table 6.33, “Datatypes and Functions for File and Output”).

Table 6.33. Datatypes and Functions for File and Output
ACD datatypeAJAX datatypeTo retrieve from ACD
list menu
listAjPStr *ajAcdGetList
selection selection
outfileAjPStr *ajAcdGetSelect

Your application code will call embInit to process the ACD file and command line (see Section 6.3, “Handling ACD Files”). All values from the ACD file are read into memory. You have a handle on the files and memory through the ajAcdGet* family of functions which return pointers to appropriate objects.

6.19.6.1. Menu Retrieval

To retrieve a menu an object pointer is declared and then initialised using the appropriate ajAcdGet* function.

6.19.6.1.1. list Menu
    ...
    AjPStr *flist=NULL;
    ...

    flist = ajAcdGetList("frame");
    ...

The declaration shows that flist will be an array of string objects. The values held in the strings are the tags from the values list and the list is terminated by a NULL pointer. So, using our example, as only one value is allowed and assuming the user had answered '6' to the prompt the resulting array would be:

    flist[0]     a string object that contains "6"
    flist[1]     a NULL pointer

Your code would likely step through the list, if maximum is greater than 1, using something like the following:

    n = 0;
    while(flist[n])
    {
        if (ajStrMatchC(flist[n],"6"))
        {
            /* Do something */
        }

        ...
       ++n;
    }
6.19.6.1.2. selection Menu
    ...
    AjPStr *oselect=NULL;
    ...

        oselect = ajAcdGetSelect("order");
    ...

Otherwise the code is the same as for the list datatype with the exception that it would test for the strings "length", "position" and "score".

6.19.6.2. Alternative ACD Retrieval Functions

AjPStr  ajAcdGetListSingle (const char *token);
AjPStr  ajAcdGetSelectSingle (const char *token);

It is your responsibility to free up memory at the end of the program. You have only retrieved one strings, the remainder of the internal data will be cleaned up autiomatically by ACD processing. You should call ajStrDel to free the string returned by these functions.

6.19.6.3. Processing Command line Options and ACD Attributes

Currently there are no functions for this.

6.19.6.4. Memory Management

It is your responsibility to free up memory at the end of the program. You must call the destructor function on the string array returned by calls to ajAcdGetList or ajAcdGetSelect.

The destructor for an array of strings is:

void  ajStrDelarray (AjPStr** PPstr);

It is used as follows:

    AjPStr *flist=NULL;

    flist = ajAcdGetList("frame");

    ...

    ajStrDelarray(&flist);