Text can be selected manually (either with the mouse or keyboard) and color highlighted using the (Pen/xxxx) keyboard primitives. (Pen/Blue), (Pen/Green), etc. This is fine for ad-hoc marking of text, but when you'd like to mark,  say, all occurrences of a string this would be a large task.


Many of the primary commands which support selection criteria now also support the automatic highlighting of the text found during the operation. This is performed in addition to the basic basic purpose of the command. The operands described here allow you to request this highlighting. Rather than repeat these details in each command syntax diagram, whenever the parameter color-change-request appears, the following operands can be substituted.


Color operands are used primarily on FIND and CHANGE commands. Just as you have a choice whether you want to just find data or change it, you have a choice as to whether you just want to look for data in some given color, and/or if you want to change its color. Note that finding vs. changing the color of your data is performed independently of changing the contents of your data.


This ability gives you the most flexibility, because the two actions are not dependent on each other. That is, you can change the color of text using a FIND command, or you can use a CHANGE command to alter the data contents of strings that were found to be of some color without also changing that color. Its up to you how you want to manage the color of your data.


Note: Color selection criteria and a color change request can often be combined in the same command, but not in all cases. Refer to the syntax of the particular command you are interested in to see which color operands, if any, are supported. Specific color operands are supported only where it makes logical sense to do so.


Standard Color Names


Throughout this description various color names are used. There are 15 fixed color names (BLUE, GREEN, YELLOW, RED, BLACK, NAVY, TEAL, VIOLET, ORANGE, GRAY, LIME, CYAN, PINK, MAGENTA and WHITE). These are all specified in Options -HiLites. (You are free, if you so choose, to have the standard color name RED actually display purple on the screen, or for BLUE to display gray, but for most users that would be very confusing).


All names are used in the same way.


As well as the names described above, there is also:


+STD


where +STD means the standard default Foreground / Background colors you have chosen for normal text.


Note:  The + plus sign should be read as "change", not as "positive". The operand +RED is not the opposite of a "negative" search color like -RED. -RED means to search for data which is not RED, while +RED means to change the color of data to RED.



Syntax



[ +colorname ] [ +STD ]



Operands


+color-name

You may specify at most only one color name. For example F "ABC" +RED ALL means find all the strings "ABC" and add RED highlighting to the string. It would not make sense to use multiple change-color names, since a given text string can only be in one color at any given time.



Description


The following examples should help.


FIND "ABC" 1 10 +BLUE


Find string "ABC" in columns 1 to 10 and highlight it in BLUE.


Here, a "change" occurs to the color of the data, even though there is no change to the contents of the data. For that reason, we use a FIND rather than a CHANGE command.


FIND "DEF" .110 .120 GREEN +YELLOW


This example uses both a color-selection-criteria and a color-change-request criteria.

Find the string "DEF" on lines 110 through 120 only if it currently is entirely GREEN, and if found, change its color to YELLOW.


CHANGE "GHI" "XYZ" +BLUE ALL


Change all  strings "GHI" anywhere in the file to "XYZ" and set the changed string to BLUE.


Note that because no "simple" name like RED and no "negative" name like -RED is specified, the original color of any GHI strings is ignored. The command will find all GHI strings without regard to their original color.


FIND "DEF" .110 .120 -STD +STD


This example uses both a color-selection-criteria and a color-change-request criteria.

Find the string "DEF" on lines 110 through 120 only if it currently is not the standard default color, and if found, change its color back so that it is the default color.


Note that if the -STD operand above was omitted, the DEF data would still end up set to the standard color the same way, but some text that was already in the standard color would get needless "changed" to the color it already was. For small files, this may not matter, but for very large files you will likely want to restrict the color changing operation to only the data that actually needs to be changed.


Additional Criteria


Many of the primary commands provide additional selection abilities (like X or NX, U or NU operands) which work in conjunction with the normal action of the line range operands described above. Check the detailed description of the individual primary command.



Clearing colors


If you need to clear the colors from a file, there are various ways to do this.


To clear colors from the entire file, issue the primary command RESET COLOR. See RESET - Reset (Edit Mode) for more information.


Note:  A plain RESET without COLOR doesn't clear colors, because if you went through the trouble of coloring your text, and you issued a plain RESET (say, to clear out some excluded lines), you'd be really annoyed if all your colors went away. That's why SPFLite generally doesn't have its plain RESET command do more things than IBM's ISPF does. People would not be expecting it, and it would cause too many problems. Plus, colors are not reset very often, whereas plain RESET commands get issued all the time.


Suppose you wanted to reset a block of text you highlighted with the mouse. (Be careful here not to confuse "highlighting" with "coloring". When we say highlighting, we mean "text selection" using the mouse or with the shift-arrow keys. Highlighting just means "this is a piece of text I want to reference". It has nothing to do with colors.)  


Now, if you highlight some text, you can alter the color of it using keyboard primitive functions. (Yes, in the Screen Options menu, it says "Highlight Red" etc. and the Help talks about Virtual Highlighting Pens. Unfortunately, there are not enough English words to say everything we'd like to say as uniquely as we'd like to say it.)


For example, you could define the following KEYMAP entries with virtual highlighting pen functions:


Ctrl-Shift R = (Pen/Red)

Ctrl-Shift B = (Pen/Blue)

Ctrl-Shift G = (Pen/Green)

Ctrl-Shift Y = (Pen/Yellow)

Ctrl-Shift S = (Pen/Std)


Let's say you have some string that is red. You can highlight it with the mouse, and assuming your keys are set up as shown, you could press Ctrl-Shift S, and the text color will be changed back to the "standard" non-colored one.


Created with the Personal Edition of HelpNDoc: Easily create iPhone documentation