FORM resource
A FORM is a required resource that describes a dialog box that prompts the user for information or displays information. In Oasis montaj, you see forms when you select a menu option followed by ellipses (...) or when you run a GX that requires interactive parameter entry. Form elements include a title bar, entry fields for text, numbers, lists of files, and push buttons.
The form is made up of a FORM resource, which may contain edit fields and buttons. Those components may linked to LIST or HELP resources.
When a FORM dialog box is displayed, the user can enter any required and optional information, then press a button to choose an action, or press <Esc> to close the box without making changes. Many forms will include a <Cancel> button, which is equivalent to the user pressing <Esc>.
FORM Syntax
RESOURCE, FORM, resource_name, “title”, esc_val
| Parameter | Description |
|---|---|
| resource_name | Identifies an individual resource. You must use a unique name for each resource in a GX. |
| title | The title of the form dialog, which appears at the top of the dialog when displayed to the user. SetTitle_DGW(hDGW,"My new title"); |
| esc_val | Specifies the number that is returned if the user presses <Esc>. If this occurs, no validation is done (entered values are not stored or evaluated). The esc_val should normally be set to –1, or the same as used for a [Cancel] button. |
FORM Example
GXC file diff.gxc contains a form resource line that describes a FORM named "DiffForm" as follows:
RESOURCE,FORM,DiffForm,"Calculate differences",-1 . . .
In your GX source code, "DiffForm" would be referenced as follows. In this sample, hDGW has been declared to be a DGW class instance:
#include "diff.grh" // this needs to be at the top of the GXC file before variable definitions
.
.
.
DGW hDGW
.
.
.
// --- Create the Dialogue ---
hDGW = Create_DGW("DiffForm"); //loads resources in "DiffForm" to create a dialog control
.
.
.
FORM Components
A FORM resource will have one or more field and button components. Field and list resource components will appear on the dialog box in the order that you specify them, meaning that you can control their vertical positioning. Buttons appear at the bottom of the dialog, and are positioned horizontally left to right in the order specified.
| Component | Description |
|---|---|
| EDIT | simple edit field syntax: EDIT,,,width,{&}label,{required},{validation},{default_value} |
| FEDIT | file\browse field syntax: FEDIT,,, width,{&}label,{required},{validation},{default_value}, {file_path},{file_mask} |
| LEDIT | List selection field syntax: LEDIT ,,,width,{&}label,{required},{validation},{default_value}, list_resource |
| CEDIT | Colour selection field syntax: CEDIT,,,width,{&}label,{required},{default_value} |
| EBUT | Exit button syntax: EBUT, {&}label{~},ret_val,{cancel} |
| HBUT | Help button syntax: HBUT, {&}label,help_resource |
FORM Component Parameters
The following table describes the parameters, purpose and/or values you can specify for the various FORM resource components. The second and third parameters in the EDIT, FEDIT and LEDIT components are no longer used, but their positions, marked by commas without values, must be retained.
| Parameter | Description |
|---|---|
| width | Defines the width of an edit field in characters. The maximum width will depend on your system display limitations. It is a good idea to make all edit fields in a GX the same width because this improves the appearance of the dialog. |
| label | Identifies the label associated with this object. The label is displayed on the left of edit fields, and as the text in a button. Labels can be changed from a GX by calling the SetInto_DGW as in the following example: SetInfo_DGW(hDGW,_MYFORM_0,DGW_LABEL,"My new label"); The "&" character placed before a character of the label in a button will make that character the “hot” button that lets your user activate the button by pressing <Ctrl-character> Placing a ~ (tilde) character after a button label will make this button the default action when the user presses <return> or <enter> |
| required | R if a user entry is required; N for a non-editable entry (appears in a gray background); blank for optional user entry. |
| validation | Indicates the type of values, files or user selections you want to allow for the component. One of the following: INT – (EDIT) integer value REAL- (EDIT) real value PASSWORD – allows entry of a password in which user keystrokes are displayed as a ‘*’ character. N – (EDIT) indicates read-only. Text appears in a grayed window NEW – (FEDIT) file does not yet exist and the user will be prompted to confirm. OLD – (FEDIT) the file must already exist FORCE – (LEDIT) forces user to select one of the items in the list |
| default_value | Default value to place in the field if the GX has not specifically set a value. You can also use a default value defined in geosoft.ini by specifying %group.parameter%”. For example, “%MONTAJ.DEFAULT_COLOUR%” will place the default colour table in a field by default. (This if for colour file selection only, and not for use in the CEDIT (colour selection) tool .) Note that the SetInfo_DGW and SetInfoSYS_DGW methods will change the value in a dialog field. |
| file_path | Indicates the default path from which to create a file list. Use a tilde (~) to indicate the Geosoft directory. Multiple items may be specified, separated by commas. |
| file_mask | Defines the file name mask (default is *.*). "/" to look for directories only. ”**” to allow multiple file selection (see note below) "*.grd" displays all data and image DAT types that are available. "*.GRDDAT" limits the list to data grid DATs. "*.IMGDAT" limits the list to image DATs. Multiple masks can be specified by separating each mask by a semicolon. To select multiple files of a specific type, make the first mask “**” followed by a semicolon and the mask for the file type wanted. For example “**;*.grd” allows the user to select multiple grid files. Extensions can be changed from a GX by calling the SetInto_DGW as in the following example: SetInfo_DGW(hDGW,_MYFORM_0,DGW_EXT,"My new extension"); |
| list_resource | The name of the LIST resource for an LEDIT component. A LIST resource that matches this name must be defined in the same resource file. |
| ret_value | The value that is returned when a button is pressed. |
| cancel | If the word "cancel" is specified, this button is treated as a cancel button and no validation of the dialog box is performed. Pressing a cancel button is equivalent to pressing the <esc> key. |
| help_resource | Defines the name of the HELP Resource to display when a help button is selected. |
FEDIT
There are two types of FEDIT components: those that create lists of already existing files, and those that are to specify new files. The type is specified using the OLD or NEW validation string. If NEW is specified, and the file already exists, the validation ensures that the user is prompted to verify whether the file is to be overwritten:
FEDIT,,,40,"Create a New File" ,R,NEW,,,*.dat FEDIT,,,40,"Symbol Font Name",R,OLD,symbols,~,*.gfn FEDIT,,,30,"Grid name",R,OLD,,,*.grd
In the second example, files of type “.gfn” in the user’s Geosoft directory will be displayed, and the symbols.gfn file will be selected by default, if no previous font file has been selected in this field.
In the third example, the presence of the “*.grd” alerts the resource compiler to the fact that grid files are requested, and the special grid file browser is invoked when the “...” browse button is selected beside this field. This grid browser automatically appends to the grid name the file decorations specific to the chosen grid type required to correctly interpret the grid.
EDIT
The EDIT components may be used in four basic ways: to handle strings, integers and real values, and to display a text label in a shaded window as a read-only field:
EDIT ,,,30,"A Real value",,REAL EDIT ,,,30,"An Int value",R,INT,10 EDIT ,,,30,"A String value",R EDIT ,,,30,"Channel Name",N
In the first example, no input is required, but if it is, it must be a valid floating-point number. In the second example, an integer value is required, and 10 will be offered as default if no value is passed into the GX for this field. The third example requires the user to enter any string value. The fourth example is for printing out a channel name (for example); the user cannot change this value; the programmer determines it in the source code.
CEDIT
The CEDIT components are used to specify colours for coloured entities such as symbols, symbol fills, and lines. In the dialog, the edit window will be painted with the currently selected colour, and when the user clicks on the window the colour selection tool comes up so the user can select a different colour. The following are examples of the use of the CEDIT component:
CEDIT ,,,30,"Line colour","K" CEDIT ,,,30,"Line colour #2","R128" CEDIT ,,,30,"Line colour"
The last (optional) field is the default colour string. Colour strings take the form “R#G#B#, where # is a value from 0 to 255, giving the intensity of the Red, Green or Blue colour. Black can be expressed in a number of ways, including “K”, “R0” or “R0G0B0”. (Colours not included are assumed to be at zero intensity.) Letters given without numeric qualifiers are assumed to be at full intensity; for instance white can be written as “R255G255B255” or “RGB”.The default colour (third example above) is black “K”. In addition, you can use “N” (None) to indicate no colour, which is the same as transparent –for instance for fill colours in symbols – as well as “C” (Cyan), “Y” (Yellow), and “M” (Magenta).
LEDIT
The LEDIT component is a drop-down box containing a group of selectable parameters, such as channel names. It is used to allow the user to select an option from a predefined list, specified in a LIST resource. When you select an item, it replaces any existing text in the field. If the validation parameter of FORCE is specified then only list items can be selected. otherwise the user can enter a new value.
The contents of the list are defined as the list resource in the Resource file, or they can be defined at run time using the GetList_DGW method to the get the LIST object (see example below).
LEDIT,,,20,"Plot sizes?",R,FORCE,"Yes",YesNo LEDIT,,,20,"Sizes",R,FORCE,"Large",SIZE LEDIT,,,20,"Channel",,FORCE,,CHAN // The contents of this list will be provided in code. RESOURCE,LIST,CHAN RESOURCE,LIST,YesNo ITEM, Yes,1 ITEM, No,0 RESOURCE,LIST,SIZE ITEM, Small ITEM, Medium ITEM, Large
In the following GXC code example a LIST resource is filled with a sorted list of channels. If you omit the Sort_LST command the channels will be listed in the order they were created. In this case, the “_MYFORM_3” parameter indicates that the LEDIT component referenced is the fourth component (because indexing begins at 0) in the FORM resource whose resource_name is “MYFORM”.
// --- Set up lists --- List = GetList_DGW(hDGW,_MYFORM_3); // retrieve list from dialog SymbLST_DB(Data,List,DB_SYMB_CHAN); // fill the list from the database Sort_LST(List,0,0); // sort the list alphabetically
BUTTONS
There are 2 types of buttons which can be included on your form. The EBUT component is used to create a clickable button with a caption, while the HBUT component is used to link a HELP resource to the form. The presence of a HELP resource is indicated by a clickable question mark button on the top right of the dialog and will also be activated if the user presses F1.
EBUT,&OK,0 EBUT,&Cancel,1,CANCEL HBUT,&Help,help // In this example from BASEMAP2.GRC, a wizard-type dialog is simulated by using <Back and Next> buttons EBUT,<&Back,0 EBUT,&Next>~,1 EBUT,&Cancel,-1,cancel HBUT,&Help,maphelp
Different return results can be used within a switch statement for more complicated program flow as shown in the following excerpt from DELLINES.GXC.
// --- Are we running interactively ? ---
if (iInteractive_SYS()) {
i = 0;
while (i != 99) switch (i) {
case 0: // --- delete option ---
Diag = Create_DGW("DELLINES0");
SetInfoSYS_DGW(Diag,_DELLINES0_0,DGW_LISTALIAS,"DELLINES","OPTION");
i = iRunDialogue_DGW(Diag);
if (i == -1) Cancel_SYS();
GetInfoSYS_DGW(Diag,_DELLINES0_0,DGW_LISTALIAS,"DELLINES","OPTION");
Destroy_DGW(Diag);
iOpt = iGetInt_SYS("DELLINES","OPTION");
if (iOpt == 1) {
if (iDisplayQuestion_SYS(_("Delete all selected lines/groups."),_("Confirm that you want to delete ALL selected lines and groups.")))
i = 99;
else
i = 0;
} else if (iOpt == 0)
i = 99;
else if (iOpt == 2)
I= 1;
else {
DisplayMessage_SYS(_("Lost"),_("I'm lost"));
i = 0;
}
break;
case 1:// --- select a line to delete ---
Diag = Create_DGW("DELLINES1");
List = GetList_DGW(Diag,_DELLINES1_0);
SymbLST_DB(Data,List,DB_SYMB_LINE);
SetInfoSYS_DGW(Diag,_DELLINES1_0,DGW_TEXT,"DELLINES","LINE");
i = iRunDialogue_DGW(Diag);
if (i == -1) Cancel_SYS();
GetInfoSYS_DGW(Diag,_DELLINES1_0,DGW_TEXT,"DELLINES","LINE");
Destroy_DGW(Diag);
break;
}
}
LIST Resource
A LIST resource is a drop-down box containing a group of selectable parameters, such as channel names or a fixed set of options. The contents of the list can be defined as part of the list resource in the Resource file, or they can be defined at run time using the GetList_DGW method to the get the LIST object and then set items in the list (see example below).
If there is a list available for the selected field, you see a drop down list box containing items with a down arrow to the left of the box.
When you select an item, it replaces any existing text in the field.
LIST Syntax
RESOURCE, LIST, resource_name
Parameter | Purpose and/or Allowed Values |
|---|---|
resource_name | name of the LIST, which is used to reference this list in FORM components. |
LIST Components
Individual items in the dropdown LIST resource are specified using the ITEM component. The items appear immediately following the LIST resource, one item per line.
ITEM,item_name{,alias}
Parameter | Purpose and/or Allowed Values |
|---|---|
item_name | Identifies the list item displayed to the user. |
alias | Indicates the corresponding alias value actually passed back and forth from the dialog. If no alias is defined, the item_name is used. |
The following is an example of an LEDIT component, with a list whose items are defined inside the resource file:
LEDIT,,,20,"Plot sizes?",R,FORCE,"Yes",YesNo LEDIT,,,20,"Sizes",R,FORCE,"Large",SIZE RESOURCE,LIST,YesNo ITEM, Yes,1 ITEM, No,0 RESOURCE,LIST,SIZE ITEM, Small ITEM, Medium ITEM, Large
The “R” parameter in the LEDIT components ensures that the user must enter a result in the field, and the “FORCE” parameter ensures that the entered text is one of the menu items.
The following is a commonly found example of an LEDIT component where the resource items are not defined in the resource file:
LEDIT,,,20,"Channel",,FORCE,,CHAN RESOURCE,LIST,CHAN
This creates an empty list resource named "CHAN" that will be populated by the GX at run-time. In this example, the CHAN resource will be populated by a list of channels in the current database using GX code similar to the following:
// --- Set up lists --- List = GetList_DGW(hDGW,_MYFORM_3); // retrieve list from dialog SymbLST_DB(Data,List,DB_SYMB_CHAN); // fill the list from the database Sort_LST(List,0,0); // sort the list alphabetically
In this example, the “_MYFORM_3” parameter indicates that the LEDIT component referenced is the fourth component (component indexing begins at 0) in the FORM resource whose resource_name is “MYFORM”.
HELP Resource
Help resources are used to provide the user with context sensitive help about how to use your GX, or specifically how to use the dialog that is displayed. The HBUT button on a FORM (Dialog) resource requires a HELP resource. The HELP resource is displayed when the user presses the [Help] button.
Help information itself can be provided as a simple text file, an RTF (Rich Text Format) file, or you can use Compile HTML help (.CHM) file. In the first 2 cases the file will be stored within the gx itself and displayed in an external viewer when required. When utilizing a CHM file the process is described below.
RESOURCE,FORM,Dialog,"My dialog has 3 help buttons",-1 HBUT,"Help me",help1 HBUT,"More help",help2 HBUT,"&Even more help",help3 RESOURCE,HELP,help1,simple_help.txt RESOURCE,HELP,help2,more_help.rtf RESOURCE,HELP,help3,Even_more_help.chm
In the above example help3 is the Topic ID that will be referenced in Even_more_help.chm. An initialization file (.ini) is then created linking the Topic ID's in the grc file with the embedded htm(l) files within the CHM help. In the above example the INI file might be:
Even_more_help.ini
[GXHELP] help3="Even_more_help.chm:E_M_Help.htm"
Depending on how the chm file was created there are various methods of determining the name of the help file, however you can always retrieve it by right clicking on the topic after launching the file in the windows help viewer.
The CHM file has to be placed in the resourcefiles\hlp directory, and the inititalization file belongs in the resourcefiles\spec\ini directory.
Using WinHelp or Compile HTML (*.CHM) Help Files
You can also use a WinHelp (*.HLP) or Compile HTML (*.CHM) help system files to provide help information to any GX you create. The following section outlines the steps you need to follow to do link a WinHelp/Compile HTML help system to a GX.
Linking WinHelp or Compile HTML help to Oasis montaj GXs
This tutorial uses a number of sample files that are installed with your GX Developer installation. The following files will be copied to a gx\examples\winhelp subdirectory located within your GX Developer directory:
myhelp.ini This INI file is used to map the GX Topic ID to the help file.
myhelpgx.gx This is a sample GX with a dialog box containing two help buttons.
myhelpgx.grc This is the grc file for the sample GX myhelpgx.gx
myhelpgx.gxc This is the gxc file for the sample GX myhelpgx.gx
myhelpfile.hlp This is a sample WinHelp file with only two help topics, one for each help button on the GX dialog.
brokenlink.hlp This help file is displayed if the link is broken.
Step 1 – The GRC File
The .grc file contains the help resource information for the GX. In this example, the GX has a dialog box that contains two help buttons.
// // MyHelpGx.GRC //----------------------------------------------------------------------------- RESOURCE,FORM,MyHelpForm,"GX to test Winhelp Topics",-1 EDIT,,,16,"Bogus Edit Box",, EBUT,&OK,0 EBUT,&Cancel,1,CANCEL HBUT,&HelpTopic1,MyHelpTopicLink1 HBUT,&HelpTopic2,MyHelpTopicLink2 RESOURCE,LIST,CHAN RESOURCE,HELP,MyHelpTopicLink1,BrokenLink.hlp RESOURCE,HELP,MyHelpTopicLink2,BrokenLink.hlp
Parts of the GRC File
The help buttons are defined in the HBUT lines:
HBUT,&HelpTopic1,MyHelpTopicLink1
HBUT,&HelpTopic2, MyHelpTopicLink2
The &HelpTopic2text is the title text on the help button.
The MyHelpTopicLink2 text is a link ID (or help resource). This ID is used in the myhelp.ini file to link to the real help Topic ID in the myhelp.hlp file (this is explained more in the next step).
Broken Links
The RESOURCE lines specify a file that is displayed if a user clicks on the help button and the link to your Winhelp topic is broken for any reason.
In this example, a broken link would display the brokenlink.hlp file. You can also specify a text file (brokenlink.txt) or an RTF file (brokenlink.rtf).
You should compose a message that tells your users what to do should when they find a broken link (contact you, for example). You can place this file in the gx\include directory so it can be shared by all your GXs. Geosoft uses a file named “nogx.hlp” exactly for this purpose (please do not use this file since it asks your users to contact Geosoft).
Step 2 – The myhelp.ini file (Mapping File)
The next step is to create a mapping file that Oasis montaj will use to link the link ID to a Topic ID in a specific WinHelp (*.hlp) or Compile HTML Help (*.chm) file.
In this example, we created a mapping file called myhelp.ini that contains the following text:
[GXHELP] MyHelpTopicLink1="MyHelpFile.hlp:MyHelpTopic1" MyHelpTopicLink2="MyHelpFile.chm:MyHelpTopic2.htm"
What each line means:
The first line in the file [GXHELP] identifies that this is a mapping file used to provide GX help.
The following two lines consist of three parts, illustrating WinHelp (*.hlp) and Compile HTML Help (*.chm) files.
WinHelp Example
MyHelpTopicLink1="MyHelpFile.hlp:MyHelpTopic1"
MyHelpTopicLink1 is the Link ID for the first button as indicated in the myhelp.grc file.
MyHelpFile.hlp or indicates the WinHelp file to look in for this information.
MyHelpTopic1 is the Topic ID associated with the topic text in the WinHelp file.
Compile Help (*.chm) Example
MyHelpTopicLink2="MyHelpFile.chm:MyHelpTopic2.htm"
MyHelpTopicLink2 is the Link ID for the first button as indicated in the myhelp.grc file.
MyHelpFile.chm or indicates the Compiled Help file to look in for this information.
MyHelpTopic2.htm is the HTM file associated with the topic text in the Compile Help file. To determine the individual HTML files contained within a Compile Help file, use the following command:
hh.exe "decompile extracted GridAnalysisHelp.chm
What are Topic IDs?
Each topic in a WinHelp file has a unique Topic ID. Topic ID names should not have any spaces in them. A Topic ID is not the same as a Topic name. A Topic Name is only the title text of the topic.
Tip: At Geosoft, to make things easier, we usually use a topic ID that is derived from or similar to the name of the GX. For example, the ARROW GX topic in the help system would have a topic ID called ARROW_GX.
Step 3 – Create a Custom Winhelp File
If you haven’t already done so, you will now need to create your custom WinHelp file (Myhelp.hlp) using a help authoring software program (at Geosoft we use Robohelp).
Add custom Help INI to Oasis montaj
Before you can use your custom GX help file, you will have to tell Oasis montaj to use the custom .ini file you created. This will let Oasis montaj know which mapping files to check for links.
Simply, your custom .ini file needs to be placed into the spec\ini subdirectory in an Oasis montaj installation. This spec directory resides on the same level as bin, gx, and hlp.
Any number of files can be placed into this directory. With this modification, Oasis montaj will now search the spec\ini directory and load each file when it looks for a help topic to link to.
Step 4 – Copy the Files and Restart Oasis montaj
If you are using Oasis montaj, you should copy any help files you create to the hlp sub-directory, any INI files to the spec\ini sub-directory, and GXs to the gx sub-directory where your Oasis montaj is installed.
Whenever you change an INI or HLP file that Oasis montaj uses, you need to restart the software to have the changes take effect.
Final Note: The instructions in this note only apply to linking help from a GX. If you want to link help file topics to custom GUI (graphic user interface) objects or to dialogs created using visual basic, you will need to create a .hh mapping file and link them using a different method.