Field Help

From BR Wiki
Jump to navigation Jump to search

For disambiguation purposes, see also BRConfig.sys FieldHelp

The "Field help specifications" portion of the full screen processing syntax identifies the user level, window placement, and text that is to be displayed in field help windows.

It can also be used with print fields statements, for example, with buttons.

Comments and Examples

The border type and attributes for field help windows may be specified by the BRConfig.sys FIELDHELP specification. The border types which are available for field help windows are the same as the border types which are available for regular windows.

The following helpstring specification provides no field help text for the first through fourth fields. The fifth field has a 3 x 16 window that displays if USERLEVEL is set to either 2 or 3. Default positioning (to the right of the field if possible) is used for window placement.

00300 RINPUT FIELDS MAT FIELD$, HELP "XXXX2;Pay Frequencies: \n W - Weekly\n B - Biweekly;":MAT RECORD$

The next example provides field help text that is identical for the second and third fields. The field help window is displayed below the field if possible (Business Rules will override the specification and find a position that does work if below is not possible). NOTE that the specifications for the first and second fields use @ as the separation character, but the specification for the third field-which utilizes backwards referencing for the display of identical text -ends with a semi-colon.

00550 INPUT FIELDS MAT FIELD$, HELP "1B@Non-standard separation\ncharacter@1B@Normal is ;@&2;": MAT RECORD$
  

Through the use of the "int" parameter, which identifies the number of an open window, the text which is specified for a field help window may be sent to an open window instead. In the following example, "3" identifies the user level for which the help text should automatically be displayed, and "7" indicates that the field help text, "This text...," is to be displayed in open window #7.

00350 INPUT FIELDS "10,10,C 20,UAE",HELP "37;This text would be displayed in window-num 7;": SAMPLE

Helpstring Syntax

"{{1|2|3} {A|B|L|R|<integer>}[<|>] <separator> <text> <separator> |X|&<Field Num>;}[,...]" 

Supplemental Syntax ("helpstring" parameter)

The above syntax may be inserted where the "helpstring" parameter appears in the main diagram for full screen processing statements. If the "string-expr" or "MAT string-array" parameters are used to specify field help text, each must include the same elements that are identified in the "helpstring" specification. Business Rules assumes that multiple field help specifications will be identified in the same field order which is indicated in the field definition string.

The "1", "2","3", and "4" HELPLEVEL parameters denote the user level for which the field should be automatically displayed. (This option works in conjunction with the WBConfig.sys file's USERLEVEL specification.)

  • "1" indicates that the information provided in this field help text is very important and it should be automatically displayed to most users -even those who are experienced.
  • "2" indicates that the information should be automatically displayed to anybody who is at an intermediate level (or less) of experience with the software.
  • "3" indicates that the information should be automatically displayed only to novice users of the software.
  • "4" supports windows tooltips, but suppresses field help windows entirely (4.2). This is the recommended setting.

Automatic display of all field help text, regardless of the user level specified here, can be turned off when the WBConfig.sys file's USERLEVEL specification is set to 0. Field help text remains available to all users, even if it isn't automatically displayed to them, when they press the <HELP> key. (Pressing <HELP> a second time initiates regular help processing.)

The next block of parameters identifies the placement of the window that is to display the field help text. The letter parameters specify the following:

  • "A" is above the field,
  • "B" is below the field,
  • "L" is to the left of the field, and
  • "R" is to the right of the field.

A greater-than (>) or less-than (<) sign may be specified along with either A or B. Greater-than (points to the right) specifies that the window is to be placed flush right with the field. Less-than (points to the left) specifies flush left placement. When neither sign is specified, the window is centered above or below the field. Business Rules always attempt to use the specified placement instructions. However, if the amount of room on the screen does not permit honoring this specification, default placement will occur.

The "int" parameter may also be used to identify window position. It allows field help windows to directly interact with I/O windows. "Int" represents an integer from 1 to 999 (inclusive) that identifies the number of an open window file. It causes the field help text to be sent to a window which is already displayed on the screen. If the number specified is not a valid window file, default field help window placement will occur. Use of the "int" parameter can result in two major screen optimizations:

a) it significantly reduces the number of times that the screen is repainted (rather than displaying a different window for each field, Business Rules just displays the open window),
b) it causes Business Rules to rewrite the contents of the window only when necessary (thus when the cursor moves between two fields with the same help text, no rewrite occurs).

Int is particularly desirable for Unix / Linux terminals, especially when large amounts of text are being repeatedly displayed.

The "sep" parameter represents a non-numeric and non- alphabetic character that will be used as a separator. The character, which is used, may not appear within the help text. ADS recommends the use of a semi-colon (;) for this separator if it is not required in the text. The same character which is used as the "sep" before the text must also be specified as the "sep" after the text.

The "text" parameter represents the field help information that is to be displayed to the user. Business Rules automatically determines the width and height of the window according to the width of the lines and the number of rows of text, which are specified for this parameter. The new-line character (CHR$(10)) or a backslash and lowercase n (\n) may be used to indicate the start of a new line of text. The maximum line length for field help text is 78 characters. An error will occur when lines longer than this are specified. Although Business Rules displays up to 1000 characters of text in a field help window, 100 characters should be considered a more practical limit.

The "X" parameter denotes a field for which there is to be no help text. It may be repeated as many times as are necessary. If you wish to provide help text for only the fourth field, you would begin the helpstring specification with "XXX" to denote that there is no field help for the first three fields.

The "field-num" parameter may be used to specify the same text that has already been identified for an earlier field. Only backward references are allowed. "Field-num" represents the number of the field for which text has already been specified; it must be preceded by an ampersand (&) and followed by a semi- colon (;).

Defaults

1.) Center window above field.
2.) R if possible; attempt B, L, then A if necessary.

Technical Considerations

1.)There may be more or fewer fields identified in the helpstring than there are defined in the full screen processing statement.