FORM "<genie>"[,"<form title>"]; 

<field number>:"<field name>", <field size> [,readonly/readwrite[, "<list form>", "<list field>"[,"<list filter>"]]]; ...

NORMAL 

"<prompt> {<field number> }

..."

...

The format of the genie form file follows closely that of the CITECT.FRM file. Each genie form definition is denoted by the keyword FORM. This is followed by the name of the genie as specified in the genie library. For example, if you were writing a form definition for the genie 'Training.Sample', the form file would be "Training.FRM" and the genie name would be "Sample". A title can be provided for the genie form. If none is provided the genie name is used.

A record definition must be provided. It consists of a field number, field name and fields size. Each field is linked to the genie by its 'field name'. The field name should match up the substitution string(s) used in the genie. For example if you used %Tag% as a genie substitution string, then Tag would be the field name in the record definition. Any values entered into the Tag field through the form would be expanded out into the genie substitution string %Tag%. The field numbers must be start at 1 and increase conescutively.

You can also add extra fields that do not have a corresponding substitution string. Information entered into these fields will be stored but will not be expanded into any other fields.

The 'readonly', 'readwrite' keywords have no effect on the form but exists to maintain compatible with the CITECT.FRM structure. If not provided the field defaults to readwrite.

A 'list' can be specified for each field. This list appears in a drop down combo box on the form. The 'list form' and 'list field' specify which field of which form to source the contents of the list from. For example if you wanted to list the name from each record in the Variable Tags database you would enter "Variable Tags" and "NAME" for the form and list.

A 'list filter' can be specified with the format 

"<field>=<filtertext>"

For example, this can be used to only list tags that are of a specific data type.  It is also useful for genies that use structured tag names.

<field> is the field name to filter by.  This defaults to the field name specified as the 'list field', so <field>= can be omitted.

 <filtertext> is the text to search for in that field.  Only records that have the specified filter text in the specified field will be added to the drop-down list.

An * may be used as a wildcard.  e.g. Using "*_PV" as the 'list filter' would only add records that end in _PV, and the _PV would be omitted from the name. This would cause tags such as "Loop1_PV" to appear in the list as "Loop1" and tags that don't end in _PV would not be listed. Multiple list filters may be specified between the quotation marks as long as the filters are separated by commas.

Any of the forms defined in CITECT.FRM can be used as a 'list form'. If a form from CITECT.FRM is used as 'list form' then 'list field' can be any of the fields from the forms record definition. For example if 'Keyboard Keys' is used as 'list form' then 'NAME', 'CODE', 'ECHO', 'KYBD_TYPE" or 'COMMENT' could be used for 'list field'. The value from the field specified by 'list field' will be taken from each record in the database file (keys.dbf for Keyboard Keys) and added to the list.

The keyword 'HELP' can also be specified as the 'list form'. If HELP is specified then the 'list field' can be any of the values from the field 'TYPE' in HELP.DBF (found in the \CITECT\BIN directory). The value from the 'DATA' field for each record whose 'TYPE' matches 'list field' will be used to construct the list. For example if 'BOOLEAN' was specified as the 'list field' then the list would contain 'TRUE' and 'FALSE'. The 'list filter' is not supported by genie form files.

It should be noted that any records the user adds to HELP.DBF will be lost the next time they re-install Citect for Windows.

The form definition is specified after the record definition. The form definition consists of the keyword NORMAL followed by a string that describes the form. The string describes prompts and fields. A prompt is copied character for character across to the form. Any carriage returns (new lines) are copied across to the form. Fields are indicated by a field number enclosed in brackets. The number of characters separating the brackets (including the field number digits) determines the size of the edit control on the form. The substitution string for this field is determined by the field name of the field with this field number. The prompt does not need to be same as the field name.

EXTENDED forms are not supported by genie form files.

An example form definition for Sample is shown below.

! Sample genie form

! This form will prompt for three tags, a Cicode function name, and a comment

! The first tag's drop down list will list the base tag name for any tags that end in _PV

! The second tag's drop down list will list the base tag name for any tags that end in _CMD and have the data type DIGITAL

! The third tag's drop down list will list all variable tag names

! The Function name drop down list will list all Cicode function names that are in Citect\Bin\Help.dbf

! The comment field simply allows you to enter a text comment

!

FORM "Sample", "Sample Genie Form";

1: "BaseTag1", 16, readwrite, "Variable Tags", "NAME", "*_PV";

2: "BaseTag2", 16, readwrite, "Variable Tags", "NAME", "*_CMD,TYPE=DIGITAL";

3: "Tag1", 16, readwrite, "Variable Tags", "NAME";

4: "Name", 16, readwrite, "HELP", "FUNCTION";

5: "Comment", 32, readwrite;

NORMAL

"Base Tag Name 1 {1 }

Base Tag Name 2 {2 }

Tag Name 3 {3 }

Function {4 }

Comment {5 }"

! Insert_Object genie form

! This form uses special 'list form', 'list field', and 'list filter' names

! to create a drop-down list of ActiveX object names

! This feature is available in Citect 5.20 and later

!

FORM "Insert_Object", "Genie - Insert Object";

1: "GUID", 128, readwrite, "<<", "ListActiveXControls","0";

2: "EVENTCLASS", 128, readwrite;

3: "W", 4, readwrite;

4: "H", 4, readwrite;

NORMAL

"Object {1 }

Event Class{2 }

Width {3 } Height {4 }"

For more examples look in the form files in the INCLUDE and EXAMPLE [aka DEMO] projects.

See Also: Q1765 Modifying Genie Form Files and Q3643 Creating Custom Dropdown Lists for Genie Forms