1. Main menus. Add or modify a section in the icm.gui file, or (preferred) your own file in the same format. To program the main GUI menus and popup dialogs, you can modify a single central file, called icm.gui or create your own .gui file. This main icm.gui file resides in the $ICMHOME directory, while your own additional file can be anywhere else. The icm.gui file contains controls for each menu item. It the menu item requires a dialog, it is automatically generated.
2. Popup dialogs in tables. Add a header element called cellPopup or tablePopup need to be added to a table, e.g.

   add column t {1 2 3}
   add header t "POPT New Table Item\nSYNT # T_Table\nSYNT # r_Enter_Real (2.)\nSYNT show $1\n" name="tablePopup"
   add header t "POPT New Table Cell Item\nSYNT # r_Enter_Real (2.)\nSYNT print $1 + %@.%^[%#]" name="cellPopup"

   The following shortcuts are allowed:

   %@ is the table name, e.g. %@.%^ is table.column
    %# is the line/row  number, e.g. t.mol[%#]
    %^ is the column name corresponging to the cell.

3. Popup dialogs in internal html-documents. For those you need to add ths following line:

   #dialog{"YourCaption"}

   so that the dialog looks like this:

   #dialog{"Enter name"}
   # s_name ("Kosmo")
   # ff_file|*.html ("")
   print $1 $2

   #dialog{ "Sample Dialog" }
   # txw_Enter_Text ()
   txt = %s_out   # s_out is not a safe place (might be overwritten)
   print Length(txt)

   Notice underscore containing names like s_ need to be capped with the percent symbol

One icm.gui section consists of the following fields:

MENU Display.Color.White 
SYNT color white

Creating controls for the main input data types.

To create a control for a particular data type one needs to add the following line.

SYNT # t_name ( default1 | default2 ) [ OPTIONS> ]
Example:

SYNT # i_enterInt (10)

The following input types are possible:

Possible values of OPTIONS are:

SYNT # T_Table_A (*)  [RDONLY,LMINWIDTH:110] C_by_Column () [TABLE:1,RESIZE,LMINWIDTH:110]
SYNT # { o__inner o_left o_right } [CENTER]
SYNT # T_Table_B (*) [RDONLY,LMINWIDTH:110] C_by_Column () [TABLE:6,RESIZE,LMINWIDTH:110]

Conditional options:

Example of "Extract Ligand" dialog :

MENU Extract Ligand(s)
COMM Extract ligand into chemical table
OPTN !isMini !isPharm
ICON bipm_chemring
SYNT #1 ms1_
SYNT #2 { o_"2D"_as_2D_drawing o_"3D"_keep_3D_coordinates }
SYNT #3 l_append_To_Existing_Table (no) [OPTN:(nChemTable)] X_ (*) [RDONLY,OPTN:($4)]
SYNT if (   $3 ) extractLigand $1 $2 $3 Name( $4 table )
SYNT if ( ! $3 ) extractLigand $1 $2 $3 ""

Example of "Merge Two Sets" dialog:

MENU Chemistry.Merge Two Sets
OPTN nTable>1
SYNT # T_Table_A (*)  [RDONLY,LMINWIDTH:110] C_by_Column () [TABLE:1,RESIZE,LMINWIDTH:110]
SYNT # { o__inner o_left o_right } [CENTER]
SYNT # T_Table_B (*) [RDONLY,LMINWIDTH:110] C_by_Column () [TABLE:6,RESIZE,LMINWIDTH:110]
SYNT # txt_Hint (inner - only molecules present in BOTH A and B tables are kept<br>left - ALL rows of A are kept<br>right - ALL rows of B are kept)
SYNT join $2 $5 $3

Specifying the default values of the arguments

The general syntax of the default value specification is:

( value1 | value2 | ...)

Where default_value can also be one of the following:

• asterisk, * : lists all values/variables of specified class, e.g. seq_ (*)
• dynamic condition: expression in extra parenthesis containing filtering condition, e.g. ((isAmino))
• custom text/string. This is either any text or expression in the form: internal_text@Human_Readable_Text , e.g. (10|0@all) you will see all , but value 0 will be returned.

Examples:

os1_Select_Object (*)             # lists all objects loaded in current session
os1_SelectObject ((isIcmObj))        # lists all ICM objects
os1_SelectObject (*|Obj(as_graph)@Graphic Selection)        # lists all ICM objects plus 'static choice' of graphic selection

ms1_Select_Molecule ((!isWater))  # will forms a list of all molecules excluding waters
ms1_Select_Molecule ((isAmino)|(isNucl))  # will forms a list of all amino and nucl chain molecules.
ms1_Select_Molecule ((isHet)|(isAmino&nResInMol<10))   # list all ligands plus short amino chains (peptides)

This is a list of internal GUI functions that can be used in dynamic conditions

Functions for the Molecular arguments ( ms1_ .. ):

• isAmino (lists amino chains)
• isNucl (lists nucleotide chains)
• isHet (lists hetero molecules - ligands)
• isMetal (lists metals)
• isWater (lists water)
• isDsMol (lists displayed molecules )
• isIcmObj (only molecules of ICM objects )
• isLinkedToAli (lists linked to an alignment molecules)
• hasSwissID (lists molecules with swiss ID)
• nResInMol (counts number of residues in molecule)
• nAtomInMol (counts number of residues in molecule)

Functions for the Object arguments ( os1_ .. ):

• hasAmino (lists objects with amino chains)
• hasNucl (lists objects with nucleotide chains)
• hasHet (lists objects with ligands)
• hasMetal (lists objects with metals)
• hasStack (lists objects with attached conformation stack)
• nMolInObj (counts number of molecules in the object)
• nResInObj (counts number of residues in the object)
• nAtomInObj (counts number of atoms in the object)
• isIcmObj (lists ICM objects)
• isDsSelObj (lists displayed and selected objects)
• isDsObj (lists displayed objects)
• isPharm (lists pharmacophore objects)

Suppressing the automatic interpretation of X_ with the % symbol.

Note, that the GUI dialogs and controls are generated automatically every time the program finds a letter followed by underscore. For that reason if you want to suppress that action, use the percent symbol, e.g.

SYNT print  %s_out # do not want to generate a text dialog.
SYNT display %as_graph # here you do not want to generate an as_ selection dialog
SYNT if Nof(g_distances)==0 delete  %g_distances

Specifying MIN and MAX values, or adding other controls.

SYNT #20 i_Angle        (360|MIN:-360|MAX:360)

Specifying objects, molecules, residues and atoms

More detailed examples.

SYNT # f_Input_file|*.mol;*.SD*;*.sd* () # generates a file dialog
SYNT # r_Sphere ( 3. ) # here r_ is the type; 3. is the default value
SYNT # r_Resolution_Increase (1.2|1.5|1.75|2|2.5|3) # you can provide popular choices
SYNT # r_Ribbon_Width   (SYS:GRAPHICS.ribbonWidth) # that is how a system variable is redefined

The actual icm commands that use those arguments refer to them as $1 $2 .. , e.g.

# choose a mesh and save it to a file
SYNT # g_mesh (*) 
SYNT # f_file 
SYNG write $1 $2

Layout issues

Layout defines how various input elements are arranged on the page. ICM arranges all controls in a single line horizontally. Each new line in the dialog definition starts a new horizontal layout. In some cases you need to arrange controls as a grid. BEGINGRID and ENDGRID options should be used to do this:

Example:

# l_Anilines (yes) [BEGINFRAME:Options,BEGINGRID] l_Nitro (yes)
# l_Metals (yes) l_Carboxylic_Acid (yes)
# l_Hologen_Hydrides (yes) l_Aldehydes (yes)
# l_Alkyl_halides (yes) l_Acid_halides (yes) [ENDGRID,ENDFRAME]

Radio-buttons can be also arranged in a several rows/columns.

Example:

# { o_1_Option_11 [HORIZONTAL:2] o_2_Option_12 o_2_Option_13 o_2_Option_14 o_2_Option_15 } 
# { o_1_Option_11 [VERTICAL:2] o_2_Option_12 o_2_Option_13 o_2_Option_14 o_2_Option_15 }

Creating a dialog with tabs.

Each page (tab) should be started with '%%%Page_Name' line. Then follows a page declaration.

Example:

MENU &File.Tabs Example
SYNT %%%Page1
SYNT # s_Text_1 ("aaa") [REQUIRED]
SYNT print $1
SYNT %%%Page2
SYNT # s_Text_2 ("bbb") [REQUIRED]
SYNT print $1
SYNT %%%Page3
SYNT # s_Text_3 ("ccc") [REQUIRED]
SYNT print $1

Creating a wizard dialog.

You may easily convert your tab dialog into wizard dialog by replacing '%%%' with '^{^'.}

Example:

MENU &File.Wizard Example
SYNT ^^^Page1
SYNT # s_Text_1 ("aaa") [REQUIRED]
SYNT print $1
SYNT ^^^Page2
SYNT # s_Text_2 ("bbb") [REQUIRED]
SYNT print $1
SYNT ^^^Page3
SYNT # s_Text_3 ("ccc") [REQUIRED]
SYNT print $1

Adding custom user functions to 'Insert Column'

This section contains description of the syntax to custom function for Insert Column dialog.

Example:

CFUN newgroup.Ligand_Strain
SYNT # (X)->r
SYNT funcLigStrain(%1)

Each column function start with CFUN which contains dot separated path in the form of folder1.folder2.funcname

Existing folders ID are:

• creat : "New"
• trans : "Transformations"
• arith : "Arithmetical"
• math : "Mathematical"
• search : "Find"
• str : "Text"
• chem : "Chemical"

For example to add new function into 'New' folder the path should look like: creat.MyNewFunc

The SYNT section should contain one or more template description. Each template description line start with '#'

Template describes the type of arguments and the result type.

The syntax:

(<arguments>)->(<result>), brackets are optional
arguments: space or comma-separated values in format: 
        type:argname=default
Types combination of: i r s l w I R S X (Uppercase: array, lowcase: constant)
  "I" will accept both integer column (Iarray) and integer constant
  1I 1R 1S 1IR 1IRSX .. -- no constants allowed (only arrays)

Examples:

• (r r)->r # takes to real columns or two real values and return real column as a result
• (X r:curoff=0.5)->r # takes chemical and optional real argument with default 0.5

The line in the SYNT section which does not start with '#' will be treated as an arithmetic expression which calculates the column value. It may contain any arithmetic operators, constants, shell functions and user functions.

See add column function for details.