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:

Field	Example	Description
MENU	Display.Advanced.Pockets	this menu item will be added in the top menu bar
OPTN	Apply	optional. Allows to specify special kinds of dialogs.
OPTN	Conditions and Flags
COMM	Comment
ICON	icon name
SYNT	display g_pocket	the ICM-command executed upon pressing 'OK' or 'Apply'.

An example:

 
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:

type	example	comment
b_button	SYNT # b_Undisplay_distances (delete g_distances)	executes the command in () when pressed.
d_directory	SYNT # d_PDB_Directory (SYS:s_pdbDir)	gives you a dialog to select a directory
ff_fileDialog	SYNT # f_Input_file↑*.mol;*.SD*;*.sd* ()	generates a secondary file dialog
f_fileDialog	SYNT # f_Input_file↑*.mol;*.SD*;*.sd* ()	generates a file dialog first, ignores other arguments
g_grobMesh	SYNT # g_Mesh (*)	star means show the current list of grobs in icm
i_integer	SYNT # i_size (10)	also allows one to filter the input, e.g. SYNT #20 i_Angle (360	MIN:-360	MAX:360)
l_logical	SYNT # l_high_res (yes)
o_radioButtons	SYNT {o_icmWord1_text_1 o_icmWord2_text_2 ..}
os1_molObjects, ms1_molecules, rs1_residues, as1_atoms
p_preference	SYNT # p_ribbonStyle_Ribbon_Style	internal name followed by the control title.
r_realVar	SYNT # r_temperature (200.)
R_realArray
s_stringVar	SYNT # s_name (John)	returns quoted "John"
txw_Big_Text_Box	SYNT # txw_Description ($s_out)	stores edited text in s_out variable. Use %s_out to access the value.
txt_text	SYNT # txt_boxName (Text to be displayed)	free comment
u_unknown
T_table	SYNT # T_Table_Name (*)	an asterisk (*) will be substituted with the list of tables
X_chemicalTable
C_column	SYNT # C_Select_Column [TABLE:2,SARRAY]	selected a column of the existing table. Works in pair with T_ or X_
ch_Compound	SYNT # ch_Draw_Compound	draw compound or type SMILES/SMARTS string

Possible values of OPTIONS are:

option name	description	example
IARRAY,SARRAY,RARRAY,CHEMARRAY	narrow the choice for column selector C_
RDONLY	sets control to read-only mode. User can not pick from the list.
REQUIRED	insist that the value is not empty
RESIZE	allow resizing of the window	[RESIZE]
RIGHT,LEFT,CENTER	alignment of the control on the dialog
TABLE:~~i_tableReferenceNumber	column selector C_ need a reference to a parent table. This number is found counting prefix_ before the table
SMARTS	generate SMARTS expression from ch_ input
NOCOORDS	do not include 2D coordinates into result of ch_ input

The i_tableReferenceNumber needs some clarification.

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:

VISIBLE s_condition| shows/hides control depending on condition
OPTN s_condition	enables/disables control depending on condition

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.