CurFld

From Br Wiki
Jump to: navigation, search

The CurFld internal function has 4 possible combinations of syntax:

CURFLD
 
CURFLD ([<New_current_field>] [,<attribute$>] [,FKEY])

CurFld ([<New_current_field>] [,<New_current_row>]) ! if the new current field is a ListView

CurFld ([<New_current_field>] [,<New_current_cell>])! if the new current field is a Grid

When used without parameters, CurFld function returns the number of the field containing the cursor from the last INPUT FIELDS. With parameters, CurFld can be used to set a new starting field (same as the C control attribute) and/or set a new attribute for the starting field. CurFld may also be used to set the cursor to a cell of a grid or a row in a ListView.

In other words, there are three uses for CURFLD:

  1. CURFLD, without parameters, returns the relative position of the last control (field) occupied during an INPUT operation.
  2. CURFLD(nn) returns the subscript of the current item within the 2D control (LIST or GRID) at relative position nn.
  3. CURFLD(nn,yy) positions the cursor at field yy in 2D control nn when the next INPUT operation is commenced. For LISTs, yy is a row value. For GRIDs it is a cell subscript value.

And, if the control being referenced by nn is not a 2D control, the following parameters are applied during the next INPUT operation-

  1. The relative field number.
  2. Optional additional field attributes.
  3. Optional FKEY value (e.g. right arrow) to be applied for cursor positioning before processing the INPUT.

Comments and Examples

00100 DIM SF$(3)
00110 LET SF$(1)="10,30,c 10,r"
00120 LET SF$(2)="12,30,c 10,r"
00130 LET SF$(3)="14,30,c 10,r"
00140 INPUT FIELDS MAT SF$: A$, B$, C$
00150 PRINT "Cursor ended on FIELD"; CURFLD
00160 PRINT "Cursor ended on ROW"; CURROW
00170 PRINT "Cursor ended on COLUMN"; CURCOL

In the sample program above, the there are three fields available for input. The operator can move the cursor in any direction, but only within these three fields. After the operator hits the <ENTER> key, line 150 will print the number 1, 2 or 3 depending on which field the operator left the cursor on. In addition, line 160 will print the row number (10, 12, or 14) containing the cursor when input was ended. Also, line 130 will print the column number (30 through 39).

Some programmers prefer to do screen input with only one field at a time. In these cases, CURFLD will always be 1 because only one field is used. CURFLD provides valuable information when several fields are entered in one statement through an array, specifically, when INPUT FIELDS, RINPUT FIELDS, INPUT SELECT, or RINPUT SELECT is used with an Array.

As CURFLD returns the subscript in the field definition array of the field containing the cursor from the last INPUT FIELDS, RINPUT FIELDS, INPUT SELECT, or RINPUT SELECT, CURFLD can be especially useful with the on-line help facility. By using CURFLD in the HELP$ function in line 990 for the value of the "mark", the operator can be directed to the most relevant portion of the text under the topic HOURS.ENTRY in the help file that explains the valid entries for that field. For example:

00810 INPUT FIELDS MAT FLD$: HRS,OT,DT,SICK HELP 90
00820 STOP
00990 HELP$("HOURS.ENTRY", CURFLD) : RETRY

The use of CURFLD with parameters is primarily designed for easy error processing. In the following example, CURFLD returns the cursor to the error-causing field and reverses the field for greater visibility. NOTE that this use of CURFLD takes affect only for execution of the next INPUT FIELDS, RINPUT FIELDS, INPUT SELECT, or RINPUT SELECT statement.

00010 INPUT FIELDS MAT A$: MAT A CONV 30
00020 IF A(2)>10 THEN LET CURFLD(2,"R") : GOTO 10
00030 STOP
00040 LET CURFLD("R")
00050 RETRY

FKEY Parameter

CurFld has been extended to allow an additional numeric parameter, an FKey value, that causes FIELDS and SELECT statements to execute the specified keystroke before requesting operator input. CURFLD ignores FKEY values of 100 or less and of 114 or greater. The following code uses CURFLD and FKEY to trap the operator's field exit keystroke and execute it after verifying the data just entered. NOTE that the AE control attributes are used to interrupt execution of the INPUT FIELDS statement upon field exit.

00010 PRINT NEWPAGE
00020 INPUT FIELDS "10,10,C 10,AEU:R;11,10,C10,U": X$,Y$ HELP 41
00030 IF CURFLD=1 THEN PRINT FIELDS "10,22,C": X$
00040 IF FKEY>100 THEN LET CURFLD(CURFLD,FKEY) : GOTO 20
00041 PRINT FKEY
00050 STOP

As soon as the operator attempts to exit the first input field, line 30 verifies the entered data by redisplaying it to the right of the field. The CURFLD function in line 40 is then used to reenact the operator's field exit operation: the field just verified is set to the current field, and the operator's attempted exit keystroke (the value of FKEY) is executed. Operator input is then allowed for the next field.

NOTE: If the up arrow was the last key used, the cursor will return to the previous field. If the tab key was used, the cursor will position to the next field with a T (tab stop) attribute.

NOTE that the CURFLD function in line 40 is executed only if the value of FKEY is greater than 100. Values of 100 or less are ignored, as are interpreted as an attempt to enter the entire screen.

CURFLD will now process field control attributes such as AEP and #. These control attributes will be ADDED to the control attributes that are specified for a field. Also, the attributes that are specified with CURFLD will OVERRIDE (be used instead of) a floating attribute specified with ATTR. The CURFLD attributes will remain in effect only during the next execution of an INPUT FIELDS or INPUT SELECT statement. Line 20 in the following example uses the X control attribute (see the "X control attribute" discussion in the BRConfig.sys Specifications section for more information).

00010 INPUT FIELDS "10,10,V 10,U;11,10,V 10,U;12,10,V 10,U",attr "HU":X$,Y$,Z$
00020 IF X$="" THEN LET CURFLD(1,"RX") : GOTO 10
00030 !.. other editing
00040 IF FKEY>100 THEN LET CURFLD(CURFLD,FKEY) : GOTO 10
00050 !.. output

If the first field displayed by the above code is left blank, the CURFLD function in line 20 will reposition the cursor to that field and display it in reverse video. The CURFLD function's X attribute will additionally cause an auto-enter to occur when the operator attempts to re-exit the field. If the field passes the test on line 20, and the enter key or a function key was not pressed, the field attribute will resume as an underline and the cursor will be positioned at the next field the operator was trying to move to.

ADS expects that line 40 will become a standard line of code in all programs that use input fields and validate data.

Previously, the CurFld statement supported 3 parameters:

  1. The relative field number.
  2. Optional additional field attributes.
  3. An optional FKEY value to be applied for cursor positioning before processing the INPUT.

In the event the first parameter points to a 2D field/control then instead of the FKEY value, the third (or second numeric) parameter is interpreted as the subscript of the item within the 2D control. For LISTs, this is a row value. For GRIDs this is a Cell Subscript Value. For TOOLBARs, it is the icon subscript value (relative position in toolbar).

Also, in the event the first parameter points to a 2D field/control then the CURFLD function returns the subscript of the current item within the 2D control.

The CURFLD system function has been extended to support the current selection upon entry to a multi-field control. The first parameter specifies which field/control is to be affected and the second parameter is the subscript of the cursor upon entry to that control. In the event the first parameter points to a 2D field/control then instead of the FKEY value, the third (or second numeric) parameter is interpreted as the subscript of the item within the 2D control.

|For LISTviews this is a row value.
|For GRIDs this is a Cell Subscript Value.
|For TOOLBARs it is the icon subscript value (relative position in toolbar).
Note that CURFLD with 2 parameters does not set the initial position of the cursor until the respective control is entered. Also if the mouse is used to enter a control, that will override the specified CURFLD value.

Option 43 Use old style Input Select with respect to setting CURFLD to the NXTFLD value when a selection is made.

Technical Considerations

Note that before BR 4.2, CURFLD could be used with RINPUT FIELDS, INPUT SELECT, or RINPUT SELECT. But as of 4.2, it is limited to INPUT FIELDS.

CurFld is initialized to -1 at the start of a new program by the RUN command.

Related Functions

CURROW and CURCOL return the row and column numbers of the last INPUT FIELDS, RINPUT FIELDS, INPUT SELECT, or RINPUT SELECT statement.