SHADE, CSHADE

Syntax

1. shade col|{numexpr}, row|{numexpr}, cols|{numexpr}, rows|{numexpr}, percent|{numexpr} [,extend] [,color] [,rgb rrggbb]

2. shade col|{numexpr}, row|{numexpr}, cols|{numexpr}, rows|{numexpr}, percent|{numexpr}, skip, times [,extend] [,color] [,rgb rrggbb]

3. shade "text|!=text|~regexp|!~regexp[@left,top,right.bottom]", col|{numexpr}, row|{numexpr}, cols|{numexpr}, rows|{numexpr}, percent|{numexpr} [,extend] [,color] [,rgb rrggbb]

If cshade is used, then cols and rows are interpreted to be the opposite corner of the shade region, and columns and rows are calculated by UnForm.

Description

The region indicated by col, row, cols, and rows will be shaded, using the percent as the percent-gray value.  The region parameters can be specified as decimal values to 1/100 character.   The region is based on the full character cell, starting at the upper left corner of the cell.  This differs from the box keyword, which measures from the center point of a cell.  The percent can be any value from 0 to 100, where 0 is white (useful for erasing regions), and 100 is black.  The default shade value is 5% (which renders as 10% in PCL5 devices).  PCL5 printers actually support only eight levels of gray, generally:  2%, 10%, 20%, 35%, 55%, 80%, 99%, and 100%.  Values less than these are rounded up to the next supported value.  If you wish to issue a shade command that will do nothing, use -1 as the percent.

For compatibility with Version 1 rule files, Version 2 and above will convert shade values of 1, 2, 3, and 4 to 2%, 20%, 55%, and 100%, respectively.

If used, numexpr is a Business Basic expression that generates a numeric value for the column, row, columns, or rows.

Syntax 2 provides for repeating regions to be easily specified.  The skip parameter is a number indicating the number of blank lines that follow the shade region.  The times parameter is the number of times to repeat the shade/blank pattern.  UnForm will generate multiple rows of shading until either the number of repetitions is met or the end of the page is found.  For example, shade 1,21,80,2,1,2,8 would produce 8 shaded regions, each 80 columns by 2 rows with shade grade level 1.  Two blank lines would separate the shade regions.  These two parameters are ignored if the first parameter is a text string, as in syntax 3.

If syntax 3 is used, then the shading is drawn relative to any occurrence of the text, or of text that matches the regular expression regexpr.  In these cases, there may be no shaded regions, or several. column and row are 0-based, in these formats, and can be negative if required. The search for text or regexpr can be limited to a region on the page by adding a suffix in the format '@left,top,right,bottom'.  To use a literal "@" character in text or regexpr, it is necessary to specify "\@".

If the syntax "!=text" or "!~regexpr" is used, then the search is for positions NOT equal to the text or NOT matching the regular expression.  When using the NOT syntax, only one search is performed per line in the search region.

All formats support the extend option.  This simply expands the shade region by ½ character in all directions, making it easy to fill in a box that is placed at the mid-point of each character position surrounding the shade region.

Note that the box keyword also supports shading, and may be more convenient to use if an outlined shaded region is desired.

Color can be specified as white, cyan, magenta, yellow, blue, green, red, or black, or you can name a RGB value as a 6-character hex string with rgb rrggbb, where rr is red (00-FF), gg is green (00-FF), and bb is blue (00-FF).

You can improve the look of shade regions on laser printers, especially at medium shade levels and 600 or higher dpi settings, by using the gs command.

With PostScript input, use a shade percent of 0 to erase a region of the overlay and allow UnForm graphical enhancements to remain visible.

Examples:

shade 41,3,40,6,2 will fill the indicated region with a medium  (20%) shade.

shade 10.5,3.01,40,4.98,25 will shade the indicated region with 25% gray.

shade "No.  Item/Desc",0,0,79,1,10,extend will shade from the position the noted text is found, for 79 columns and 1 line.  The shaded region will then be extended ½ column and row in each direction.  10% gray will be used.

shade 1,14,80,2,1,2,12 will produce a repeated pattern of 80 columns wide, 2 lines high, light shading, followed by two blank lines.  The pattern will be repeated 12 times, occupying a total of 48 lines.

Drivers: pcl, pdf, ps

For Zebra (0% or 100% only), use a box command.