Screen Operations
Business Rules! advanced Screen Input/Output capabilities include many abilities:
- Print to and input from any position on the screen (full screen processing)
- Designation of one or more portions of the screen as its own mini-screen (windowing)
- Change the screen's display features through the use of screen attributes
Full Screen Processing
Full screen processing allows data entry controls on any position on the screen, specified by Row and Column. This contrasts with regular screen processing, which allows prompted data display and entry with PRINT, INPUT, LINPUT and RINPUT statements, but only allows access to the bottom line of the screen. (Lines in regular screen processing then scroll up until they scroll off the top of the screen.) With full screen processing, any position on the screen may be addressed directly.
- Besides allowing access to any position on the screen, full screen processing provides several additional advantages over regular screen processing
- Screens can be attractively designed, making programs look extremely professional to the end-user.
- Less code is required. One screen that fully utilizes Windows control attributes and displays ten prompts and ten input fields can be programmed in as few as two statements.
- The operation of the input screen can be controlled. Control attributes may be used to specify starting cursor positions, automatic entry of data, field protection and more.
Graphical Console
A separate command console handles the operator commands without interfering with the graphical console. Print newpage goes to the command console if at the command prompt, and to both in a program. Print anything else will only go to the command console.
The GUI console can be opened to other than 80 columns by 24 rows:
An OPEN window statement may specify a parent window number: George, Dallas, 42, 180
George, Peter, Tom
Version 4.14+ will no longer display fonts as bitmaps. It will, by using only native graphical controls, support proportional fonts and variable window sizes. Caution- You may need to make programming changes to utilize this version.
Two fonts are supported simultaneously, one for background and captions and one font for input fields.
General Coding Concepts
- Always Print Newpage Before Full Screen Processing
Business Rules! does not automatically clear the screen when full screen processing is used. The program must do this with PRINT NEWPAGE. Neglecting to clear the screen when changing to or from full screen processing may cause errors in the operators new entry as old information may become interspersed with new.
Multiple Field Processing
The full screen processing statements allow you to input and output multiple fields with a single statement. This can be accomplished in two main ways: with repetitions of individual parameters directly within the full screen processing statement; or with the use of array parameters which reference a string variable, coded elsewhere in the program, that includes all the information required for the various specifications.
In the following example, six fields are processed by each of two full screen-processing statements. In each case, all information required to process the multiple fields is included in the actual statement. In line 140, the field definitions and variable names are specified for six prompts. In line 150, the current values are output and the changed values (as updated by the operator) are input; this line also includes field help information for two of the six fields.
00120 DIM COMP$*25, STREET$*35, ADDR$*35, NAME$*20 00130 PRINT NEWPAGE 00140 PRINT FIELDS "6,11,c 20; 8,11,c 20; 10,11,c 20!:12,11,c 20; 14,11,c 20; 16,11,c 20" : PRID$, PRCOMP$,PRSTREET$, PRADDR$, PRNAME$, PRPHONE$ 00150 INPUT FIELDS "6,32,c 4,ra; 8,32,c 25,ra; 10,32,c 35,ra;12,32,c 35,ra; 14,32,c 20,ra; 16,32,c 12,ra",attr "R",help"XX2A<;Type in the street address.\nIf there is an apartment or suite number, \n type # and the number;2A<;Type in the full city name. \n Use the two-letter state code\n and the 9-digit zip code;": ID$, COMP$, STREET$, ADDR$, NAME$, PHONE$
One alternate way to code the above would be to place the field specifications and the field help window specifications each into their own array. The following code utilizes this technique but it operates exactly the same as the previous example. Line 220 prints the six prompts. Line 230 outputs the current values, accepts the updated values of the specified variables, and provides field help information on two of the six fields.
00110 DIM PROMPT$(6)*20, FLDDEF$(6)*16, DATADEF$(6)*15,FIELDHELP$*200 00120 DIM COMP$*25, STREET$*35, ADDR$*35, NAME$*20 00130 ! **** Operator Prompts For Prompt$ Array 00140 DATA ID number,Company Name,Street address,City/State/ Zip, Contact, Phone 00150 ! **** Field Definitions For Prompts (FLDDEF$) 00160 DATA "6,11,c 20","8,11,c 20","10,11,c 20","12,11,c 20","14,11,c 20","16,11,c 20" 00170 ! **** Field Definitions For Data Entry (DATADEF$) 00180 DATA "6,32,c 4,ra","8,32,c 25,ra","10,32,c 35,ra","12,32,c 35,ra","14,32,c 20,ra","16,32,c 12,ra" 00190 READ MAT PROMPT$, MAT FLDDEF$, MAT DATADEF$ 00200 LET FIELDHELP$="XX2A<;Type in the street address.\nIf there is an apartment or suite number,\ntype # and the number;2A<; Type in the full city name.\nUse the two-letter state code \n and the 9-digit zip code;" 00210 PRINT NEWPAGE 00220 PRINT FIELDS MAT FLDDEF$: MAT PROMPT$ 00230 RINPUT FIELDS MAT DATADEF$,ATTR "R", HELP FIELDHELP$: ID$, COMP$, STREET$, ADDR$, NAME$, PHONE$
There are a few important items to be aware of when specifying multiple fields in full screen processing statements.
- when a string array is specified for field definitions (as with FLDDEF$ in line 220 above), extra elements in the string array will be ignored. Thus, if FLDDEF$ contained seven field definitions instead of six, the seventh would be ignored.
- the order of definitions in an array determines the order of processing. The first element of the array corresponds to the first item to be processed, the second element of the array corresponds to the second item to be processed, and so on. The order of items in the field definition does not affect your accessibility to the screen; you may define fields from the bottom of the screen to the top or from the top to the bottom or in any other way you prefer.
- it is important to remember that fields should be referenced in a consistent order throughout the full screen processing statement. The order that fields are referenced in the field definition array should be the same order that they are referenced with field help and variable names specifications.
- string and numeric fields may be intermixed in any order as long as the field definitions match the corresponding variable type. For instance, in the following example, the first field definition identifies a string field that starts at row 3, column 5 and is 20 characters long. This field definition corresponds to the first variable (NAME$) in the I/O list. Likewise, the second field definition identifies a three-digit number which corresponds to the numeric AGE variable.
1000 INPUT FIELDS "3,5,C 20; 7,5,N 3" : NAME$, AGE
Windowing
One of Business Rules most powerful screen I/O capabilities is the ability to separate the screen into several mini screens, or I/O windows. These windows can do all the same things (including scroll) that the regular full screen can do. In addition, an I/O window may have a border and a caption in the top line of the border.
Open Display (Screen)
00410 OPEN #0: "Srow=nn, Scol=nn, Caption=APPLICATION NAME", DISPLAY, OUTPUT
-or-
00420 OPEN #0:"Srow=nn, Scol=nn, Caption=APPLICATION NAME, Buttonrows=nn",DISPLAY, OUTPUT
00420 Open #0: opens the main window, A number other than Zero opens a child window if "PARENT=XX" is included in the open string and XX refers to an existing open window number.
Opens a Windows window. Optionally sets the number of button rows (0-3). (Button rows are additional rows at the bottom of the screen that Business Rules can use for optional button placement.)
Display file OPEN file reference strings can contain COPIES=nn. The nn value will replace the new [COPIES] argument in SPOOLCMD.
Windows vs Field Help Windows
Although they share many similarities, Business Rules I/O windows and field help windows are specified in very different ways and they are used for very different purposes.
The primary difference is that Business Rules treats an I/O window as its own input/output file. Information may be sent to and received from it with statements such as PRINT, INPUT, LINPUT, and RINPUT.
In addition, information may be sent to and received from a window (as if it were the regular screen) by the full screen processing statements.
In contrast, input from and output to field help windows are not allowed. Field help windows and the text, which appears within them, are specified by the full screen processing statements; they are designed to help the end-user determine what to do for a particular field.
The following chart should help to clarify other similarities and differences between I/O windows and field help windows.
Border
Requires 4.16+
WINDOW BORDERS
BORDER= any valid border spec produces a single line border.
BORDER= NONE produces no border, same as not specifying a BORDER parameter at all.
Borders (Legacy)
Only supported in Business Rules! versions prior to 4
One of the greatest similarities between I/O windows and field help windows is in the types of borders that are available for each. For I/O windows, borders are specified with the OPEN window and PRINT BORDER statements. For field help windows, they are specified with the FieldHelp specification.
Each of these three specifications uses syntax, which is nearly identical, where the border type is concerned. Each has a "BORDER" keyword (in the case of OPEN window, its "BORDER=") followed by one of six options for specifying the border: "B" (blank), "D" (double-line), "H" (sHadow), "S" (single-line), "corners", and "8 chars".
The first four border options are predesigned. The following illustrations show examples of each. (Keep in mind that the attributes specified with a border provide hundreds of opportunities for variation.)
The last two border options allow you to custom-design your own borders. With the "corners" parameter, you can specify just the top left and bottom right characters (and let Business Rules fill in the rest). Or with the "8 chars" parameter you can specify eight characters that identify the corner and middle characters for every side of the border. The following illustration shows the sequence in which the eight characters must be specified:
1|2|3
8||4
7|6|5
The following example shows the use of the "8 chars" parameter with graphic drawing characters which may be toggled on for the 0-9 and period (.) keys by pressing Ctrl-\. This example creates the same border that is created by the S border type. It also includes the "r" attribute to reverse the border.
The next sample code shows some of the options that are available with borders for windows. A good way to see both windows and field help windows in action would be to type this code in and use the RUN STEP command to execute it.
00005 PRINT NEWPAGE 00007 DIM FIELDHELP$*50, NULL$*50 00009 EXECUTE "config fieldhelp border=H" 00010 OPEN #1:"srow=4,scol=10,erow=8,ecol=37,border=S,caption =>S (Single-line border)",DISPLAY,OUTIN 00020 OPEN #2: "srow=4,scol=45,erow=8,ecol=72,border=d",DISPLAY,OUTIN 00030 PRINT #2, FIELDS "3,4,cc 22": "D (Double-line border)" 00040 input fields "12,15,c 50,r",help "1B; This is a field help window \n using an H (sHaded) border. \n \n Type in any CONFIG FIELDHELP \n specification such as the following: \n CONFIG FIELDHELP BORDER=BR;": FIELDHELP$ 00045 PRINT FIELDS "12,15,C 50,N": NULL$ 00050 EXECUTE FIELDHELP$ 00090 INPUT FIELDS "18,35,c 18",help "1A; This window uses the border you specified. \n If you typed in the suggested border, \n it is B (blank) using the R (reverse) attribute.\n \n Now watch the upper left window while pressing<CR> \n to see the effects of PRINT BORDER.;": CR$ 00100 PRINT #1, BORDER "*-*|*-*|": "custom-designed border" 00105 CLOSE #1,DROP: 00106 CLOSE #2,DROP:
In the above example, line 9 uses an EXECUTE statement to set the border type for all field help windows. Line 10 opens an I/O window with a single-line border and a caption in the top border that is right justified and says "S (Single-line border)".
Line 20 opens an I/O window with a double-line border. Line 30 then centers the string "D (Double-line border)" within the window. NOTE that the row and column specified in this statement assume that the top left corner of the window is row 1, column 1.
Line 40 specifies a field that accepts input on line 12 of the regular screen. It includes a field help window with text that describes its border as a shaded border (this border type for field help windows was specified back in line 9). This window also tells the user to type in a CONFIG FIELDHELP specification that identifies a new border type for field help windows.
Line 45 prints a null string over the area where the reversed input field for line 40 appeared, thus cleaning up the screen.
Line 50 executes the string typed in for line 40 to change the border type for all field help windows.
Line 90 specifies an input field that accepts input on line 18 of the regular screen. It includes a field help window that utilizes the new field help border type executed in line 50. It then instructs the user to watch the upper left window to see the effects of a PRINT BORDER statement.
Line 100 uses PRINT BORDER to change the border in window #1. The specified border uses the "8 chars" parameter, which is available in all the Business Rules instructions that specify border types (OPEN window, PRINT BORDER, and FIELDHELP).
Lines 105 and 106 close and drop the contents of the two open windows. Although the terminology may seem a little confusing at first, the act of closing a window causes the window's border to disappear and the information that was hidden by the appearance of the window to be restored. Thus, if lines 105 and 106 simply closed (without dropping) windows #1 and #2, the borders would disappear and a blank screen would be restored.
However, the act of closing and dropping a window file leaves the current contents of the window and its border intact at the same time that it drops the information that was hidden by the appearance of the window.
Using I/O Windows to Save the Screen (Prior to 4.0)
Beginning with 4.17 the TABS feature is used to display multiple windows and switch between them. See TABS later in this chapter. Saving a portion of the screen is not necessary after 4.0 because the graphic window that is opened on top of an existing window does not destroy the information on the layer below. The underlying information automatically becomes visible when the top window is closed. In versions prior to 4.0 there were not separate layers, consequently the replaced information would need to be saved in a separate screen file and restored (closed) when the overlaying information was no longer needed.
Saving all or part of the screen is very easy with I/O windows. All it requires is opening a borderless window using row and column parameters that encompass all the information to be saved. The following example saves an entire screen without making any changes to the appearance of the screen:
00670 OPEN #1:"SROW=1,SCOL=1,EROW=24,ECOL=80:,DISPLAY,OUTIN
It is useful to note that an OPEN window statement's row and column parameters identify the inside portion of a window. If a border is specified for a window, it is always placed one position outside the specified row and column.
Once an entire screen has been saved with a window, the existing screen may be altered any number of times without affecting what was saved from behind the window. Restoring the saved screen (including all attributes) is accomplished with a CLOSE statement as follows:
00750 CLOSE #1:
The capability of saving a screen becomes very useful when you wish to switch between overlapping windows. The following example demonstrates such a use:
00010 print NEWPAGE 00020 open #1: "srow=5,scol=5,erow=15,ecol=50,border=dn",display,outin 00030 print #1,fields "1,2,c 30": "Business Rules window 1" 00040 print #1,fields "10,2,c 30": "F1 to go to window 2" 00050 input #1,fields "4,4,c 10,u": X$ 00060 if CMDKEY<>1 then goto 180 00070 open #101: "srow=4,scol=4,erow=16,ecol=51",display,outin 00080 if FILE(2)<>-1 then goto 130 00090 open #2: "srow=8,scol=20,erow=18,ecol=61,border=dn",display,outin 00100 print #2: NEWPAGE 00110 print #2,fields "1,2,c 30": "Business Rules window 2" 00111 print #2,fields "9,2,c 30": "F1 to go to window 1" 00120 goto 140 00130 close #102: 00140 input #2,fields "4,4,c 10,u": X$ 00150 if CMDKEY<>1 then goto 180 00160 open #102:"srow=7,scol=19,erow=19,ecol=62",display,outin 00170 close #101: : goto 50 00180 stop
Essentially, the above program allows the user to switch between two windows by pressing the F1 key (lines 50 and 140). If the user presses F1 from window #1, the program saves window #1 by opening a borderless window (#101) that encompasses the data area of the window. It then opens window #2 (if window #2 already exists, window #102 is restored). If the user then presses F1 to go back to window #1, the contents of window #2 are saved in window #102. Window #101 is then restored (over the top of window #2) with the CLOSE statement. The same sequence of saving and restoring windows can continue indefinitely.
The above sample works well when running on CONFIG GUI OFF mode. This was the only available mode in version prior to 4.0. With the introduction of []CONFIG GUI ON]], "Using I/O Windows to Save the Screen", is no longer appropriate.
In CONFIG GUI OFF mode, opening a new window will preserve any information displayed at the time the window was created. Essentially, the information "behind the window", will "bleed through" the newly opened window. You may change any information on the screen that has been protected by this window, and when you close the window, the original text will be restored.
In the above sample, there is the illusion of multiple layers, but in reality, each window is only preserving a "screen shot" of the information, and not maintaining each of the layers. In other words, your 80 x 24 visible screen looks correct, but no other information is displayed. Information may be printed to any of the virtual layers, and it will be visible to the user, and when you close the window, the original text will be displayed as originally captured.
As an example, you can update a window that covers part of the screen, and use Print #0, to update the "Visible Area" in front of the window. Later when you close the window, the original information will be restored.
Following the above example application, in GUI OFF mode:
Line 10 erases the screen Lines 20-50 Open Window #1, (5,5 to 15,50) and display some information.
When the user presses "F1": Line 70 "Protects Window #1, (4,4 to 16,51), by opening window #101. Notice this new window is large enough to cover the line draw.
- Note: Window #1 is still open, and could be used to display information, but regardless of how the screen is updated, the entire original information will be restored when window #101 is closed.
Line 90-120 Open Window #2, (8,20 to 18,61) and display some more information
- Note: Window #2 covers up some of both windows #1 & #101. Again, Window #2 protects the contents of these two windows. And regardless of how the screen is updated (Handles #1,#101 or #2), the original information protected by window #2 will be restored when Window #2 is closed.
Again the users presses "F1": Line 160 "Protects Window #2, (7,19 to 19,62), by opening window #102, Notice this new window is large enough to cover the line draw.
- Note: Windows #1,#101 and #2 are still open, and could be used to display information, but regardless of how the screen is updated, the entire original information will be restored when window #102 is closed.
The next line performs some "Fancy Magic". Line 170 closes Window #101, (4,4 to 16,51) This causes the original text protected by Window #101 to be "restored". The effect of closing this window is that the original text created by Window #1, and then protected by Window #101, is now restored.
As you continue pressing F1, windows #101 & #102 take turns protecting and the restoring the two windows. The effect of this programing is the user sees what appears to be two complete layers. In other words, there is the illusion that the contents of both windows are actually still on the screen, and that pressing "F1" is switching layers.
In CONFIG GUI ON mode, opening a new window actually create a new layer or container without affecting the information behind it. The new window is now transparent, so the effect is very similar to a Print Newpage command. This new window may or may not have a border. In this mode, you no longer have a single 80 x 24 layer, rather each window has it's own private space. Information must be printed to the correct layer.
As an example, you can open a window that covers part of the screen, and use Print #0, to update the "Hidden Area" behind the window. Later when you close the window, the updated information will be displayed.
Examining the same code again, but using the GUI ON mode:
Line 10 erases the screen Lines 20-50 Open Window #1, (5,5 to 15,50) and display some information.
When the user presses "F1": Line 70 "Completely covers Window #1, (4,4 to 16,51), by opening window #101.
- Note: Window #1 is still open, and intact, but is no longer visible because window #101 is actually a new layer and contains no information Windows are not transparent in GUI ON mode. Window #1, remains unaffected as long as nothing is printed directly to Window #1. You could if desired, update Window #1 directly, but the changes would not be immediately apparent.
Line 90-120 Open Window #2, (8,20 to 18,61) and display some more information
- Note: Window #2 creates a new layer that covers up some of both windows #1 & #101. Because Window #101 is hiding Window #1, Window #2, appears to "Pop-Up", with Window #1 "Disappearing".
Again the users presses "F1":
Line 160 "Completely covers Window #2, (7,19 to 19,62), by opening window #102. Now the screen appears to be blank.
- Note: At this point, Window #1, is covered by Window #101, and Window #102 partially covers Window #1 & #101. Window #102 is the "Top Layer".
Line 170 closes Window #101, (4,4 to 16,51). This causes a rather strange effect as compared to the GUI OFF version. Window #1, is now partially visible because it is not covered by Window #101. However, Windows #2 & #102 are still partially covering Window #1. The effect is that Window #1 appears "Broken".
As you continue pressing F1, windows #101 & #102 take turns partially hiding the two windows. In GUI ON mode, this sample application looks terrible!
Make the following few changes to the sample program.
00070 ! OPEN #101: "srow=4,scol=4,erow=16,ecol=51",DISPLAY,OUTIN
00130 ! CLOSE #102:
00160 ! OPEN #102: "srow=7,scol=19,erow=19,ecol=62",DISPLAY,OUTIN
00170 ! CLOSE #101: !:
GOTO 50
These small changes create a new behavior that is more appealing. Now, pressing "F1" will simply move focus between the two windows. Notice that Window #2, always covers Window #1, but the user can still enter data as the focus changes.
A few more changes create the following example:
00010 PRINT NEWPAGE 00020 OPEN #1: "srow=5,scol=5,erow=15,ecol=50,Tab=Window 1",DISPLAY,OUTIN 00030 PRINT #1,FIELDS "1,2,c 30": "Business Rules window 1" 00040 PRINT #1,FIELDS "10,2,c 30": "F1 to go to window 2" 00050 INPUT #1,FIELDS "4,4,c 10,u": X$ 00060 IF FKEY=93 OR FKEY=99 THEN GOTO 180 00080 IF FILE(2)<>-1 THEN GOTO 140 00090 OPEN #2: "srow=5,scol=5,erow=15,ecol=50,TAB=Window 2",DISPLAY,OUTIN 00100 PRINT #2: NEWPAGE 00110 PRINT #2,FIELDS "1,2,c 30": "Business Rules window 2" 00111 PRINT #2,FIELDS "9,2,c 30": "F1 to go to window 1" 00120 GOTO 140 00140 INPUT #2,FIELDS "4,4,c 10,u": X$ 00150 IF FKEY=93 OR FKEY=99 THEN GOTO 180 00170 GOTO 50 00180 STOP
Run the program, and press "F1" as instructed. Notice that the tabs in fact are separate layers that preserve the text you type. As long as you are in GUI Mode, feel free to use the mouse to navigate the tabs. This modified version will only exit when you press Escape, Alt-F4 or click on the "X" to close the window.
Syntax of Statements
- Each of the full screen processing statements has basically the same syntactical form, which can be divided into the following six portions
- 1.) Statement name and I/O location.
- 2.) Field definition.
- 3.) Attribute for current field (not applicable for PRINT FIELDS).
- 4.) Field help specifications (not applicable for PRINT FIELDS).
- 5.) I/O list.
- 6.) Error condition list.
Each of the above portions are identified in the following syntax diagram for full screen processing statements. This diagram will be used for reference in describing the syntax of four of the five of the full screen processing statements. (See the Statements chapter for a separate description of the PRINT FIELDS statement.) Since the following syntax diagram is rather complex, each portion will be described separately in the parameter descriptions that follow.
- Defaults
- 1.) Display to and input from the screen.
- 2.) Do not alter attribute when field is current.
- 3.) Do not display field help text.
- 4.) Interrupt the program if an error occurs and "ON error" is not active.
Statement Name I/O Location
The "Statement name, I/O location" portion of the syntax for full screen processing statements identifies the statement being used and the file number of the window which is to be used for input or output.
- Parameters
The primary keyword ("INPUT", or "RINPUT") of the statement being used must be specified first.
"Wind-num" references a window file that has already been opened by an OPEN window statement. When this parameter is used, Business Rules input from and output to the window as if it were a separate screen: the first row and column of the window will be considered row 1 and column 1. When "wind-num" is not specified, file #0 (the full screen) is assumed.
The secondary keyword ("FIELDS" or "SELECT") of the statement being used must be specified next.
Field Definitions
- Purpose
The "Field definition" portion of the full screen processing syntax identifies the following for each field: row number; column number; format type; length of the data to be input; and the monochrome, color and control attributes which are to be used for the field.
- Comments and Examples
The following statement identifies a field that starts at row 6, column 3. The field is numeric and has a total length of 7 characters, one of which is a decimal point and two of which are decimal digits. When the statement is executed on a monochrome monitor, the field will appear as reversed and highlighted. When the statement is executed on a color screen, the background of the field will be red. The name of the variable to which input will be assigned is AMOUNT.
00750 INPUT #7, FIELDS {\b "6,3,N 7.2,HRE/:R"}: AMOUNT
- Insertable syntax ("field-spec" parameter)
- Defaults
- 1.) Fraction length = 0.
- 2.) Maximum DIM length.
- 3.) Use current attributes.
- Parameters
The above syntax may be inserted where the "field- spec" parameter appears in the main diagram for full screen processing statements. If the "string-expr" or "MAT string-array" parameters are used to specify the field definition, each must include the same elements that are identified in the "field-spec" parameter.
The "row" parameter is a required integer value that indicates the row number on the screen or in the window where the data is to be entered.
The "column" parameter is a required integer value that indicates the starting column number on the screen where data is to be entered.
The next set of parameters specifies the format type of the data to be entered. There are three possible routes.
In the top route, "num form-spec" represents a numeric format specification. G, GL, GU, GZ, L, N, and NZ are all valid in this position; the specification must be followed by a space. The "field-length" parameter, which is an integer value that identifies the length (including decimal point and decimal positions) of the field, comes next. If the field contains decimal positions, "fraction" should identify how many there are; this parameter must be separated from the field length by a period (no spaces).
In the middle route, "string form-spec" represents a string format specification. C, CC, CR, CL, CU, G, GL, GU, GZ, V, VL and VU are all valid in this position. If "field length" is used, it must be separated from the format spec by a space.
In the bottom route, the "PIC" or "FMT" specification allows you to specify a picture of the field to be input. See the File I/O chapter for a list of the characters that may be used in the "(pic-spec)" portion of this parameter.
See the File I/O chapter and APPENDIX F Format Specification for additional information about all the format specifications listed in this section.
The "attributes" parameter represents an insertable syntax that identifies the monochrome, color and control attributes that are to be used for the field. See the Definitions chapter for the insertable syntax and for additional information about this parameter.
Additionally fonts can be controlled at the field level by assigning them to attribute substitution letters as in:
- CONFIG ATTRIBUTE [J]RH,font=ariel,slant,max \line This specifies reverse highlight ariel italics maximum size.
Attribute for Current Field
- Purpose
The "Attribute for current field" portion of the full screen processing syntax identifies the attribute that should be used for the field that the cursor is on.
- Parameters
The "ATTR" keyword identifies that a separate set of attributes should be used for the current input field. It must be followed by either the "attributes" parameter or the "string-expr" parameter. "Attributes" represents an insertable syntax that identifies the monochrome, color and control attributes that are to be used for the field. See the Definitions chapter for the insertable syntax and additional information.
If used, the value of "string-expr" must include the same elements as are required in the "attributes" parameter.
- Hot text
Hot text may be displayed as either text or buttons. To make it display as a button, the trailing attribute specification should be a B followed by the fkey value to be returned when the button is clicked. e.g. "20,5,CC 12,,B1244" displayed as a button with fkey value 1244. Beginning with 4.16 the default behavior for a Hot Text field is a button. The Button may be suppressed by using an "H" instead of the "B" or no letter.
Any FIELDS text may now generate a keyboard scancode when double clicked, similar to the way BUTTONS and the Combo Box graphic do. Even linedraw characters can be "hot".
When a picture is specified as an input field, all non-navigation keys are ignored.
- Additionally fonts can be controlled at the field level by assigning them to attribute substitution letters as in
- The Shaded Sunken Appearance
Normal Windows behavior is to grey out any data entry fields that are inactive. Consequently, this is how labels appear when they are sunken. This defeats the ability to use a sunken approach to hilight screen headings. For example if you specify SCREEN U 0173 and then specify U as a leading attribute in a PRINT FIELDS specification, the field will be displayed sunken but grey.
You can now override the normal Windows behavior with regard to greying out sunken labels by specifying S as a leading attribute. The S (sunken- formerly shaded) field attribute calls for a white sunken field irrespective of whether the field is open for input.
- Fields Color Attributes
In an input or print fields statement the attributes after the slash can only contain valid color attributes such as HRGB or #RRBBGG. In the past the "N" attribute was accepted in this location. Beginning with 4.17i any non-color attribute in the color section will generate an error.
- Additional Date() Formats are supported
[NEWCELL(icells2l.spc)]
Also, a new FIELDS format is supported
row,col,DATE(dd/mm/yy)
The values are displayed as dates but are stored internally as day of century. The mask may be any valid DATE() mask.
Field Help Specifications
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.
I/O List
- Purpose
The "I/O list" portion of the syntax for full screen processing statements identifies the information that is to be input or output by the statement.
- Comments and Examples
With INPUT FIELDS and INPUT SELECT, the I/O list identifies the variables to which the input is to be assigned. With RINPUT FIELDS and RINPUT SELECT, the current values of the I/O list are output, the output values are updated by the operator, and the updated values are re-input to the specified variables.
- Parameters
A colon (:) must separate the I/O list from any previous parameters in the full screen processing statement. At least one "var-name" or "MAT array-name" must be specified. These two parameters represent the list of variables to be assigned values from the entered data. multiple variables must be separated by commas
Error-Cond List
- Purpose
The "Error-cond list" portion of the full screen processing syntax identifies the types of errors that should be trapped and where execution should be transferred to when such errors are trapped.
- Parameters
The "error-cond" portion of the parameter identifies the error to be trapped, and the "line-ref" portion identifies the line to which execution should be transferred when such an error is trapped.
- Technical Considerations
1.) Relevant error Conditions are: CONV, Error, Exit, Help, IOERR, and SOFLOW.
Console Characteristics
The name of the directory with examples for this section is: EXAMPLES\CONSOLE
A separate command console handles the operator commands without interfering with the graphical console. PRINT NEWPAGE outputs to the command console from the command prompt, and to both consoles in a program. Regular PRINT statements and PRINT USING statements output only to the command console. PRINT FIELDS and PRINT BORDER output only to the graphical console.
The name of this example is: CONSOLES.BR
00100 PRINT NEWPAGE ! output to both consoles 00200 PRINT "ABC" ! output to command console 00300 PRINT using "form C 4,C 2,N 2" : "WXYZ"," ",24! output to command console 00400 PRINT FIELDS "15,4,C 15": "million dollars"! output to graphical console 00500 PRINT #0, BORDER "Billion dollars":! output to graphical console
- Output
The consoles can be opened to other than 80 columns by 25 rows:
OPEN #0: "Srow=5,Scol=5,Rows=30,Cols=100", display, outin ! specifies position on screen and size in chars
An OPEN window statement may specify a parent window number. In the following example, window #1 is opened as a child of window #0. Srow= and Scol= reference window #0.
The name of this example is: CHILDWIN.BR
00100 OPEN #1: "SROW=2,SCOL=2,EROW=5,ECOL=20,border=S,caption=MyWindow,Parent=0",display, outin
- Output
File numbers 300-999 are now supported in addition to those below 200.
When a user defined Windows menu is displayed, the Preferences menu is suppressed. When the user-defined menu is cleared, Preferences is restored.
Datahilite
The default under Windows is to reverse each field as it is entered, and to position the cursor at the end of the data.This type of processing can be turned off, by specifying DATAHILITE OFF in the BRconfig.SYS file.
- 3D Fields applies to pre 4.0 versions
The 3D FIELDS parameter UNDR ON ignores all other attributes for underlined fields. Traditionally, BR has used either the N (normal) attribute or R (reverse) attribute and ORed the other attributes specified (H, B, and U). Now it works the same way, unless UNDR ON is specified and U is present, in which case it uses the U value exclusively. This provides greater control over the color scheme with 3D FIELDS active. You can use H for other purposes without affecting UH processing.
{\b CONFIG DATAHILITE WIN ON} indicates that the user's Windows specifications for selected text should apply to highlited text.
{\b CONFIG DATAHILITE WIN OFF} can be used to turn this feature off.
- Two new parameters were added to the {\b DATAHILITE} configuration statement
XX Uses color attribute XX (as specified in a SCREEN statement) for the "selected" text.
[X] Use the color specification associated with [X] in the ATTRIBUTE configuration statement.
The 3D FIELDS parameter UNDR ON ignores all other attributes for underlined fields. Traditionally, BR has used either the N (normal) attribute or R (reverse) attribute and ORed the other attributes specified (H, B, and U). Now it works the same way, unless UNDR ON is specified and U is present, in which case it uses the U value exclusively. This provides greater control over the color scheme with 3D FIELDS active. You can use H for other purposes without affecting UH processing.
FIELDS3D has been changed to 3D FIELDS.
When 3D fields are enabled, the screen requires more vertical space than it otherwise would. Therefore, the BR window takes on a rectangular appearance, and doesn't look as good in full screen mode as it does as a window.
To activate this feature, specify 3D FIELDS ON in your BRconfig.SYS file and also specify SCREEN U 0170 only. (Or specify SCREEN U 0170,N 38 to add some flair.)
You can also use the CONFIG command to activate this feature, but if so, you must OPEN #0: "SROW=1,SCOL=1", DISPLAY, OUTIN after executing the CONFIG command.
Specifying 3D FIELDS in BRconfig.SYS is not sufficient to activate it. You must also either precede a standard field attribute with 01 (e.g. U 0170) or specify S as a leading field attribute in your FIELDS specification.
e.g. INPUT FIELDS "10,10,C 10,S": X$ The preferred way for legacy code to activate 3D FIELDS is to use the SCREEN statement.
Ctrl-Z will act as undo when DATAHILITE is on.
Window on a field
The ability to enter and process more text than a window field can display at one time is included. This is a very powerful feature that lays the groundwork for support of proportional fonts. You will, for example, be able to enter and maintain fifty characters of data in a twenty character field on any platform.
- The syntax for enabling this capability is
00100 INPUT FIELDS "row,col,20/C 50,N/W:W": name$
Which enables up to 50 characters to be entered into a 20 character window field.
- This syntax was changed in the July release of BR 4.17. It used to be
00100 INPUT FIELDS "row,col,C 20/50,N/W:W"
where 20 was the width of the "window" and 50 was the allowed width of the data entry field. 4.17 changed this so that it would be compatable with more format statements (and easier to understand).
This new syntax also works for
00100 INPUT FIELDS "row,col,20/PIC(##D##D##),N/W:W"
and for
00100 INPUT FIELDS "row,col,date(M3 d, cy),N/W:W"
- Window on a field processing
The syntax for window on a field has been changed to accommodate more options. The displayed length of the field is the first parameter and precedes the field size.
01200 RINPUT FIELDS "10,20,40/C 100,N/W:W":TEXT$
Displays and allows input to a 100 character variable TEXT$ in a field that only uses 40 characters of screen space.
To accommodate extended field capacities with 'display under mask' field types, BR now uses the following syntax:
row,col,displayed-length/field-spec
e.g. 5,10,7/N 10.2
- 10 digits with decimal point displayed in 7 char field
or 7,10,11/PIC(#,###.##)
- 7 digits with punctuation displayed in 11 char field
The main use for this feature is to shorten the displayed length when displaying proportional fonts as in 9,10,20/C 25.
OPTION 45 allows the old method of extended field specification in addition to the new method. If the older format is encountered without Option 45, then error 861 is reported.
- Text Box
A text box with wrapping text can be displayed in BR if the field is opened in a window. An input fields statement that exceeds the width of the window will wrap within the window and allow data entry in wrapping format.
00100 OPEN #10:"SROW=10,SCOL=10,ROWS=5,COLS=20",DISPLAY,OUTIN 00200 RINPUT #10,FIELDS "1,1,100/C 2000,N/W:W":TEXT$
Will wrap an input fields data entry field within a window that is 5 rows by 20 columns. This window will wrap and scroll to allow entry of a 2000 character string.
Graphical Controls
Graphical Controls are also known as Widgets.
RADIO Buttons and CHECK Boxes will work with PRINT, INPUT, and RINPUT operations. A COMBO box may be processed with separate PRINT and INPUT statements. A COMBO box may also be processed with RINPUT after it has been populated with a PRINT statement. However, GRID and LIST require separate PRINT and INPUT statements and do not allow RINPUT.
Combo Boxes
Combo Boxes consist of two parts. A text field with an implied Q attribute, and a drop down list that may be used for selection. The Populate process (with the =, + or -) pertains only to the drop down list. INPUT operations pertain only to the text field and respond just like a text field. If Enter is pressed while entering data, then an Enter action is taken. If the mouse is used to select a NEW value, then the trailing interrupt number (FKey) is applied. However, OPTION 48 may be set on to make Enter act like a mouse double click.
Populate the drop down box:
00100 PRINT FIELDS "row, col,[display-cols/] COMBO data-cols,= [, SELECT] [, Fkey]": mat string$ ! leading attribute may be =, +,-
Note that, while the SELECT keyword is allowed as a trailing attribute in the following two statements, it has no effect because if SELECT is used, it must be specified when the Combo Box is originally created (when it is populated).
Set the text default field value: (this second step is entirely optional and is often omitted)
00200 PRINT FIELDS "row, col,[display-cols/] COMBO data-cols,text-attr [, SELECT] [, Fkey]": string$
Input the text field value (upon selection):
00300 INPUT FIELDS "row, col,[display-cols/] COMBO data-cols, field-input-attr [, SELECT]": string$
Since Combo Boxes are really an enhanced text field, they may be processed with RInput Fields just like any other text field. This would be done by pre-populating them before issuing the Input or RInput Fields that groups them in with other text fields.
Combo Boxes are single column only. Use the Combo drop down character (Q attribute) in conjunction with LIST to effect multi-column dropdowns. Note that such multi-column dropdowns need to be presented in their own child window so they don't destroy underlying controls.
FKey processing for Combo Boxes is significantly different than for use of the Q character. FKey with Combo Boxes has no relation to drop down processing. Instead it triggers the specified FKey event when someone makes a selection with the mouse or by pressing ENTER.
If SELECT is specified (as of Business Rules! version 4.20) when the Combo Box is created it will permit only selection from the drop down list. No text keyboard typing will be permitted. In order to use SELECT, it must be specified when the Combo Box is created by the populate statement. If SELECT is specified for an already existing COMBO control, a BR error is generated.
The following example demonstrates the use of Combo Boxes. Lines 600 and 700 populate two Combo Boxes. On line 800, RINPUT FIELDS groups the two Combo Boxes and inputs the selected car and model into the corresponding variables. Line 900 prints results.
Examples
Example 1
00100 print NEWPAGE 00200 dim CAR$(3)*20,MODEL$(6)*20,SELECTEDCAR$*20,SELECTEDMODEL$*20 00300 let CAR$(1)="BMW": let CAR$(2)="Chrysler": let CAR$(3)="Toyota" 00400 let MODEL$(1)="750 IL": let MODEL$(2)="525 CI": let MODEL$(3)="Sebring" 00500 let MODEL$(4)="Concorde": let MODEL$(5)="Corolla": let MODEL$(6)="Camry" 00600 print fields "1,1,20/combo 20,= ": MAT CAR$ 00700 print fields "2,1,20/combo 20,= ": MAT MODEL$ 00800 rinput fields "1,1,20/combo 20;2,1,20/combo 20": SELECTEDCAR$,SELECTEDMODEL$ 00900 print fields "4,1,C 20;4,21,C 20": SELECTEDCAR$,SELECTEDMODEL$
Output
Output of line 900:
Example 2
This example illustrates the differences between select only and original Combo Boxes.
10800 execute "CON GUI ON"
11000 print newpage
11200 dim option$(1)*32,option_sel$(2)*32
11400 str2mat("One,two,three,four,five",mat option$,',')
11600 print #0,fields "10,10,Cc27,[W]": 'Non Select '
11800 print #0,fields "10,40,Cc27,[W]": 'Select (4.2+)'
12000 print #0,fields "11,10,25/Combo 32,=": mat option$
12200 print #0,fields "11,40,25/Combo 32,=,Select": mat option$
12400 rinput fields "11,10,25/Combo 32,[D]S;11,40,25/Combo 32,[D]S": mat option_sel$
12600 for x=1 to 2 : print 'option_sel$('&str$(x)&')='&option_sel$(x) : next x
Special Notes
Combo Boxes that contain the x attribute often return FKey 209 in such cases use curfld(curfld,fkey) to avoid blinking.
00010 do 00020 rinput #win,fields mat io$,attr '[A]': mat setting$,choice_policy$,choice_desc$ 00030 if fkey=209 then let curfld(curfld,fkey) 00040 loop until fkey<>209
Check Boxes
Radio Buttons
Radio buttons allow users to select or deselect choices or options. They are functionally grouped, which means that when any entry of a group is checked, all other checked entries are unchecked.
Check Boxes work like radio buttons, but are not functionally grouped.
Each FIELD is one button.
Syntax
Radio buttons can function with PRINT, INPUT, and RINPUT operations (the above syntax only shows one RINPUT FIELDS example). Each functions a bit differently: PRINT FIELDS will print the label and button but not allow selection; INPUT FIELD will print the button for selection but not the label (and so needs a different PRINT FIELDS statement for a label; and RINPUT FIELDS displays both the button and the label and allows a selection to be made.
Specify "row, col, RADIO cols, [group][attribute] [,Fkey] [,NOWAIT]": "[^]caption"
Row and col determine where the buttons will be.
Cols is the width of the displayed caption.
Group number defaults to zero. [Group] is the number of the radio button group. Any Screen Attribute would also be placed here after the group number. The group should not be separated from the attribute by a comma.
If FKEY is specified, an FKEY interrupt is generated when the item is clicked ON or OFF.
NOWAIT denotes the G attribute, which returns control immediately to the program.
The carrot (^) at the beginning of the caption indicates an ON (checked) setting. The carrot is not displayed.
In the following example, RINPUT FIELDS creates two radio buttons in group 1. Both captions have a width of 8. If the first radio button is clicked, then an FKEY interrupt will occur, FKEY will return 10, and the value of X$ will be "^one". If the second radio button is clicked, then an FKEY interrupt will occur, FKEY will return 11, and the value of Y$ will be "^two".
00100 let X$="one" : let Y$="two" 00200 RINPUT FIELDS "1,1,radio 8,1,10;2,1,radio 8,1,11": X$,Y$ 00300 PRINT FIELDS "3,1,C 30" : "FKEY value is now "&STR$(FKEY) 00400 PRINT FIELDS "4,1,C 30" : "X$="&X$&" Y$="&Y$
- Output
- or:
Another example:
81250 Insert_Lines=1 81260 Insert_Above$="Above" 81270 Insert_Below$="Below" 81280 if Insert_Below=1 then Insert_Below$="^"&Insert_Below$ else Insert_Above$="^"&Insert_Above$ 81290 RInput #Win,Fields "2,25,Nz 3,[D];3,25,Radio 8,1[D],-1;4,25,Radio 8,1[D],-1": Insert_Lines,Insert_Above$,
MsgBox System Function
Combo Box Character
The combo box character is supported like it is by the old console (Q as a leading attribute plus specification of an fkey value).
Fonts And No Graphical Control Overlap
Labels (strings) displayed are analyzed for spacing.. If more than one blank is found or line draw or underline characters are encountered, a new control delineated. When such individual controls (label segments) are delineated the last non-whitespace character of each subfield is check for a colon. If it is a colon the text is right justified within the subfield.
IF A CHR$(5) CHARACTER IS ENCOUNTERED IT IS REPLACED BY A BLANK AND A CONTROL BOUNDARY IS DELINEATED. Delineating a new control implies continuing output at the position where it would be if the window were using fixed fonts. This can be useful when setting up a multi-column INPUT SELECT line. This is because INPUT SELECT does not align columns with proportional fonts the way PRINT FIELDS does. Ultimately it will be preferable to recode your lookups or zooms to use LISTview.
One of the disappointments in moving to a GUI presentation is that text selection via DATAHILITE overrides the ATTR value. ATTR still applies to the 'current' field (where the cursor is) once the data is deselected. But the color of selected text is necessarily determined by the operating environment. If you want to override the color of the current field immediately upon entry, then you will have to turn DATAHILITE off so the text will not be selected upon entry.
New Fonts and No Graphical Control Overlap
All window displays consist of true Windows/MAC graphical controls and *proportional fonts* are supported along with non-proportional fonts. Proportional fonts are not rendered fixed size. Positioning of controls and sizing of controls on the window are managed by simulating fixed character positions.
Hot text may be displayed as either text or buttons. The default is to display it as a button. To override this default the trailing attribute specification should be an H followed by the fkey value to be returned when the button is clicked.
e.g.
"20,5,CC 12,,B1244" displayed as a button with fkey value 1244 "20,5,CC 12,,H1244" displayed NOT as a button but returns fkey value 1244
The cursor changes to a hand pointer only for hot text and pictures. It does not do so for buttons because it is self evident that they are hot.
Labels (captions) displayed are analyzed for spacing.. If more than one blank is found or line draw or underline characters are encountered, a new control is delineated. When such individual controls (label segments) are delineated the last non-whitespace character of each subfield is check for a colon. If it is a colon, the text is right justified within the SUBfield. In other words, the colon right aligns the data WHERE IT WOULD BE IF YOU WERE USING FIXED WIDTH FONTS.
IF A CHR$(5) CHARACTER IS ENCOUNTERED IT IS REPLACED BY A BLANK AND A CONTROL BOUNDARY IS DELINEATED. Delineating a new control implies continuing output at the position where it would be if the window were using fixed fonts.
One of the disappointments in moving to a GUI presentation is that text selection via DATAHILITE overrides the ATTR value. ATTR still applies to the 'current' field (where the cursor is) once the data is deselected. But the color of selected text is necessarily determined by the operating environment. If you want to override the color of the current field immediately upon entry, then you will have to turn DATAHILITE off so the text will not be selected upon entry.
The new GUI mode does NOT permit bleed through the way the old console does. That is, anything written to an underlying window is not seen until the overlaying window is removed. However, a capability called FORCE VISIBILITY (described in a separate section) overcomes this limitation for programs designed for the old BR console.
If a field is written to a window that already has an overlapping field, then the field which it overlaps (the original field on the screen) is automatically deleted. There are a couple of exceptions to this:
- 1.) LABELs printed to a window using a proportional font can sometimes extend beyond the area that they would occupy as a fixed width font. When this happens, BR extends the control (text space) to the length of the proportional data. If a label is subsequently displayed in this extended area, it is positioned *under* the previous label extension. If a non-label is printed in this extended area, it is positioned *over* the label extension.
- 2.) If a control is displayed over the top of a LABEL's fixed character space, the original label is stenciled (or truncated) by the new control using fixed width font logic. Each resulting segment is handled independently as if it were a separate field.
Grid and List
This discussion assumes the reader has a clear understanding of INPUT FIELDS and PRINT FIELDS processing with simple fields.
Grid and List (a.k.a. ListView) are Two dimensional controls, which means that they contain rows and columns. GRIDs are normally used for data entry, while LISTs are used only for selection. In Business Rules, outputting to these controls is done with Print Fields and inputting from them is done with Input Fields. Each field specification pertains to one Control. However, a single FIELD specification can pertain to a parenthesized group of arrays. When using Grids and Lists, first the header must be populated, and then the data within the rows.
The INPUT FIELDS specification states Grid or List as the field type. The display area is specified in terms of rows and columns separated by a slash. The following parameter, instead of being leading field attributes, is a secondary keyword indicating the type (CNT/SUB/CELL/ROWCNT/ROWSUB/ROW) of output or input operation to be performed. The next parameter further qualifies the IO operation (CHG/SEL/ALL/CUR/NEXT). Normally this trailing attribute is an FKEY value which is shifted right one parameter in this context.
It is useful to work with 2D Controls in terms of rows versus cells, particularly when the columns are dissimilar. A complete set of row oriented parameters are provided for that purpose. Output operations support the mass populating of 2D controls row by row. And input operations can be row oriented as well. The keywords associated with row processing are R, ROWCNT, ROWSUB, and ROW.
RINPUT does not work with 2D controls because the output statements are somewhat different from the input statements. The output consists of setting up the columns, including providing the column headings, and populating the control with data. The input consists of identifying what has changed in a manner that enables selective data retrieval and corresponding file updating.
If the user clicks on a column heading the GRID or LIST will be sorted on that column. Sorting is done in terms of rows. Such sorting of these controls has no affect on the BR program. The information returned to BR will be as though no sorting were performed. If a control's population is increased by populating with the plus (+) flag, the control will be resequenced back to its original order before the data is added. One way a program can restore the original displayed order of a GRID or LIST is to populate it incrementally (+) with no data. As of version 4.1 and higher, if a GRID input is attempted on a protected field, BR issues a Bell.
Shift+PgUp and Shift+PgDn selects within a List/Grid.
Grids and lists are compatible with the FILTER field, which works like a search bar.
In GRIDs and LISTs only, string arrays may be used to process numeric values. BR automatically performs VAL and STR conversions as needed. If string data is passed to a numeric field type such as N or DATE then it is automatically converted to numeric form for internal processing (4.2).
As of Business Rules! versions 4.3+, arrays are automatically resized when receiving data from 2D INPUT operations. This also applies to grouped arrays. Automatic resizing only applies to one dimensional arrays and does not occur when INPUTing into two dimensional arrays. For example, where all arrays are one dimensional and may have the incorrect number of elements:
INPUT FIELDS "row,col,LIST rows/cols, ROW, ALL" : ( MAT Array1$, MAT Array2$, MAT Array3, MAT Array4, MAT Array5$ )
FKey Processing
An FKey value can be associated with a LIST or GRID control by specifying the FKey number during either output or input operations. Once an Fkey value is specified, the control retains the setting until it is reset. An FKey value can be cleared by specifying an Fkey value of minus one (-1).
When a LIST or GRID has an FKey value set processing is dependent on whether or not the 2D control is being processed by an INPUT FIELDS statement:
- Displayed but inactive- Single clicking any cell produces the FKey interrupt.
- Active (participating in Input Fields)- Double clicking any cell produces an FKey completion.
With regard to simple field specifications in PRINT FIELDS or INPUT FIELDS statements, CURROW and CURCOL identify the character position where the cursor was when FIELDS processing is completed. However, when the most recent field processed is a 2D control then CURROW and CURCOL results have different meanings:
When FIELDS processing ends and control is returned to the program while the 'current' control is of type LIST or GRID, CURROW and CURCOL are set to the current cell row and column within the 2D control instead of the character position relative to the window.
GRID CURSOR MOVEMENT
When field + or - is keyed BR always returns fkey values of 114 or 115 in both navigation and edit mode and for any type of data. (This assumes the X attribute or some other attribute returns control to the program.)
Default cursor positioning for Field +/- keys is to perform a down arrow operation, and the Enter key defaults to NONE (no movement).
In edit mode, Field +/- forces the signing of a numeric field, whether or not the field type is PIC.
In edit mode, Field +/- also right truncates any character or numeric data before exiting the field.
A Config statement can be used to override (control) grid cursor movement. When this is used, both Field +/- and Enter produce the same cursor movement:
GRID_CURSOR_MOVE DOWN | RIGHT | NONE | DEFAULT
This determines the field cursor position after keying Enter or Field +/-. Both navigation and edit mode produce the same resulting cursor position.
Restoring a User Sorted 2D Control
In versions 4.3 and higher the syntax for sorting a listview is:
PRINT FIELDS "nn,nn,GRID 10/40,SORT": { column number }
This has been extended to allow a numeric array instead of a scalar. If an array is given, it is assumed to be in the same format that SORT_ORDER returns. The new format is:
PRINT FIELDS "nn,nn,GRID 10/40,SORT": { column-number | numeric-array }
Where the numeric-array has one element for each column left to right. BR will resort the columns in the requested order.
The numeric array values indicating the order of column sorting to be performed do not need to exactly match the standard format. e.g Fractions are allowed, the values can fall within any range, and there does not need to be trailing zero elements for unsorted columns.
A multi column LISTview
01000 PRINT FIELDS "10,20,LIST 10/80,HEADERS,[HDRS][,fkey]": (MAT HEADINGS$,MAT WIDTHS, MAT FORMS$)
Note: Widths are expressed in character positions.
The [HDRS] notation refers to an optional CONFIG ATTRIBUTE HDRS specification for setting the appearance of the header row. In this case the brackets [] are required and the term HDRS may be any bracketed attribute name.
If a function key value (e.g. 1520) is given then when the control is not active, it may be clicked to trigger the specified interrupt similar to any other hot control. A function key interrupt is also triggered by double clicking during an Input operation.
| MAT HEADINGS$ | Specifies the titles that will appear at the top of each column in the List or Grid. The format of this row may be specified by an optional parameter following HEADERS in the above example. |
| MAT WIDTHS | Specifies the number of characters in each column. For example if four columns are specified and the widths are given as 10, 15, 10 and 5, then the 2D control occupies 40 character positions (plus a little for the column separators) irrespective of the number of columns specified for the display area. If needed, scroll bars are used to display wider controls within the displayed area. |
| MAT FORMS$ | Specifies the display characteristics of each column such as "C 12" or "PIC(z,zzz,zz#.##-)". A "P" following the display parameter will cause the field to be protected and no data entry will be allowed in GRID mode. |
The field form array elements may also include a trailing comma followed by field attributes (e.g. color) that pertain to the column.
PRINT FIELDS "10,20,LIST 10/80, = [,fkey]": (MAT NAME$, MAT CITY$, MAT AGE, MAT WEIGHT)
In this example, the fourth element of the HEADERS FIELD_FORM$ array (above) could specify rounding of WEIGHT to two decimal places. If an fkey value is specified, then double-clicking (or single clicking if S is specified) a cell will generate the specified fkey interrupt.
Reading a Listview or Grid
When using INPUT FIELDS to read from a 2D control, the leading attributes specification states the type of read operation and the trailing attributes specification is the type of cell or row selection to be performed. The third parameter can optionally specify NOWAIT or an FKEY value. If it is an FKEY value, it signifies that an FKEY event should be triggered when, in navigation mode, a selection is made by double clicking or pressing the Enter key.
Syntax
Parameters
Quotation marks must surround the specifications, and individual parts must be separated by commas.
Row and Column specify the space where the grid or list begins.
List or Grid, followed by rows and columns separated by a slash determine how big the list or grid is going to be. The main difference between a list and grid is that lists are for selection only while information can be added to grids directly.
The following Read Types are valid for both grids and lists:
| RowCnt | The number of rows specified. |
| RowSub | The subscripts of the specified rows. |
| Row | Read all cells in each specified row. |
| Colcnt | The number of columns established by the header arrays. e.g. INPUT FIELDS "row,col,LIST rows/cols, COLCNT, ALL" : numeric-variable |
| Sort_Order | (4.3+) Provides a value of zero for each unsorted column and gives the ascending sequence of column sorts that have occurred. If a column has been reversed (double sorted) it's value will be negative. The selection typed used must be ALL. For example: INPUT FIELDS "row,col,GRID rows/cols, SORT_ORDER, ALL" : Mat NumArray, with the following history of sorting a four column GRID:
column 1 (descending most recent) column 2 (ascending first sorted) column 3 (not sorted) column 4 (sorted ascending) SORT_ORDER would return- array(1) -> -1 array(2) -> 3 array(3) -> 0 array(4) -> 2 |
| HEADERS | (As of 4.30) The read operation returns the original PRINT FIELDS HEADER values. For example: INPUT FIELDS "row,col,LIST rows/cols, HEADERS,ALL,NOWAIT" : (MAT HEADINGS$,MAT WIDTHS, MAT FORMS$) The selection type used must be ALL. |
| MASK | (As of 4.30) MASK can be used with Grids and Lists. As a READ type, this reads the display mask setting, including listviews that have been displayed according to a filter or filterbox. For example: INPUT FIELDS "row,col,LIST rows/cols,MASK [,NOWAIT]" : mask_array. The mask array affects only the user presentation and not the data. Use RANGE processing or the CHG selection type to selectively read from a 2D control. |
These Read Types are valid for Grids only:
| Cnt | Specify the number of cells specified (see selection types below). |
| Sub | Read the Cell Subscript Values (see example below). |
| Cell | Read each cell specified. |
For the "Sel-type" parameter, the following selection types are valid for both grids and lists:
| Sel | Read one or more selected items. |
| SelOne | Select only one item. |
| All | Read all items in the control (except headings). |
| Cur | Current cell or row number. |
| Next (4.2+) | The cell the cursor is going to next if the user moved it using an arrow or a mouse click. |
| Range | Specifies which portion of a 2D control is to be input. (As of 4.3) See Below. |
| Cell_Range | A special type of output range. (As of 4.3) See Below. |
This Selection Type is valid for Grids only:
| Chg | All items changed since the last '=' populate or the last CHG retrieval of cell/row contents. |
The Read Qualifier is an optional parameter to help the read. As of 4.3 it can be DISPLAYED_ORDER. #PIC or #FMT could be used. #PIC and #FMT allow numeric data from a string to be used. For example: DISPLAYED_ORDER Indicates that the read operation is to not restore the data into it's original order before returning the results to the program (as of version 4.30). This reads the original row subscripts for all rows - in their present order - and only works with the ALL selection type.
GRIDLINES makes LIST controls look like GRIDs with respect to the display of data (column and row separators).
PRINT FIELDS "10,20,LIST 10/80,GRIDLINES": 1 | 0 (on or off)
The leading attribute values "^select" or "^deselect" may be specified to allow the pre-selection of GRID / LIST Elements:
PRINT FIELDS "nn,nn,GRID 10/40,^select ATTR": (mat start, mat end, mat attr$)
The Fkey and Nowait parameters are optional. FKEY means that an FKEY event should be triggered when a selection is made by double clicking or pressing the Enter key, in navigation mode. Nowait simply means that it does not wait for user input.
Following the ending quotation mark, a colon precedes the name of the I/O List.
DISPLAYED ORDER Read Qualifier
As of 4.30, DISPLAYED ORDER - indicates that the read operation is to not restore the data into it's original order before returning the results to the program, for example:
INPUT FIELDS "row,col,LIST rows/cols, ROWSUB, ALL, DISPLAYED_ORDER, NOWAIT": numeric-array
This reads the original row subscripts for all rows in their present order. This qualifier works only with the ALL selection type. It may be used in conjunction with other qualifiers such as FKEY.
Examples
LIST
00210 INPUT FIELDS "10,20,LIST 10/80,ROWCNT,SEL,FKEY": avail_rows ! selected row cnt 00220 ! next INPUT operation does not wait for operator 00230 MAT subscr(avail_rows) ! redimension with number of selected rows 00240 INPUT FIELDS "10,20,LIST 10/80,ROWSUB,SEL,NOWAIT": MAT subscr ! read subscripts
Uniform GRID
Contains one data array and multiple columns
00210 INPUT FIELDS "10,20,GRID 10/80,CNT,CHG": cells ! # of changed cells 00220 MAT subscr(cells) ! redimension 00230 INPUT FIELDS "10,20,GRID 10/80,SUB,CHG,NOWAIT": MAT subscr ! read subscripts 00240 MAT data$(cells) ! redimension 00250 INPUT FIELDS "10,20,GRID 10/80,CELL,CHG,NOWAIT": MAT data$ ! read changes
Row Oriented GRID
00210 INPUT FIELDS "10,20,GRID 10/80,ROWCNT,CHG": rows ! # of changed rows 00220 MAT subscr(rows) ! redimension 00230 INPUT FIELDS "10,20,GRID 10/80,ROWSUB,CHG,NOWAIT": MAT subscr ! read subscripts 00240 MAT NAME$(rows) : MAT CITY$(rows) : MAT AGE(rows) : MAT WEIGHT(rows) ! redimension 00250 INPUT FIELDS "10,20,GRID 10/80,ROW,CHG,NOWAIT": (MAT NAME$, MAT CITY$,MAT AGE, MAT WEIGHT) ! read changed rows
This brings us to the question of what is to be done with the information after it has been read. If it is to be stored in a file, then we should have included a hidden column with master file record numbers of the data in each row. This would support looping through the input array and rewriting the changed data.
While LIST subscripts are expressed in terms of rows, GRID subscripts may be either. In a four column five row GRID, the cell at row three column two has a subscript of ten.
Cell Subscript Values of a 5 x 4 GRID
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
Sample Program
The following example shows use of LIST and GRID controls. There are seven parts in this program.
The first part creates a LIST with 2 columns and 3 rows. On lines 300 - 500, column headings, widths, and form specifications are assigned to the corresponding matrices. Lines 600 and 700 place data into the matrices to be printed in the LIST. The HEADERS operation on line 800 sets the column headings, widths and form specs. Line 900 populates the LIST by row, which is the default.
00100 dim HEADINGS$(2), WIDTHS(2), FORMS$(2), NAMES$(3)*28, CITIES$(3)*18, DATA$(1)*80, SUBSCR(1) 00200 print NEWPAGE 00300 let HEADINGS$(1)="Name": let HEADINGS$(2)="City" 00400 let WIDTHS(1)=30 : let WIDTHS(2)=20 00500 let FORMS$(1)="CC 28" : let FORMS$(2)="CC 18" 00600 let NAMES$(1)="Stalin" : let NAMES$(2)="Napoleon" : let NAMES$(3)="Roosevelt" 00700 let CITIES$(1)="Moscow" : let CITIES$(2)="Paris" : let CITIES$(3)="Washington" 00800 print fields "1,1,list 8/60,headers": (MAT HEADINGS$,MAT WIDTHS,MAT FORMS$) 00900 print fields "1,1,list 8/60,=R": (MAT NAMES$,MAT CITIES$) 01000 print fields "9,1,C 50" : "Press enter to insert at the end of list" 01100 let KSTAT$(1)
Output
The second part of the program demonstrates the use of the primary flag +, which adds to the end of any previously populated data. Line 01200 redimensions matrices NAMES$ and CITIES$ to allow room for one extra item in each of them. Line 01300 places new data into the matrices to be printed in the LIST.
Line 01400 adds the new data to the LIST.
01200 mat NAMES$(UDIM(NAMES$)+1) : mat CITIES$(UDIM(CITIES$)+1) 01300 let NAMES$(4)="Churchill" : let CITIES$(4)="London" 01400 print fields "1,1,list 8/60,+": (MAT NAMES$(4:4),MAT CITIES$(4:4)) 01500 print fields "9,1,C 50" : "Select rows to be read into a matrix"
Output
The third part of the program demonstrates use of read types ROWSUB and ROWCNT and selection type SEL. Line 1600 inputs the number of selected rows into AVAIL_ROWS. The user may select rows using the mouse or the keyboard and SHIFT and CTRL keys. Line 1700 redimensions matrix SUBSCR to the number of selected rows. Line 1800 inputs the subscripts of the selected rows into matrix SUBSCR. Line 1900 performs a HEADERS operation for a new LIST using the same matrices as were used in the previous LIST. Line 2000 populates the first row of the new LIST with the data from the first selected row from the previous LIST using the primary flag =. If user selects more than one row, then lines 2100 - 2500 add the data from the selected rows using the primary flag +.
01600 input fields "1,1,list 8/60,ROWCNT,SEL": AVAIL_ROWS 01700 mat SUBSCR(AVAIL_ROWS) 01800 input fields "1,1,list 8/60,rowsub,sel,nowait": MAT SUBSCR 01900 print fields "12,1,list 8/60,headers": (MAT HEADINGS$,MAT WIDTHS,MAT FORMS$) 02000 print fields "12,1,list 8/60,=": (MAT NAMES$(SUBSCR(1):SUBSCR(1)),MAT CITIES$(SUBSCR(1):SUBSCR(1))) 02100 if UDIM(SUBSCR) > 1 then 02200 for I = 2 to UDIM(SUBSCR) 02300 print fields "12,1,list 8/60,+": ( MAT NAMES$(SUBSCR(I):SUBSCR(I)),MAT CITIES$(SUBSCR(I):SUBSCR(I))) 02400 next I 02500 end if 02600 print fields "9,1,C 50" : "Press enter to insert at beginning of list"
Output
The fourth part of the program demonstrates the use of the primary flag -, which inserts in the beginning of any previously populated data. Line 2800 redimensions matrices NAMES$ and CITIES$ to allow room for one extra item in each of them. Line 2900 places new data into the matrices to be printed in the LIST. Line 3000 adds the new data to the beginning of the LIST ahead of previously populated data.
02700 let KSTAT$(1) 02800 mat NAMES$(UDIM(NAMES$)+1): mat CITIES$(UDIM(CITIES$)+1) 02900 let NAMES$(5)="Castro" :! let CITIES$(5)="Havana" 03000 print fields "1,1,list 8/60,-": (MAT NAMES$(5:5),MAT CITIES$(5:5)) 03100 print fields "9,1,C 60" : "Press enter to populate list by column"
Output
The fifth part of the program, more specifically, Line 3300, demonstrates the use of the secondary flag C to populate the LIST by column. The primary flag = is also used in order to replace any previously populated data.
03200 let KSTAT$(1) 03300 print fields "1,1,list 8/60,=C": (MAT NAMES$,MAT CITIES$)
Output
The sixth part of the program creates a GRID. The HEADERS operation on line 3600 uses the same HEADINGS$, WIDTHS, and FORMS$ as the previously constructed LISTs. Line 3700 sets CURFLD to be on the sixth cell of the GRID (this is discussed in the next section). Line 3800 populates the GRID. The user may change the contents of the cells.
03400 print fields "23,1,C 50" : "Press enter to continue": let KSTAT$(1) 03500 print NEWPAGE 03600 print fields "1,1,grid 8/60,headers": (MAT HEADINGS$,MAT WIDTHS,MAT FORMS$) 03700 let CURFLD (1,6) 03800 print fields "1,1,grid 8/60,=": (MAT NAMES$,MAT CITIES$)
Output
The seventh part of the program demonstrates the use of read types CNT, CELL, and SUB and selection type CHG. Line 3900 counts the number of changed cells and inputs that number into variable CELLS. Line 4000 redimensions the matrix SUBSCR to the number of changed cells. Line 4100 inputs the changed cells into SUBSCR. Line 4200 redimensions the matrix DATA$. Line 4300 inputs the subscripts of the changed cells into matrix DATA$. Line 4400 prints DATA$.
03900 input fields "1,1,grid 8/60,cnt,chg": CELLS 04000 mat SUBSCR(CELLS) 04100 input fields "1,1,grid 8/60,sub,chg,nowait": MAT SUBSCR 04200 mat DATA$(CELLS) 04300 input fields "1,1,grid 8/60,cell,chg,nowait": MAT DATA$ 04400 print MAT DATA$
Output
Output of line 04400
Displaying a List or Grid (Output Operations)
To display a listview or a grid, you must set the headers first, using a special PRINT FIELDS operation.
HEADERS
The HEADERS operation sets the column headings and widths. The corresponding input/output list value must be a parenthesized group of three arrays, for example:
00250 PRINT FIELDS "10,20,LIST 10/80,HEADERS": (MAT HEADINGS$, MAT WIDTHS, MAT FIELD_FORMS$)
- or -
00250 PRINT FIELDS "10,20,GRID 10/80,HEADERS,[hdrs],1520": (MAT HEADINGS$, MAT WIDTHS,MAT FIELD_FORMS$)
The [hdrs] notation refers to an optional CONFIG ATTRIBUTE [HDRS] specification for setting the appearance of the header row. In this case the [] brackets are required.
If a function key value (e.g. 1520) is given then when the control is not active, it may be clicked to trigger the specified interrupt similar to any other hot control. A function key interrupt is also triggered by double clicking during an Input operation.
MAT HEADINGS$ Contains the column titles that will be displayed at the top of each column. The font, color and shading of these titles can be set through the [HDRS] or similar substitution attribute.
MAT WIDTHS specifies DISPLAYED Column Widths and is expressed as the number of character positions occupied by each column. Scrollbars are provided as needed to honor overall control size specified in the FIELDS specification.
For example, if four columns are specified and the widths are given as 10, 15, 10 and 5, then the 2D control occupies 40 character positions (plus a little for the column separators) irrespective of the number of columns specified for the display area. If needed, scroll bars are used to display wider controls within the displayed area.
Displayed widths of zero characters are allowed. This enables the use of hidden columns for storing things like record numbers and record keys.
MAT FIELD_FORMS$ provides the BR FORM for each column. e.g. C 15 stipulates a maximum field capacity of 15. The actual displayed length is a function of the grid size and the column relative width.
The field form array elements may also include a comma followed by leading field attributes (e.g. color) pertaining to the column.
The number of columns must be set with HEADERS prior to Populating a control (loading data into it).
MASKing
As of 4.3, LIST and GRID support the MASK operation, both in READs and Populating, as seen in this section. For example:
PRINT FIELDS "row,col,LIST rows/cols,MASK" : mask_array
This restricts the rows (for both LIST and GRID) previously displayed to those corresponding to a “true” value in mask_array. A true value is represented in a numeric array as a value greater than zero. Negative values are not allowed in mask arrays. A string mask array may also be used with “T” and “F” values. The MASK stays in effect until 1) a new MASK is specified or 2) the contents of the control are changed with PRINT ( =, +, -, see primary flags below). Also, the mask array affects only the user presentation, not the result set.
Populating
The populate operation loads data into the control. In the following example four columns are loaded:
03010 PRINT FIELDS "10,20,LIST 10/80, =": (MAT NAME$, MAT CITY$,MAT AGE, MAT WEIGHT)
- or -
03020 PRINT FIELDS "10,20,GRID 10/80, =": (MAT NAME$, MAT CITY$, MAT AGE, MAT WEIGHT)
In this example, the fourth element of the HEADERS FIELD_FORM$ array (above) could specify rounding of WEIGHT to two decimal places. If an fkey value is specified, then double-clicking (or single clicking if S is specified) a cell will generate the specified fkey interrupt.
Permissible leading attribute values are:
Primary Flags
| = | Replace any previous data |
| + | Add to any previously populated data (this allows loading in chunks) |
| - | Insert data ahead of previously populated data (4.16+) |
Secondary Flags
| R | Load one row at a time (the default - use grouped IO parens) |
| C | Load one column at a time - This is for loading multiple columns of the same data type |
| L | Provide the FKEY (see INPUT below) or Enter interrupt if the user presses up arrow or page up in the first field, or down arrow or page down in the last field. Note that this is not specified in the individual field leading attributes. |
| S | Single click to activate an Enter or FKEY event (otherwise a double click is required) (4.17+) |
Note that the following example will NOT work-
00100 PRINT FIELDS "10,20,LIST 10/80,=C": MAT NAME$,MAT CITY$,MAT AGE,MAT WEIGHT
The reason is that only MAT NAME$ will reach the list. MAT CITY$, MAT AGE and MAT WEIGHT will be associated with subsequent fields. Multiple arrays provided to a single control must be grouped with parentheses.
Populating a two-dimensional object by row with grouped IO means NAME$(1) will go into (1,1), AGE(1) will go into (1,2) and WGT(1) will go into (1,3) and so on. If a single array (MAT DATA$) is specified instead of a group, MAT DATA$ is applied horizontally instead of vertically. So DATA$(1) - DATA$(3) will be the first row and DATA$(4) - DATA$(6) will be the next row and so on.
Populating a two dimensional grid by column with an array named DATA$ means that DATA$(1) goes in (1,1) and DATA$(2) goes in (2,1) and DATA$(3) goes in (3,1). Therefore the first however many values of DATA refer to the first column and the second however many values of DATA refer to the second column. So if there are 3 columns and UDIM(DATA$) = 90 then DATA$(1)-DATA$(30) is the first column, and DATA$(31) - DATA$(60) is the second column and DATA$(61) - DATA$(90) is the last column.
For example, using the following information, each example demonstrates how the grid will be filled:
MAT NAME$ = George, Peter, Tom
MAT CITY$ = Dallas, Detroit, Denver
MAT AGE$ = 42, 23, 35
MAT WEIGHT$ = 180, 212, 193
00200 PRINT FIELDS "10,20,GRID 10/80, =": (MAT NAME$, MAT CITY$,MAT AGE$, MAT WEIGHT$)
Peter, Detroit, 23, 212
Tom, Denver, 35, 193
00200 PRINT FIELDS "10,20,GRID 10/80, =C": (MAT NAME$, MAT CITY$,MAT AGE$, MAT WEIGHT$)
Dallas, Detroit, Denver
42, 23, 35
180, 212, 193
As you can see using C with grouped arrays is counter-intuitive and doesn't fit well. C is most useful with a single array that should be loaded vertically down several columns.
Grid Validation
GRIDs are now validated as each cell is exited instead of when control is passed to the BR program after all data is entered.
Color and Font changes in Cells
The attributes that determine font, color and style in each cell can be set for an entire column by including these parameters in the heading FORM array. Individual cells can then be changed using a PRINT statement.
The format of the print statement is
00100 PRINT #WINNO, fields "2,2,LIST 10/60,ATTR":(mat start, mat end, mat attribute$)
With the following parameter descriptions:
| mat start | contains the cell number(s) where the attribute chain begins, |
| mat end | contains the last cell number where the attribute applies |
| mat attribute$ | contains the attribute specification that should be applied to the cell range(s) specified. |
If the 2d control is a GRID, then mat Start and mat End refer to starting and ending Cell Numbers. If the 2d control is a listview, then mat Start and mat End refer to starting and ending Row Numbers.
The attributes specified for any COLUMN can be overridden on a cell basis by specifying the starting cell number, ending cell number, and the overriding attributes in three arrays that are printed to the grid window with the same grid specificatoins and the key word "ATTR".
02420 PRINT #BLISTWIN,FIELDS BLISTSPEC$&",ATTR": (MAT BROWS,MAT BROWE,MAT BATT$)
In the above example, BLISTWIN is the window number, BLISTSPEC$ is the grid specification ("GRID 10/40" for example), BROWS is an array holding the starting cell number, BROWE is an array holding the ending cell number, and BATT$ is an array holding the overriding attributes. In a list the attributes of the first cell in the row controls the appearance of the entire row.
01500 PRINT FIELDS "nn,nn,GRID 10/40,ATTR": (mat start, mat end, mat attr$)
The above example overrides the attributes of a range of cells/rows for a GRID/LIST display. This allows you to shade or otherwise alter the display of a range of cells / rows in a 2D control.
Aggregate Sorting
BR supports aggregated sorting for LISTs and GRIDs. This means when clicking on various column headings or programmatically sorting columns, fields of equal values retain their previous order within their new groupings (4.2).
Numeric Column Sorting
2D controls now facilitate numeric column sorting. This works well in conjunction with the new DATE field format (see release notes 4.16) where the data is stored as day of century, but is displayed as a formatted date. It also works with all numeric columns.
If a listview columns form spec if given as DATE(mm/dd/ccyy), for example, then any time that column is sorted, either as a result of the user clicking on the column heading, or the program giving the sort command (shown below), the dates are properly sorted even though they're displayed as mm/dd/ccyy. For this to work, the data has to be given in the julian days format, see the DAYS function for more information.
In versions 4.2 and higher the syntax for sorting a listview is:
PRINT FIELDS "nn,nn,GRID 10/40,SORT": { column number }
To sort in reverse order, sort the column twice:
PRINT FIELDS "nn,nn,GRID 10/40,SORT": { column number }
PRINT FIELDS "nn,nn,GRID 10/40,SORT": { same column number }
This has been extended in version 4.3 to allow a numeric array instead of a scalar. If an array is given, it is assumed to be in the same format that SORT_ORDER returns. The new format is:
PRINT FIELDS "nn,nn,GRID 10/40,SORT": { column-number | numeric-array }
Where the numeric-array has one element for each column left to right. BR will resort the columns in the requested order.
The numeric array values indicating the order of column sorting to be performed do not need to exactly match the standard format. e.g Fractions are allowed, the values can fall within any range, and there does not need to be trailing zero elements for unsorted columns.
NOSORT for Columns
As of 4.2, the NoSort parameter is used to prevent users from sorting columns of a Grid or List.
For the statement:
PRINT FIELDS "10,20,GRID 10/80,HEADERS,[hdrs],1520": (MAT HEADINGS$, MAT WIDTHS, MAT FIELD_FORMS$)
The field attribute "^nosort" appearing in the MAT FIELD_FORM$ prevents the sorting of a grid or listview in response to the user clicking on the corresponding column header. This does not prevent programs from sorting on those columns.
Range Input
The following examples are used in versions 4.3 and higher. In these examples BR will redimension the receiving arrays as needed:
INPUT FIELDS "row,col,LIST rows/cols, CELL, RANGE" :
start, end, MAT Data$
This reads the specified range of cells. BR redimensions MAT Data$ as needed. Note that CELL may now be used with LIST. Previously, LISTs were only addressable by row.
INPUT FIELDS "row,col,LIST rows/cols, ROW, RANGE" :
(start:=7), (end:=11), ( MAT Array1$, MAT Array2, MAT Array3$ )
This reads the cells in rows 7 through 11. The receiving arrays are re-dimensioned as appropriate.
INPUT FIELDS "row,col,GRID rows/cols, ROW, RANGE":
MAT start, MAT end, ( MAT Data1$, MAT Data2$, MAT Data3 )
This reads one or more ranges of rows.
A more detailed example of this is:
100 ! create and populate a LIST control
200 MAT START(3) : MAT END(3)
210 READ MAT START, MAT END
220 DATA 7,21,33
230 DATA 11,21,38
240 INPUT FIELDS "row,col,LIST rows/cols, ROW, RANGE" : MAT START,
MAT END, ( MAT Array1$, MAT Array2, MAT Array3$ )
This reads 12 rows of data ( row 7-11, row 21 and rows 33-38 ).
Range Output
The following examples are valid for versions 4.3 and higher. By default, RANGE output refers to rows. The special keyword CELL_RANGE is used to denote the specification of cell ranges. Additionally, the use of scalars versus arrays for start and end values determines important characteristics of the output process.
Using Scalars For Range Specification
PRINT FIELDS "7,8,GRID 10/75, RANGE": start, end, MAT Data$
This replaces the values in rows numbered 'start' through 'end' with the data in MAT Data$. The size of MAT Data$ must be a multiple of the number of columns in the GRID or an error is generated.
PRINT FIELDS "7,8,LIST 10/75, RANGE": start, end, (MAT NAME$, MAT CITY$, MAT AGE, MAT WEIGHT)
This replaces the values in ROWs numbered 'start' through 'end' with the data from MATs NAME$, CITY$, AGE and WEIGHT. The data arrays must all be dimensioned the same.
Insertion and Deletion with RANGE
The number of rows being output do not need to match the number of rows being replaced. To delete a range of rows, output one or more grouped arrays with zero elements.
The following examples are valid for versions 4.3 and higher. Using the following statement, various scenarios are described.
PRINT FIELDS "7,8,LIST 10/75, RANGE": start, end, (MAT NAME$, MAT CITY$, MAT AGE, MAT WEIGHT)
start=7, end=11, and the arrays have been DIMed to nine elements Result- Nine rows replace five, and the total content of the control is expanded by 4 rows.
start=7, end=11, and the arrays are DIMed to zero elements Result- Five rows are deleted, and the total size of the control is reduced by 5 rows.
start=7, end=0 (anything less than 7), and the arrays are DIMed to support three rows Result- Three rows are inserted ahead of row seven and the total content of the control is expanded by three rows
start=5000, end={any value}, the control only has 482 rows, and the source arrays are DIMed to support eleven rows
Result- Eleven rows are appended to the end of the control and become rows 483 through 493.
Outputting Ranges of Cells
The following examples are valid for versions 4.3 and higher.
Ranges of cells may be output in conjunction with the CELL_RANGE keyword.
PRINT FIELDS "7,8,LIST 10/75, CELL_RANGE": start, end, (MAT NAME$, MAT CITY$, MAT AGE, MAT WEIGHT)
- or -
PRINT FIELDS "7,8,GRID 10/75, CELL_RANGE": start, end, MAT Data$
In this case, start and end specify cells instead of rows. If insertion or deletion is indicated by dimensioning the data arrays to greater or fewer elements than are being replaced, then the data must be a multiple of the number of columns. Insertion and deletion is only valid in terms of rows, even when cell subscripts are used to specify ranges. In such cases, if the cell subscripts are not on row boundaries, an error is generated.
PRINT FIELDS "7,8,GRID 10/75, CELL_RANGE": start, start, Data$
In this example, the value in one cell is replaced with the content of a scalar.
Using Arrays For Range Specification
If the start and end specifications are array denoting multiple ranges, there must be a one to one correspondence between the number of rows specified and those in the data. This method implies replacement only and insertion or deletion is not allowed.
The data flow that this feature was designed to support is one where the user is presented with a LIST or GRID where multiple rows have been either selected or changed before returning control to the program and the program is responding by updating something on those rows.
The program begins by presenting a 2D control to the user and reading the the control with type ROWSUB or SUB. Type SUB only works for GRIDs where all colmns have the same data type. Of course the subscripts are read into a numeric array which BR redimensions as appropriate. Then the program reads the changed or selected data with NOWAIT. (This resets the CHG flags in the control.) The program then changes either row (ROWSUB) or cell (SUB) data and outputs the results using the subscript array as both the start and end specification. Other scenarios are possible but this is the primary intended use.
The following examples are valid for versions 4.3 and higher:
100 ! create and populate a GRID --
200 INPUT FIELDS "row,col,GRID rows/cols,ROWSUB,CHG": MAT Rowsubs
(Reading subscripts does not reset the CHG flags in the control.)
210 INPUT FIELDS "row,col,GRID rows/cols,ROW,CHG,NOWAIT": ( MAT Data1$,
MAT Data2, MAT Data3$ )
BR redimensions the receiving arrays as needed.
(Reading the data also resets the CHG flags in the control.)
220 ! process the changed rows now present in the data arrays --
300 PRINT FIELDS "row,col,GRID rows/cols,RANGE": MAT Rowsubs,
MAT Rowsubs, ( MAT Data1$, MAT Data2, MAT Data3$ )
This outputs the updated rows.
Grid and List BR_VB Similarities
Before introducing grids and lists in BR, similar effects could be achieved using BR_VB to work with Visual Basic. If you were familiar with BR_VB, the following notes may be of interest:
Grid and list controls work like the BR_VB interface except headers now specify the form of each column and a new input type has been added:
A multi column LISTview-
00100 PRINT FIELDS "10,20,LIST 10/80,HEADERS[,hdrs][,fkey]": (MAT HEADINGS$, MAT WIDTHS, MAT FORMS$)
Note- Widths are expressed in character positions, not percentages like they are in BR_VB.
The populate operation-
00200 PRINT FIELDS "10,20,LIST 10/80,=": (MAT NAME$, MAT CITY$, MAT AGE, MAT WEIGHT)
Read-Ctl type: CNT (in place of CELLROWSUB) returns a single numeric value which is the number of subscripts available to read. In the case of grids, this is the number of cells. In the case of LISTviews, this is the number of rows.
00110 INPUT FIELDS "10,20,LIST 10/80,ROWCNT,SEL": avail_rows ! # of selected rows 00120 MAT DATA$(3 * avail_rows) ! redimension.. 3 cols x selected rows 00130 INPUT FIELDS "10,20,LIST 10/80,ROW,SEL,NOWAIT": MAT DATA$ ! read rows
See Also:
Tabs
Requires Business Rules! 4.16+. BR can set up tabs or tabbed windows opened at the same row and column with the TAB= keyword. In order to respond to the user clicking a tab, the FKEY value 92 is generated when a tab is clicked. This lets the program change focus to the desired tab by performing an IO statement to it.
For example:
00100 open #14: "srow=5,scol=5,rows=5,cols=20,TAB=The Tab's Caption", Display, Outin
The system function CURTAB is also available.
The example below opens two windows. The two windows are in the same tabbed group since they are opened at the same row and column with the TAB= keyword. IO will start in window #1. At first, FKEY will be -1, since no buttons or tabs have been clicked yet and ENTER has not been pressed.
If the user clicks on the second tab, FKEY value 92 will be generated and printed. After this, any time the user clicks on either of the tabs, FKEY value 92 will be generated and printed. While in either of the two windows, the user may enter in up to 10 characters into the text box. Upon pressing ENTER, FKEY value 0 will be generated. Upon clicking the "continue" button, FKEY value 20 or 22 will be generated, depending on which window the user is currently in. The program will stop executing if the Esc key or either of the two "Cancel" buttons is pressed. Also, on lines 600 and 1200, CURTAB is printed to indicated which tab has been clicked on most recently.
The name of this program is: TABS.BR
00100 print NEWPAGE 00200 open #1: "srow=2,scol=2,rows=20,cols=60,TAB=tab1",display,outin 00300 open #2: "srow=2,scol=2,rows=20,cols=60,TAB=tab2",display,outin 00400 do 00500 if CURTAB(1)=1 then 00600 print #1, fields "3,1,N 2;3,4,N 2": FKEY,CURTAB(1) 00700 print #1, fields "2,1,CC 10,,B20;2,12,CC 6,,B21": "Continue","Cancel" 00800 input #1, fields "1,1,C 10": VAR1$ 00900 print #1, fields "4,1,C 10": VAR1$ 01000 end if 01100 if CURTAB(1)=2 then 01200 print #2, fields "3,1,N 2;3,4,N 2" : FKEY,CURTAB(1) 01300 print #2, fields "2,1,CC 10,,B22;2,12,CC 6,,B23": "Continue","Cancel" 01400 input #2, fields "1,1,C 10": VAR2$ 01500 print #2, fields "4,1,C 10" : VAR2$ 01600 end if 01700 loop UNTIL FKEY=99 OR FKEY=21 OR FKEY=23
- Output
Before any buttons or tabs have been clicked yet and before ENTER has been pressed:
If the user clicks on the second tab:
If the user types data into the textbox and presses ENTER:
If the user enters data into the textbox and clicks "Continue":
Font Control and Color Specification
Attribute Substitution Name Extensions
Field Attribute [xxx] identifiers may now be up to 12 characters long.
Fonts can be specified at the field level by assigning them to attribute substitution names as in:
CONFIG ATTRIBUTE [hilite_text] font=ariel:slant:max or - CONFIG ATTRIBUTE [hilite_text] /#rrggbb:#rrggbb, font=ariel:slant:max
This specifies that [hilite_text] denotes foreground and background colors specified as #rrggbb with ariel, italics, and maximum size font.
Screen and Attribute Statements Working Together
SCREEN statements can now use [config-attribute] references. So the preferred (more readable) method for specifying screen attributes is to first define each attribute in full words and then reference them in SCREEN statements. This means that the ATTRIBUTES and SCREEN statements can be used to progressively build upon one another:
- e.g. ATTRIBUTES [lite_blue] /#112233:#556677 (This sets lite_blue foreground and background in terms of HTML color specifications.)
ATTRIBUTES [yellow] /#442255:#887799 SCREEN N [lite_blue], U [yellow]
- or better yet - ATTRIBUTES [normal] /W:W ! windows foreground and background SCREEN N [normal]
ATTRIBUTES [XX] UH, font=ariel:slant:max
- or -
ATTRIBUTES [XX] UH/RGB:W, font=ariel:slant:max
On Unix terminals the above statement would be interpreted as:
ATTRIBUTES [XX] UH/RGB:
because W and font= are ignored by Unix terminal support.
Now that I have defined [XX] and other attributes I can specify:
SCREEN N [lite_blue], U [yellow], R [XX]
The /xxx:yyy embedded syntax in FIELDS statements still overrides color for the corresponding fields, irrespective of SCREEN settings. However, now a W may be specified in lieu of R, G, B and H, denoting use the current Windows colors.
e.g. /RG:W - yellow foreground on Windows background color
Colors may now be specified as /#rrggbb:#rrggbb where rr is the red gradient, gg is the green and bb is the blue gradient. Or they may be specified as /W:W which denotes Windows foreground and background.
The *background* color attribute T denotes Transparent and applies ONLY TO LABELS (PRINT FIELDS and INPUT SELECT). This is useful for printing text over various backgrounds without showing the Windows grey around the letters.
Examples:
00080 Execute "CONFIG ATTRIBUTE [mickey_mouse] /#rrggbb:T, font=ariel:slant:max"
00090 Execute "CONFIG ATTRIBUTE [hilite_text] /#rrggbb:#rrggbb, font=ariel:slant:max" 00100 PRINT FIELDS "12,22,25/C 20,[hilite_text],520": "My Text"
This example displays up to 25 proportional characters in a 20 fixed character space in specific colors with ariel italics, maximum size, and a hot key (fkey) value of 520.
Font Characteristics
Multiple fonts are now supported under Windows. The default is still SYSTEMPC. Any installed non-proportional font is permitted that is named in the following BRCONFIG.SYS statement:
FONT {fontname} ...
Some of the fonts provided by Microsoft are:
Lucida Console
Minitel
Terminal (NT only)
some Courier fonts
Version 3.9+ supports the command STATUS FONTS. This will report all currently installed Windows fonts that are acceptable in a FONT statement. Also fonts can be changed dynamically via the CONFIG command.
FONT=
FONT.TEXT=
FONT.LABELS=
FONT.BUTTONS=
The default font is the user's Windows default font. Separate fonts may be invoked for Labels, Buttons, and Text (data entry fields):
00100 OPEN #0: "Srow=5,Scol=5,Rows=25,Cols=80,FONT=Arial", Display, Outin
- |(specifies a base font)
00200 OPEN #0: "Rows=30,Cols=100,FONT.LABELS=Terminal,FONT.TEXT=Arial,FONT.BUTTONS=Lucida Console", Display, Outin
You can also specify the following font qualifiers:
- 1.) Family: decor / roman / script / swiss / modern (fixed)(this may be useful in addition to the font name for systems that don't have the specified font)
- 2.) Boldness: light / bold
- 3.) Style: ital / slant
- 4.) Underline: under
- 5.) Size: small / medium / large / max - Size is based entirely on font height.
Font Size Adjustment- adjusts the size of displayed text down to accommodate the horizontal space allocated for the text:
- 1.) Width: Determine the average caps + digits character width. Then reduce the font size until the number of characters times this average fits the BR field capacity.
- 2.) Width+: Determine the average letter size considering both upper and lower case letters. Then apply the width limitation.
- 3.) Width-: Make the font small enough to accommodate a string of capital W's.
- 4.) NoWidth: Clear the Width adjustment setting.
e.g. 00100 OPEN #0: "Rows=30,Cols=100,FONT.LABELS=Terminal:bold:slant,FONT.TEXT=Arial,FONT.BUTTONS=Lucida Console",Display,Outin
The former FONTSIZE=99x99 parameter is only supported when GUI is OFF.
Note that the maximum length of configuration statements has been increased to 800 bytes.
Also any open window statement will inherit the attributes of the parent window, except that any new font specification (labels / text / buttons) will begin with the system defaults for that category.
Hot Text
Any FIELDS text may now generate a keyboard scancode when double clicked, similar to the way Buttons and the Combo Box graphic do.
Hot field fkey values may now be in the ranges:
- 0-99
- 1000-9999
A special hot-key value of 10000 denotes the Enter key, and generates a zero fkey value.
Linedraw can also be marked as HOT.
HTML Color Parameters
- RRGGBB, W, and T Color Specifications
Colors may now be specified as /#rrggbb:#rrggbb where rr is the red gradient, gg is the green and bb is the blue gradient. Or they may be specified as /W:W which denotes Windows foreground and background.
The *background* color attribute T denotes Transparent and applies ONLY TO LABELS (PRINT FIELDS and INPUT SELECT). This is useful for printing text over various backgrounds without showing the Windows grey around the letters.
- Examples
00100 EXECUTE "CONFIG ATTRIBUTE [hilite_text]/#442255:T font=arial:slant:max" 00200 OPEN #0: "caption=mikhail, Picture=Matrix.ico:NORESIZE",display,outin 00300 PRINT FIELDS "12,40,C 20/25,[hilite_text],80": "Text is twenty chars"
- Output
This example displays up to 25 proportional characters in a 20 fixed character space in specific colors with arial italics, maximum size, and a hot key (FKEY) value of 80.
IMPORTANT: Spaces are not allowed between the attribute substitution name [hilite_text] and the attribute combination /#442255:T. However, spaces are allowed between the attribute substitution name and the font specification. Also, do not put a comma after the attribute combination /#442255:T.
Command Console Colors
The SCREEN C xx specification determines the foreground and background colors of the command console.
Windows Color and Font Settings
- The current Windows color and font settings may be retrieved
[NEWCELL(icells2l.spc)]
- For a complete list of possible values and current settings type
STATUS ENV
Graphical Interface
A Graphic User Interface or GUI refers to the user interface and not what goes on behind the scenes.
GUI is commonly considered to include at least one or more of the following widgets:
- Grids
- ComboBoxes and checkboxes
- Dropdown Menus
- Object Oriented Design
- Mouse or keyboard driven interaction
- Proportional fonts
- Buttons
External Links
GUI Mode
GUI mode can be turned off using the command
CONFIG GUI OFF
which is the 'old' style of programming in BR, where both the command line and the running program are found in the same console, or screen. It allows Print to screen and Linput. The biggest difference is that GUI controls will not function (your program might not even run). And when the program is running correctly, the command console is not visible until CTRL-A is hit or an error is reached.
In GUI mode on, the command line and any Listing or program editing occurs in the command console, while the program runs in the GUI console, which is what the end user will see. Running a program that was designed before GUI was implemented with GUI ON may have the following problems: child windows now cover parent windows completely, print to screen and linput will not show in the GUI console and proportional fonts may change the screen's appearance.
Using various Options will aid in running older programs in the GUI console.
GUI Mode ON Fkey values
When GUIMODE is on, Fkey values may be assigned to controls either by PRINT or INPUT statements. If they are assigned with PRINT statements, they need not be specified in corresponding INPUT statements in order to be active. However, in order to clear them an Fkey value of minus one (-1) must be specified in either a PRINT or INPUT statement for the control.
When GUIMODE is on, a single click on a hot text field that is part of an active INPUT FIELDS statement will not trigger an FKEY interrupt, but it will cause the cursor to move to that field. If it is double clicked, focus is moved to the control and then the specified Fkey interrupt is generated.
Labels and inactive text fields with Fkey values assigned will continue to trigger an Fkey interrupt when they are single or double clicked.
The appearance of PRINTed sunken fields has been improved.
Input Fields
In an Input Fields statement to specify the color attributes of an inactive field you must set the attribute "[ INACTIVE]" i.e.
00200 execute "config attribute [ INACTIVE]N/#0000FF:#FFFFFF,font=SWISS:MEDIUM"
Miscellaneous
- A debug dump facility has been added to BR. It produces a file named BR_CRASH_DUMP.DMP which is very useful for resolving GPFs and assertion failures. This is produced only when using BRdebug.exe as opposed to BRnative.exe.
- TABs do not switch in response to PRINT FIELDS.
- DIR reports true filename case.
HOT Controls
All controls appear active when hot (fkey value assigned).
Protected Fields
Protected fields using Windows colors are now displayed as [ inactive], not as background.
2D SECTION COLORING
01500 PRINT FIELDS "nn,nn,GRID 10/40,ATTR": (mat start, mat end, mat attr$)
Overrides the attributes of a range of cells/rows for a GRID/LIST display. This allows you to shade or otherwise alter the display of a range of cells / rows in a 2D control.
AEX and P are now supported in HEADERS column attributes. This applies this attribute to ALL cells in the column.
Menu Support
MENU SUPPORT (only for the Windows version)
When a user defined Windows menu is displayed, the Preferences menu is suppressed. When the user defined menu is cleared, Preferences is restored.
- Summary of menu syntax supported
- ON FKEY 98 GOTO<
- INPUT MENU
- INPUT MENU TEXT
- INPUT MENU DATA
- INPUT MENU STATUS
- DISPLAY MENU
- DISPLAY MENU TEXT Used to update a menu.
- DISPLAY MENU DATA ...
- DISPLAY MENU STATUS
- MENU$
- MENU
This statement is ignored by during execution.
DISPLAY Menu Enhanced to support a "Window Handle"
(??? Which Release ???) - This was added as part of Parent=NONE.
DISPLAY #window,MENU
- Note: Window may be any "window handle", the program will automatically find the "appropriate Top Window". This means that it's always safe to use your "Current "Child" Window" without having to worry about Parent=NONE status.
- As of 4.20jg, Display #window,Menu does work, but in order for the menu to function properly, you must also display the menu on the "Console" using Display Menu without the #window.
00100 dim M$(20), PGM$(20), STATUS$(20) 00110 data "&FILE","","R" 00120 data " &New","NEW","ER" 00130 data " &Save","SAVE","ER" 00140 data " &Quit","QUIT","ER" 00150 data "&EDIT","","R" 00160 data " &Copy","COPY","ER" 00170 data " &Cut","CUT","ER" 00171 data " -","","R" 00180 data " &Paste","PASTE","ER" --- additional indentations imply additional menu levels -- 00190 data " &OPTIONS","","" 00200 data " &Verify","","CX" 00210 data " &Display Name","","C" 00220 data "&HELP","","R" 00225 data " &HELP","HELP","ER" 00230 ! 00240 let I+=1 00250 read M$(I),PGM$(I),STATUS$(I) eof 260 : goto 240
MAT M$ contains text to display. Each space indent identifies a pulldown menu of the item above.
If the text is "-", a line separator will be displayed.
MAT PGM$ is the data associated with the menu option MAT STATUS$
E = Sends FKEY 98 event if selected and no submenus are defined (activate ON FKEY 98 in program)
- P = Protect (disable/grey out/inactive) menu item
- C = Make item a checkable item, selecting item displays a check mark before it.
- X = Used with C, item is checked.
- R = Retain menu option even after the program ends, or chains to another program.
- ECX will return and FKey of 98, is checkable and is checked.
- EC will return an FKey of 98, is checkable and is not checked.
00260 display MENU: MAT M$, MAT PGM$, MAT STATUS$ !Displays menu
00270 on fkey 98 goto 400 !
00275 let KSTAT$(1) ! Wait for a keystroke
00280 INPUT MENU: MAT M$,MAT PGM$,MAT STATUS$ ! gets current menu settings
00290 INPUT MENU TEXT: MAT M$ ! Rereads text only
00300 INPUT MENU DATA: MAT PGM$
00310 INPUT MENU STATUS: MAT STATUS$
00400 X$=MENU$ ! returns data ("PGM$") from the last menu option selected
00410 X=MENU ! returns the subscript of the last menu option selected
00420 print X,X$
Selections without an "R" status do not stay active across program chains.
The following events will remove a dropdown menu.
Since INPUT MENU doesn't wait for keyboard or mouse input, it is necessary to use some other means for waiting (kstat$ or input fields). A menu click produces a kstat$ value of 6200 and, beginning with release 3.92I, an FKEY value of 98.
Example
02100 dim m_a$(1)*256,m_b$(1)*256,m_c$(1)*256
02200 mat m_a$(0) : mat m_b$(0) : mat m_c$(0)
02300 let x=5000
02400 let fn_a('top',str$(x+=1),'E')
02500 let fn_a(' choice 1',str$(x+=1),'E')
02600 let fn_a(' choice 2',str$(x+=1),'E')
02700 let fn_a(' check 1 (C)',str$(x+=1),'C')
02800 let fn_a(' check 2 (CX)',str$(x+=1),'CX')
02820 let fn_a(' check 3 (EC)',str$(x+=1),'EC')
02840 let fn_a(' check 4 (ECX)',str$(x+=1),'ECX')
02860 pr newpage
02880 pr f '5,5,Cc 70,,B99':'[Esc] End'
02882 display menu: mat m_a$,mat m_b$,mat m_c$
02890 do
03000 input fields '10,10,C 15,[D]S': pause$
03100 print f '12,10,C 40,[W]':'menu='&str$(menu)
03200 print f '13,10,C40 ,[W]':'menu$='&menu$
03300 print f '14,10,C4 0,[W]':'fkey='&str$(fkey)
03320 pr 'control returned to the calling program'
03340 pause
03400 loop until fkey=99
03500 end
03600 def fn_a(a$*256,b$*256,c$*256)
03700 mat m_a$(udim(mat m_a$)+1) : m_a$(udim(mat m_a$))=a$
03720 mat m_b$(udim(mat m_b$)+1) : m_b$(udim(mat m_b$))=b$
03740 mat m_c$(udim(mat m_c$)+1) : m_c$(udim(mat m_c$))=c$
04000 fnend ! fn_a
Keyboard Responses
GRID Navigation Mode: -----------------------------------------------
File:NEWC0046.jpg
GRID Edit Mode: -----------------------------------------------------
File:NEWC0047.jpg
Conditional On Datahilite
Insert Behavior
Insert defaults to being on if datahilite is on and off if datahilite is off. It can be configured separately.
FKEY Value:
- 90 Page up
- 91 Page down
- 99 Escape key
- 100 Right click (Help)
- 102 Up arrow
- 103 Down Arrow
- 104 Right Arrow (in Grid)
- 105 Up Field
- 106 Down Field
- 107 Field Overflow
- 109 Right Arrow
- 112 Home Key
- 113 End Key
- 114 Field Plus (Numeric Pad)
- 115 Field Minus (Numeric Pad)
- 116 Right Arrow field exit via right arrow positions to first char of next field similar to down arrow
Display Buttons
See also Print Fields Buttons
In a separately opened button bar at the bottom or top of the main window #0.
00430 DISPLAY BUTTONS mat X$: mat Y$
X$= "Row, Col, Caption Form Spec, Attributes, Fkey Value or hex scancode"
Y$= "Caption"
Use "P" for an attribute to protect (disable) the button.
Displays button captions and sets mouse actions. Clicking on a button returns the Fkey Value specified, and creates an Fkey interrupt. Optionally, a two digit hex scancode (e.g. X02) may be specified in place of an fkey value. This provides better consistency for KSTAT$ use. For example:
DISPLAY BUTTONS "1,1,C 10,,X02": "Page Up"
This will yield a scancode of 02 instead of a scancode of 5A00. However both X02 and 90 produce an fkey value of 90 because X02 equates to ctrl-B, which denotes PgUp. The scancodes introduced by KSTAT$ will be the same whether the button is clicked or the corresponding key is pressed. Note that you should still use the former numeric specification (e.g. "1,1,C 10,,nn") for actual function key emulation (where nn is an fkey value).
Mouse Response
(only effective during INPUT operation)
FKEY has two new values 200 and 201 that may occur on a field with an X attribute. This may affect your programs. These values are returned when the mouse is used to exit a field.
Mouse Buttons can be remapped with a brconfig.sys keyboard statement.
| Single Left Click | Double Left Click | |
| Without X | Move Cursor | Move and Enter |
| With X | Exit Field with 201 Fkey Value | Exit Field with 202 Fkey Value |
These exits imply that the cursor will resume at the field that is clicked upon.
| Single Right Click | Double Right Click | |
| Exit the field with Fkey Value of 100 (same as help key) | Move to new location and Exit the 100 Fkey Value |
Windows Clipboard Support
Windows Clipboard Support (Cut, Copy, and Paste)
Windows Cut and Paste
Mark a string using Shift+Arrow keys, then
Ctrl+X to cut the string to the Windows clipboard,
Ctrl+C to copy the string to the Windows clipboard,
Ctrl+V to paste the string from the Windows clipboard
(Ctrl+A replaces Ctrl+C for breaking into a program.)
The above are all standard Windows keystrokes for cut & paste. Cut and Paste may be used within BR and between BR and other applications.
If a field is highlighted, paste will only paste to that field. Otherwise, BR pastes one line per field, starting with the current field and to all subsequent fields, until the last field, or last line, whichever comes first.
| Future |
|---|
| A future release will support the mouse for marking text. |
WBTerm Compiler
Business Rules require a wbterm.out file which is produced by the wbterm compiler release 5.1 or greater. This is due to significant changes made to the way Business Rules can access scancodes from a terminal's keyboard. All old wbterm.in files should recompile successfully, but we urge you to edit any existing wbterm.in files to use the new syntax which is available. Since older versions of the wbterm.out file will not operate on this release, your wbterm.in file must be recompiled using this release 5.1 wbterm compiler.
The old method of showing scancodes in the wbterm.in file was to specify up to two significant hex digits followed by a value indicating the number of extra characters to throw away. While this method is still supported, it is not adequate for some machines such as the IBM RT, where some significant digits were being thrown away. This method allows you to specify up to 20 significant digits.
For example, on an AIX console, the F1 key returns the following values: 1B 5B 30 30 31 71. With the old method, this scancode would be specified in the wbterm.in file as F1=5B30,3;.
With this method, the string returned by this key is specified as F1=1B5B30303171;. This method also supports special characters such as \033 for escape, thus the F1 string could also be coded as F1="\033[001q". Note that the escape value ("1B" in the first example and "\033" in the second) is included in this method string, whereas it was not with the old method.
Support for remapping alphanumeric keys has also been added. For example, if you wish to remap a particular keystroke for a wbterm.in keyword, you may use the following format: F10="+";. This example would, of course, disable the use of the + key to type the "+" character, but this syntax can be useful for inserting the actual ASCII text that a key is returning.
{\b Color=5 Spec in WBTerm}
COLOR=5 has been added to the Unix/Xenix wbterm.in file (release 1.4 or greater) to support color consoles, particularly Interactive 386/ix and AIX consoles.
To learn how this specification works, you must first understand that when COLOR=5 is specified, Business Rules will send color information to the operating system in the following escape sequence format: esc[0;3c;4c(;h)(;b)m. In this sequence, 3c represents the foreground color, 4c represents the background color, and "(;h)" and "(;b)" are optional parameters for highlight and blink. Business Rules determines the values for c, h and b by referring to the COLOR=5 spec.
The format of the COLOR=5 specification is as follows:
COLOR=5, "cccccccchb";
The 10 positions in the above quoted string correspond to the 10 display attributes in the following IBM PC color table:
0 - black
1 - blue
2 - green
3 - cyan (blue+green)
4 - red
5 - magenta (red+blue)
6 - brown (red+green)
7 - white (red+blue+green)
8 - highlight
9 - blink
To create the COLOR=5 specification for any terminal, you must order the first eight digits according to the way in which their colors appear in the terminal's color table (this information should be available in the terminal documentation). The last two digits identify the escape character that must be sent for highlight and blink, respectively. The following specification, for instance, indicates that black (0) is the first color in the AT386 color table, red (4) is the second, green (2) is the third, and so on. The last two characters in the string identify that 1 is the code to use for highlight, and 5 is the code to use for blink.
COLOR=5, "0426153715"; ! actual AT386 entry
To display a red foreground on a black background, Business Rules would refer to the above COLOR=5 spec and note that red (4) is in the 1 position of the 10-digit string, while black (0) is in the 0 position of the 10-digit string. Therefore, it would send an escape sequence of esc[0;31;40m to the operating system. (It uses a value of 1 for the foreground c and a value of 0 for the background c values in the esc[0;3c;4c(;h)(;b)m character sequence.)
Likewise, to display a magenta foreground on a blue background with blink, Business Rules would see that magenta (5) is in the 6 position, blue (1) is in the 5 position, and that the value of the blink position is 5 in the COLOR=5 string. Therefore, it would send an escape sequence of esc[0;35;45;5m.
Some additional examples of escape sequences that Business Rules would send based on the above COLOR=5 spec for the AT386 are as follows:
esc[0;31;40;5m - red on black with blink
esc[0;35;40m - red+blue on black
esc[0;30;48;1m - black on white with highlight
Setting Display attributes with PRINT HEX$
In addition to using full screen processing, there are two ways to set the display attributes on a screen: with the PRINT HEX$("1Bxx") method and with the PRINT HEX$("Ex") method. In all cases, a PRINT NEWPAGE statement clears the screen and sets all character attributes to normal. Some display combinations may not be supported on all machines.
Print HEX$("1Bxx")
- Visual attributes of the display screen can be changed by executing the following statement
PRINT HEX$("1Bxx")
In this example, xx represents the machine-dependent hexadecimal representation of the display attribute. This method is not portable between equipment types. Once such a statement is executed, Business Rules uses the specified attribute for all screen output until a new PRINT HEX$("1Bxx") statement (or a PRINT NEWPAGE) is executed.
The bit configuration for xx on the IBM PC is as follows:
Print Hex$("Ex")
PRINT HEX$("Ex")
Another method of setting visual attributes of the display screen is to execute the statement PRINT HEX$("Ex"), where x is:
| 0 | normal screen |
| 1 | underline |
| 2 | blink |
| 3 | invisible |
| 4 | highlight |
| 5 | highlight underline |
| 6 | highlight blink |
| 7 | highlight blink underline |
| 8 | reverse |
| 9 | reverse underline |
| A | reverse blink |
| B | reverse blink underline |
| C | reverse highlight |
| D | reverse highlight underline |
| E | reverse highlight blink |
| F | reverse highlight blink underline |
Once the PRINT HEX$("Ex") statement is executed, Business Rules uses the specified attribute for all screen output until a new PRINT HEX$("Ex") statement (or a PRINT NEWPAGE) is encountered.
This method is not fully portable between equipment types -especially A to F.
Icon
SETENV("ICON","myicon.ico") sets the icon for the window and the taskbar to the icon specified by the second parameter (e.g. myicon).
Graphical Console
A new keyword, FONTS, has been added to the STATUS command that lists installed fonts that are suitable for use with BR.
The OPEN #0: string can contain the keyword MAXIMIZE or NOMAXIMIZE which will override the user's INI settings. If not specified, the "Save Font Size And Position" settings will govern.
{\b COMBO BOX GRAPHIC AND HOT TEXT}
PRINT FIELDS "row, col, C 10, Q,X02": "Box Caption" will place a graphic combo box down arrow graphic to the right of the field. When the field is double clicked, a HEX 02 keyboard character is generated. The X02 could also be a four digit hex value (X5044) or a function key number (14).
KEYBOARD CHANGES
The significance of certain keyboard characters has been revised:
- = changed
^ = with control key pressed
^A - break ( this was ^C )
^B - page up (back)
^C - copy to clipboard
^D - delete
^E - end field
^F - page down (forward)
^G - backtab
^H - backspace
^I - tab
^J - next field
^K - prior field
^L - right arrow
^M - enter
^N - left arrow
^O - field minus
^P - print screen
^Q - toggle insert mode
^R - up field (rise)
^S - toggle hold mode (stop)
- ^T - down field ( this once was ^V )
^U - field plus
^V - paste clipboard content
^W - home
^X - cut to clipboard
- ^Y - was REPAINT SCREEN in Unix - now HELP (back where it was)
unchanged in Windows - still HELP
^Z - restore field
^[ - escape
^\ - toggle translation of numerics to linedraw characters
- ^- - REPAINT SCREEN ( this once was ^X )
use the minus key on the top row of the keyboard
along with the control key
INPUT SELECT now displays lines like PRINT FIELDS.
Label Alignment
Labels (captions) displayed are analyzed for spacing. If more than one blank is found or line draw or underline characters are encountered (denoting a text field), a new control is delineated, which means that the label is split in two or more pieces.
When such individual controls (label segments) are delineated the last non-whitespace character of each subfield is checked for a colon. If it is a colon the text is right justified within the subfield. In other words, the colon right aligns the data where it would be if fixed width fonts were used.
The name of this example is: DELINEAT.BR
00100 PRINT FIELDS "1,1,C 10" : "one two" ! treated as a single label (one space in between) 00200 PRINT FIELDS "2,1,C 10" : "one two" ! treated as two separate labels (three spaces) 00300 PRINT FIELDS "3,1,C 10" : "one: two" ! treated as two separate labels (two spaces)!:! label "one" will be right justified in a 4 position subfield 00400 PRINT FIELDS "4,1,C 10" : "one two:" ! treated as two separate labels (three spaces)!:! label "two" will be right justified
- Output
In the output of line 200 in the above example, "two" is left aligned where it would be if a fixed font were used.
Proportional font characters have varying widths.
In the following example, when a proportional font is used, the word "row" looks longer than the word "big" and the word "bit", but the words "column", "object", and "locate" will still line up with each other when printed to the graphical console. This is because positioning and sizing of controls on the window are managed by simulating fixed character positions.
The name of this example is: PROPFONT.BR
00100 PRINT FIELDS "1,1,C 30": "Row Column" 00200 PRINT FIELDS "2,1,C 30": "Big Object" 00300 PRINT FIELDS "3,1,C 30": "Bit Locate"
- Output
If proportional fonts are turned off by executing CONFIG GUI OFF, then each letter will be exactly the same height and width as all other letters. The above example will then produce the following output:
If a CHR$(5) character is encountered with proportional fonts on, it is replaced by a blank and a control boundary is delineated. Delineating a new control implies continuing output at the position where it would be if the window were using fixed fonts. In other words, using CHR$(5) simulates fixed character positions and makes label "iiii" and label "wwww" have the same width.
The name of this example is: CHR5.BR
00100 PRINT FIELDS "1,1,C 10": "iiii wwww" 00200 PRINT FIELDS "2,1,C 10": "iiii"&CHR$(5)&"wwww"
- Output
One of the disappointments in moving to a GUI presentation is that text selection via DATAHILITE overrides the ATTR value. ATTR still applies to the current field (where the cursor is) once the data is deselected. But the color of selected text is necessarily determined by the operating environment. If you want to override the color of the current field immediately upon entry, then you will have to turn DATAHILITE OFF, so the text will not be selected upon entry. So, if the ATTR specification is to be honored, then the new GUI should be run with DATAHILITE OFF.
The new GUI mode does not permit bleed through the way the old console does. That is, anything written to an underlying window is not seen until the overlaying window is removed. However, a capability called FORCE VISIBILITY (described in a separate section) overcomes this limitation for programs designed for the old BR console.
If a text field is written to a window that already has an overlapping text field, then the text field, which it overlaps (the original text field on the screen) is automatically deleted.
The name of this example is: OVERLAP.BR
00100 PRINT FIELDS "1,1,C 5,,B20": "ooooo" ! this button will be automatically deleted 00200 PRINT FIELDS "1,5,C 2,,B40": "xx" ! this button overlaps the first one and causes the first field to be deleted
- Output
There are a couple of exceptions to this:
- 1.) Labels printed to a window using a proportional font can sometimes extend beyond the area that they would occupy as a fixed width font. When this happens, BR extends the control (text space) to the necessary length. If another label is subsequently displayed in this extended area, then it is positioned under the previous label extension. If a non-label is printed in this extended area, it is positioned over the label extension.
The name of this example is: OVERLAP2.BR
00100 PRINT FIELDS "1,1,C 8" : "SSSSSSSS" ! label 00200 PRINT FIELDS "1,9,C 4": "oooo" ! this label is positioned under the previous label 00300 PRINT FIELDS "2,1,C 8" : "SSSSSSSS" ! label 00400 PRINT FIELDS "2,9,C 4,,B5": "oooo" ! this button is positioned over the previous label
- Output
- 2.) If a control is displayed over the top of a label's fixed character space, the original label is truncated by the new control using fixed width font logic. Each resulting segment is handled independently, as if it were a separate field.
The name of this example is: OVERLAP3.BR
00100 PRINT FIELDS "1,1,C 8": "abcdefgh" ! this label is 8 character long 00200 INPUT FIELDS "1,1,C 4": VAR$ ! this control is over the top of the previous label's fixed character space and causes the label to be separated into two pieces
- Output
New Features-
Inactive Fields
Normal windows behavior is to dim inactive fields. This can be overridden with the [inactive] attribute, which refers to inactive graphical controls. The attribute names are not case sensitive.
e.g. CONFIG ATTRIBUTE [inactive]/#112233:#445566
Menu improvements
The way menus are displayed has been improved with respect to speed and appearance. The R (retain) menu flag is now honored.
Hot Controls - Focus
Any control with an FKEY associated with it via the PRINT FIELDS statement will remain hot at all times, irrespective of whether it is participating in an INPUT FIELDS operation.
[NEWCELL(icells3l.spc)]
- Paste behavior
| Action | Old | New | |
| Ctrl-V | paste goes into multiple fields at line endings | the current field gets the data it can take | |
| left/right arrows | cause a field exit at beginning and end of field | arrow keys stop at end of field | |
| up/down arrows | prior/next field | the same as left and right |
- Navigation Keys
| Action | Old | New | ||
| up/down | up/down cell | up/down cell | ||
| left/right | left/right cell | left/right cell | ||
| Home/End in GRID | get focus | set cursor | ||
| left/right | cause a field exit at | arrow keys stop at end of field |
Data entry in a Grid
INTERNAL PROCESSING CHANGES
WSID 0 No longer allowed
WSID 0 is no longer allowed. The priority of WSID assignment is:
- 1.) Command line WSID requests take precedence over brconfig.sys WSID statements.
- 2.) Of the brconfig.sys WSID statements, the last one specified is used.
NEW AND EXTENDED FEATURES
The I field attribute represents invisible. Under Windows it is now treated as a password field. Most typically it is displayed as a string of asterisks (e.g. *****).
Long filenames may now be up to 512 characters in length.
Clipboard Access
The SetEnv command and the Env$ internal function enable programmatic access to the windows clipboard.
To set the windows clipboard use:
SETENV("CLIPBOARD" ,"<replacement-value>")
To read the windows clipboard use:
ENV$("CLIPBOARD")
These expressions stow and retrieve data to and from the Windows clipboard. The word 'clipboard' is case insensitive.
New Status Commands
[NEWCELL(icells1l.spc)]
STATUS and Partial Filename
BR now supports partial filenames on the STATUS FILES and STATUS LOCKS commands: [NEWCELL(icells1l.spc)]
BUG FIXES
The text portion of Combo Boxes can now be used as ordinary FIELDS as in:
01010 INPUT FIELDS "5,10, C 12; 7,10,COMBO 15; 9,10,C 8": MAT DATA$
Formerly, the statement had to read:
01010 INPUT FIELDS "5,10, C 12; 7,10,COMBO 15; 9,10,C 8": DATA$(1),DATA$(2),DATA$(3)
DIM statements were not being reinitialized prior to Save and Replace operations. This caused arrays to be corrupted when they were redimensioned in a library routine prior to replacing a program. This was an ancient bug.