Working with Line Colors

Overview of SPFLite color support in Edit Sessions

SPFLite provides primary commands and keyboard primitive functions to support what are called Virtual Highlighting Pens.

A highlighting pen can color a portion of text in one of fifteen colors:

The available keyboard primitive functions are:

(Pen/colorname)

(Pen/Std)

You can specify a color on FIND and CHANGE commands. You can also use LOCATE to find lines having a particular color, and can use RESET to clear the color from all lines.

See the main SPFLite Help documentation for more details on these commands and primitive functions.

Macro functions for color support

The color interface for macros provides a means to query the current color state of a line, and a way to alter that state.

What could you do with this capability? You may want to use it to analyze a block of text, and add or remove highlighting colors based on some particular condition or data value you are interested in. You could look or, or change, the text coloring in ways that are beyond the ability of native SPFLite FIND and CHANGE commands.

Recall that text highlighting pens come in up to 15 colors: The current color of a character position in a given line is represented by a unique single character. These letters and their color name are:

B Blue

G Green

Y Yellow

R Red

K Black

N Navy

T Teal

V Violet

O Orange

A Gray

L Lime

C Cyan

P Pink

M Magenta

W White

Character positions having the standard text color are presented by a blank.

Suppose you have a line of data colored like this. (The colors are shown using one possible color palette selection. You can use the Screen tab of the Global Options dialog to choose any desired text foreground and background for each of the four possible colors.)

000001 LINE ONE OF COLOR-HIGHLIGHTED DATA

To "get" the color of this line, you ask for a string that represents the color of each column of data on that line. Assume that currLptr is the line pointer to that line, and Clr_Line is a string variable:

Clr_Line = Get_Clr_Line$ (currLptr)

This would produce an "array" of color codes, one character for each character in the line of data, as a string value. Here's what the function would return:

data line = "LINE ONE OF COLOR-HIGHLIGHTED DATA"

color line = " RRR BBBB"

Because the data line has a length of 34, the string returned in the color-line variable is also of length 34.

Now, suppose you wanted to set the text value "HIGHLIGHTED" to Yellow, and make the word "ONE" the standard color. You would pass a "new" color array to the function Set_Clr_Line. This function completely replaces all existing colors for that line. So, the typical way you would do this is:

Call Get_Clr_Line$ to find the current colors for the line
Use thinBasic statements to modify the color-string as needed.
In all likelihood, color changes will involve the use of the MID$ function and/or the MID$ statement. See the thinBasic documentation for more details on these features.
Call Set_Clr_Line to replace the colors.
Be aware that the word COLOR is a reserved word in thinBasic; you can't use it as a variable name.

Assume that you have the line of data shown above, and the variable currLptr contains a Line Pointer value to that line. To remove the red color from the word "ONE", and make "HIGHLIGHTED" display as Yellow, you'd write statements like the following:

DIM Clr_Line AS STRING

Clr_Line = Get_Clr_Line$ (currLptr)

MID$(Clr_Line, 6, 3) = " " ' remove color from ONE

MID$(Clr_Line, 19, 11) = "YYYYYYYYYYY" ' make HIGHLIGHTED display as Yellow

Set_Clr_Line (currLptr, Clr_Line)

where

data line = "LINE ONE OF COLOR HIGHLIGHTED DATA"

color line = " YYYYYYYYYYY BBBB"

Note that "DATA" was Blue before, and we are setting to Blue "again". That's OK. We also changed "ONE" from Red to "standard" by making its color-code positions blank, and we changed the word "HIGHLIGHTED" from standard to Yellow. Observe that each time you call Set_Clr_Line, you are performing a complete replacement of the colors of every character on the data line.

Rules:

Only data lines have a color interface, not special lines (like TABS, BNDS and NOTE lines). If the LPTR is not for a valid, existing data line, RC is set to 8, and no other action is taken. You cannot change the color of special lines.

Get_Clr_Line$ always returns a string of length identical to the data line, even if that length is zero.

You are not allowed to attempt to change the color of non-existent character positions of a data line. The string passed to Set_Clr_Line cannot be longer than the data line you are trying to update, which is another way of saying that it cannot be longer than the string returned by Get_Clr_Line$ for that same data line. If Set_Clr_Line does get a string longer than the data line, RC is set to 8 and the colors on the data line are not changed. For this reason, it is best to always fetch the current color state of a line into a string using Get_Clr_Line$, and then modify that string, being careful not to extend its length. The function Get_Line_Len may be useful in this regard.

You should normally complete any macro modifications to the data line before proceeding with changes to the associated color line. This will ensure the line length problem will not occur.

If the color string passed to Set_Clr_Line is shorter than the data line, the color string is effectively treated as if padded with blanks to make it as long as the data line.

If any color codes other than the valid ones (or blank) are passed to Set_Clr_Line, RC is set to 8, and no other action is taken.

It is not necessary for STATE ON to be in effect if Set_Clr_Line is used. However, unless STATE is ON, any changes to the text colors will not persist after the edit file is closed.

For Get_Clr_Line$, the color code letters are returned in upper case. For Set_Clr_Line, you may specify these codes in either upper or lower case.

Created with the Personal Edition of HelpNDoc: Don't Let Unauthorized Users View Your PDFs: Learn How to Set Passwords