PrevICM Language Reference
Creating your own GUI elements: Programming GUI.
Next

There are three possibilities to add a new menu or a popup dialog.
  1. Main menus. Add or modify a section in the icm.gui file. To program the main GUI menus and popup dialogs, you need to modify a single file, called icm.gui . This file resides in the $ICMHOME directory. 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 line number, e.g. t.mol[%#]
     %^ is the column name, e.g.  
     %@ is the table name, e.g. %@.%^ is table.column
    
  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

The icm.gui section consists of the following fields:
FieldExampleDescription
MENUDisplay.Advanced.Pocketsthis menu item will be added in the top menu bar
OPTNApplyoptional. Allows to specify special kinds of dialogs.
OPTNConditions and Flags
COMMComment
ICONicon name
SYNTdisplay g_pocketthe ICM-command executed upon pressing 'OK' or 'Apply'.

An example:

 
MENU Display.Color.White 
SYNT color white 

Many examples of how to program controls for the script arguments can be found in the icm.gui file.

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 to filter the input, e.g. SYNT #20 i_Angle (360MIN:-360MAX: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_columnSYNT # C_Select_Column [TABLE:2,SARRAY] selected a column of the existing table. Works in pair with T_ or X_
ch_CompoundSYNT # ch_Draw_Compound draw compound or type SMILES/SMARTS string

Possible values of OPTIONS are:
option name description example
IARRAY,SARRAY,RARRAY,CHEMARRAYnarrow the choice for column selector C_
RDONLYsets control to read-only mode. User can not pick from the list.
REQUIREDinsist that the value is not empty
RESIZEallow resizing of the window [RESIZE]
RIGHT,LEFT,CENTERalignment 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
SMARTSgenerate SMARTS expression from ch_ input
NOCOORDSdo 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]
Here column selection ( C_by_Column ) for table B (the 3rd line) is refering to table B . T_Table_B has its reference number as 6 (not 4) because this i_tableReferenceNumber counter counts each o__inner o_left o_right as 3 words in contrast to the dollar-argument number .

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:

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_ .. ):

Functions for the Object arguments ( os1_ .. ):

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
See also: Askg


Prev
Soap
Home
Up
Next
Commands