Video Attributes in Advanced Revelation (TB#4) (Functions/Subroutines/Programs)
Created at 12 AUG 1996 03:05PM
Video Attributes in Advanced Revelation
Introduction
Advanced Revelation supports a palette of 16 colors for use with color monitors. Monochrome monitors recognize a subset of these colors as the video attributes low intensity, normal, highlight, blinking, underline, and reverse.
Depending on the process being executed, a programmer can define video attributes in one of two ways: as a four-byte escape sequence, or as a single-byte DOS video attribute.
The four-byte sequence is used when establishing a video setting as part of a PRINT statement. The one-byte video attribute is passed as the second byte of the two-byte background argument in VIDEO.RW.
Escape Sequence
The Revelation PRINT statement will recognize a four-byte sequence as a video setting if it conforms to this format:
ESC : C : background : foreground
where ESC is ASCII character 27, C is the literal upper case character, and background and foreground are each one character representing the appropriate color. Once an escape sequence has been passed to PRINT, it remains in effect until a new one is passed, or until the system is reset (see System Video Functions, below).
Possible character values for background and foreground are provided under ASCII character in Table 1, "Color Attributes":
Note: Programmers can choose any combination of background and foreground colors. However, if a light color (color values 8-15) is chosen for the background, the display will blink. Advanced Revelation will ensure that a light background is not displayed if selected in the SetVideo or Environment windows; user programs are not protected in this manner.
Monochrome attributes are established as combinations of white, black, and grey. In addition, special use of white, grey and dark blue causes special effects such as blinking, reverse or underlining. Monochrome settings, including the full escape sequences required to implement them, appear in Table 2, Monochrome Video Attributes.
As an example, the following lines of code establish a video setting in each PRINT statement:
EQU ESC TO CHAR(27)
* color
PRINT ESC:"C1<" : "This prints LRED on DBLUE"
PRINT ESC:"C5>" : "This prints LYEL on DMAG"
*
* mono PRINT ESC:"C07" : "This prints in monochrome Normal"
PRINT ESC:"C?0" : "This prints in monochrome Reverse"
PRINT ESC:"C7?" : "This prints in monochrome Reverse"
Video Attribute
The system subroutine VIDEO.RW can establish a video setting for the display area created by the subroutine. When used with the 'C' operator, the sixth argument of VIDEO.RW consists of two bytes. The first is the character to be used as the background fill character, and the second character is a video attribute.
If the display area is to be in color, the ASCII value of the video attribute can be calculated according to this formula (see also System Video Functions, below):
( background * 16 ) ( foreground )
where background and foreground correspond to the color value column in Table 1.
This forumla should only be used for color display areas. The ASCII value for monochrome video attributes is listed under value in Table 2.
For example, to create a video attribute of light yellow (value = 14) on a background of dark green (value = 2), ASCII character 46 (the letter F) is passed. The value is derived as follows:
(2 * 16) 14 = 46
(bgkrd * 16) (frgrd)
On a monochrome monitor, to create a display area of highlight text on a reverse video field, the value 127 should be used (as listed in Table 2).
Note: If the value of the video attribute calculated in this manner is greater then 127 (if a light color is used for the background), the display area will blink.
The following is a code fragment illustrating the establishment of a background character and video attribute in VIDEO.RW:
DECLARE SUBROUTINE VIDEO.RW
IMAGE=
VIDEO.RW(0,0,@CRTWIDE-1,@CRTMAXHIGH-1,'R',IMAGE)
BACK.CHAR = '*' ; * background fill character
* calculate color attribute value BGRD.COLOR = 5 ; * dark magenta
FRGD.COLOR = 14 ; * light yellow
COLOR = (BGRD.COLOR * 16) + FGRD.COLOR
VIDEO = BACK.CHAR : CHAR(COLOR)
VIDEO.RW((0,0,@CRTWIDE-1,@CRTMAXHIGH-1,'C',VIDEO)
PRINT 'Sample text': ;
INPUT RESP,1
VIDEO.RW((0,0,@CRTWIDE-1,@CRTMAXHIGH-1,'W',IMAGE)
STOP
Using System Video Attributes
In addition to calculating specific video escape sequence or attribute characters, programmers can derive video settings from the Advanced Revelation environment. The system variables @ENVIRON.SET and @AW, @PW, @EW, etc., are dynamic arrays of video (and other) attributes for various windows.
The video settings in these arrays are used as the default or normal settings for the process with which they are associated. For example, the video settings in @PW are used by POP.UP when displaying a popup window.
Programmers can change the values of @AW, @PW, etc., in order to affect the video settings of the process. Alternately, video sequences can be directly passed as arguments in several system subroutines, such as POP.UP, MSG, and SCRIBE.
Programmers should note that the background and foreground (Entries or Text prompt in the Setvideo window) attributes of the arrays @PW, @AW, @EW, etc., are stored as separate fields. For example, @PW<3> contains the background video setting for popups, and @PW<8> contains the foreground ("Selections") setting. Because the background and foreground settings are stored separately, they must be combined into a single escape sequence. In storing the sequences for these attributes, special conventions are used.
The format of the video settings in these arrays is that of normal escape sequences (four bytes leading off with Esc and C). If the setting represents a single color such as DMAG or LGRN, the third character is an ASCII character 127. The fourth character is the ASCII character used for the color represented in the video setting. If the setting is a monochrome setting such as Reverse, or a combination setting such as Yellow-on-Black, the convention of using ASCII character 127 in position three is not applicable.
If used in a system subroutine (except VIDEO.RW), an ASCII character 127 as the third character of an escape sequence will be replaced with the background character appropriate to the routine being called. In other words, ASCII character 127 functions as a wildcard character interpreted to mean current background character.
If used directly in PRINT statements, however, escape sequences containing ASCII character 127 must be updated to include the true background character. The following program illustrates a possible technique (see also System Video Functions, below):
* read settings from current environment
BGRD = @ENVIRON.SET<7>[4,1]
FGRD = @ENVIRON.SET<32>[4,1]
* combine into single escape sequence
VIDEO = CHAR(27) : 'C' : BGRD : FGRD
If required as a single-byte video attribute for a call to VIDEO.RW, an escape sequence can be turned into a single byte using this logic:
* derive chaacters for background/foreground
BGRD = @ENVIRON.SET<7>[4,1]
FGRD = @ENVIRON.SET<32>[4,1]
* turn characters into color values
BGRD = MOD( SEQ(BGRD), 16 )
FGRD = MOD( SEQ(FGRD), 16 )
* calculate video attribute value
COLOR = (BGRD * 16) + FGRD
* derive background character from environment
BCHAR = CHAR( @ENVIRON.SET<3> )
CALL VIDEO.RW(0,0,10,10,'C',BCHAR:COLOR)
(etc.)
System Video Functions
Included in Advanced Revelation are three system functions used in the establishment of video attributes. These routines are:
ESC.TO.ATTR( ) convert escape sequence to attribute
ATTR.TO.ESC( ) convert video attribute to escape sequence
CURATR( ) return escape sequence currently set for PRINT
ESC.TO.ATTR simplifies the task of creating a single-byte video attribute from an escape sequence. ATTR.TO.ESC provides the reverse capability, turning a single byte into the corresponding escape sequence. Both routines are external functions and must be declared.
This sample program fragment illustrates their use:
DECLARE SUBROUTINE VIDEO.RW, MSG
DECLARE FUNCTION ESC.TO.ATTR, ATTR.TO.ESC
EQU ESC TO \1B\
IMAGE = VIDEO.RW(0,0,10,10,'R',IMAGE)
* derive current settings for message windows
BGRD = @EW<3>[4,1]
FGRD = @EW<6>[4,1]
VIDEO = ESC:'C':BGRD:FGRD
* convert ESC sequence to single-byte attribute
ATTRIBUTE = ESC.TO.ATTR( VIDEO )
CALL VIDEO.RW(0,0,10,10,'C',*:ATTRIBUTE)
* (etc.)
* convert video attribute to ESC sequence
CHAR = MSG('Enter any single character','R',CHAR,)
IF CHAR THEN CHAR = CHAR[1,1]
MSG('Escape sequence = ':ATTR.TO.ESC(CHAR),,,'')
CURATR is used to read the escape sequence currently established for the PRINT statement. This can be used to read, save, and then restore the current video attributes. The function is internal and need not be declared before being called. The following code fragment illustrates its use:
PRINT "This prints in original colors."
SAVE.VIDEO = CURATR()
PRINT @(0,10) : \1B\:'C<1' : 'This prints in new colors."
PRINT SAVE.VIDEO : "This prints again in original"
DOS Video Attribute
Advanced Revelation video and color attributes are based on the DOS video attribute. A DOS video attribute is a character that is printed along with each character that appears on a screen (in other words, each character on the screen has an associated video attribute character).
Single DOS video attribute stores the setting for foreground and background, using four bits for each setting. The layout is as pictured in figure 1.
Three bits are reserved for the color or video setting. The high-order of each nibble is reserved as a high intensity bit; when set, the color of that nibble appears light. The high-order bit of the background attribute is ambiguously defined as a blink flag. As a result, any light color in the background (any setting in which bit 7 is set) will be light, but will blink.
Possible bit settings for the foreground and background are shown in figure 2.
Figure 1
7 6 5 4 3 2 1 0
<background > ← foreground- - >
<blink> <flag> [< [high intensity flag]
Figure 2
Foreground
(dark colors) (light colors)
0000 0 Black 1000 8 Grey (Lblack) ….
0001 1 DBlue 1001 9 Lblue ….
0010 2 DGreen 1010 10 Lgreen ….
0011 3 DCyan 1011 11 Lcyan ….
0100 4 DRed 1100 12 Lred ….
0101 5 DMag 1101 13 Lmag ….
0110 6 DYel 1110 14 Lyel ….
0111 7.LGrey (DWhite) 1111 15 White (Lwhite)
Background
000….0 * 16 Black
001….1 * 16 Dblue
010….2 * 16 Dgreen .
011….3 * 16 Dcyan .
100….4 * 16 Dred .
101….5 * 16 Dmag .
110….6 * 16 Dyel .
111….7 * 16 Lgrey
Blink Flag
0…….+ 0 No blink
1…….+ 128 Blink
Table 1
Color Attributes
Color
Value Code Color ASCII Character
0 BLACK Black 0
1 DBLUE Dark-blue 1
2 DGRN Dark-green 2
3 DCYAN Dark-cyan 3
4 DRED Dark-red 4
5 DMAG Dark-magenta 5
6 DYEL Dark-yellow (Brown) 6
7 LGREY Light-gray (Dark White) 7
8 DGREY Dark-gray (Light Black) 8
9 LBLUE Light-Blue 9
10 LGRN Light-green :
11 LCYAN Light-cyan ;
12 LRED Light-red <
13 LMAG Light-magenta =
14 LYEL Light-yellow >
15 WHITE White ?
Table 2
Monochrome Video Attributes
Value Code Attribute Escape Sequence
1 U Underline ESC:'C01'
7 N Normal ESC:'C07'
8 – Low-intensity ESC:'C08'
15 H Highlight ESC:'C0?'
112 R Reverse ESC:'C70'
120 – Reverse low-intensity ESC:'C78'
127 – Reverse highlight ESC:'C7?'
129 UB Underline-blink ESC:'C81'
135 B Blink ESC:'C87'
136 – Low-intensity blink ESC:'C88'
143 – Highlight blink ESC:'C8?'
240 RB Reverse blink ESC:'C?0'
248 – Low-intensity reverse blink ESC:'C?8'
255 – Highlight reverse blink ESC:'C??'
* ESC should be assigned or EQUated to the value CHAR(27).