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.
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/ |
| Library File Documentation | Description |
|---|---|
| ajstr | String handling |
ajstr.h/c. Defines 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”).
There are two ACD datatypes for handling menus:
listA 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.
selectionA 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.
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.
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"
]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.
Parameter names for menus should be intuitive but no standards are enforced.
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.
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).
Datatypes and functions for handling menus via the ACD file are shown below (Table 6.33, “Datatypes and Functions for File and Output”).
| ACD datatype | AJAX datatype | To retrieve from ACD |
|---|---|---|
list menu | ||
list | AjPStr * | ajAcdGetList |
selection selection | ||
outfile | AjPStr * | 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.
To retrieve a menu an object pointer is declared and then initialised using the appropriate ajAcdGet* function.
...
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 pointerYour 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;
}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.
Currently there are no functions for this.
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);