GRC Resources and Dialogs

GX Developer Resources describe the visual elements of a GX, specifically the user-interface dialog windows. If your GX will present a dialog to the user to obtain information from the user, you will use a resource to define elements on the dialog.

A Geosoft Resource file (GRC) contains dialog resource definitions and resource components. The Geosoft Resource Compiler grc.exe (C:\Program Files (x86)\Geosoft\GX Developer\gx\bin\grc.exe) compiles a Resource file to produce a Geosoft Resource (GR) file and a Geosoft Resource Header (GRH) file. The resource header file is included in the corresponding GXC source code file (using the #include Pre-processor directive), which supports access and interaction with components of the dialog from the the GXC source file. When the GXC source file is compiled to create the final GX, the GXC compiler (gxc.exe) incorporates the compiled resources (.gr) into the final GX.

Resources in the GRC source file are described with a RESOURCE line, which includes the resource type, name and parameters, followed by resource components specific to the resource. The basic syntax of all lines in a GXC resource file is:

keyword,parameter,parameter,...

This section documents the resources, which include the FORM resource, the LIST resource and the HELP resource. Parameters in resource and component definitions are comma-delimited, and items in {braces} are optional. The resource compiler ignores blank lines and lines that begin with “//” characters.

For example, following is a resource file that defines a simple dialog:

// 
// DIFF.GRC
//-----------------------------------------------------------------------------
RESOURCE,FORM,DiffForm,"Calculate differences",-1
LEDIT,,,16,"Channel to difference",R,FORCE,,CHAN
LEDIT,,,16,"Output difference channel",R,,,CHAN
EDIT,,,16,"Number of differences (>=1)",R,INT
LEDIT,,,16,"Normalize differences?",R,FORCE,no,NORM
EBUT,&OK,0
EBUT,&Cancel,1,CANCEL
HBUT,&Help,help

RESOURCE,LIST,CHAN

RESOURCE,LIST,NORM
ITEM,"No"
ITEM,"Yes"

RESOURCE,HELP,help,diff.rtf

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. The title can be changed by a GXC file using the SetTitle_DGW() method: 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.

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:

..\\resourcefiles\\spec\\ini
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

[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

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.