BOX, CBOX

Syntax

1. box col|{numexpr}, row|{numexpr}, cols|{numexpr}, rows|{numexpr} [,thickness] [,shade|{numexpr}] [,color] [,rgb rrggbb] [,dbl|double [gap]] [,left l] [,right r] [,top t] [,bottom b] [,icols=gridcols] [,irows=gridrows] [,ccols=gridcols] [,crows=gridrows] [,lcolor=color] [,lcolor rgb=rrggbb] [,scolor=color] [,scolor rgb=rrggbb]

2. box "text|!=text|~regexp|!~regexp[@left,top,right.bottom]", col|{numexpr}, row|{numexpr}, cols|{numexpr}, rows|{numexpr} [,thickness] [,shade|{numexpr}] [,color] [,rgb rrggbb] [,dbl|double [gap]] [,left l] [,right r] [,top t] [,bottom b] [,icols=gridcols] [,irows=gridrows] [,ccols=gridcols] [,crows=gridrows] [,lcolor=color] [,lcolor rgb=rrggbb] [,scolor=color] [,scolor rgb=rrggbb]

If cbox is used, then columns and rows are interpreted to be the opposite corner of the box, and columns and rows are calculated by UnForm.

Description

A box of the indicated dimensions will be drawn.  All dimensions can be specified to 2 decimal places, in the range of -255 to +255.   Whole number col and row represent center points; lines are drawn to the center point of the character position identified in order to facilitate connections between lines.  This differs from the shade keyword, which shades full character cells.  It may be easier to use the box keyword's shade parameter than to calculate shade positions that are offset from similar box parameters. To draw lines rather than boxes, simply set the cols or rows to 1 or 0 (1 is a special rule maintained for historical reasons), or use the line command.  If both cols and rows are 1, then a vertical line is drawn 1 character high.  To draw a box that is 1 column wide or 1 row deep, use 1.01 or .99. If used, numexpr is a Business Basic expression that generates a numeric value for the column, row, columns, or rows.

If syntax 2 is used, then the box 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 boxes drawn, 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.

Line Thickness

The optional thickness parameter may be a number from 1 to 99, indicating the number of dots or pixels to use when drawing the box outline.  The default thickness is 1 dot.  UnForm always uses dots at 1/300 inch.  If a shade parameter is desired, then the thickness parameter is required.

The left, right, top, and bottom options override the specified thickness for any given side of the box.  Setting "left 0", for example, would erase the left side of the box, while "right 4" would set the right side to 4 pixels wide.

The double or dbl option indicates a double-lined box.  Both the inner and outer lines will be drawn at the normal thickness, and the optional gap may be specified to set the pixels between each line.  The default gap is 1 pixel.  The gap must be a digit between 1 and 9.

Shading

The optional shade parameter may be used to specify a "percent gray" value from 1 to 100.  Most laser printers can only print about 8 different shades of gray, so a value of 45, for example, may print the same pattern as 50.  Note that if you specify a shade level of 0, this differs from not specifying any shade at all: a shade level of 0 will force a white interior, even if another box or shade command draws shading inside the bounds of the box.  If an interior color is specified, shading is ignored.  A shade value of -1 is equivalent to no shading at all.

Color

Color can be specified as "white", "cyan", "magenta", "yellow", "blue", "green", "red", or "black", or you can name an 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).  To distinguish colors between the line and the shade region, use "lcolor" or "lcolor rgb" for lines, and "scolor" or "scolor rgb" for shade.

Grids

The gridcols and gridrows settings are used to draw grid lines and/or shade regions inside the box. gridcols specifies one or more vertical column settings in the structure of column[:thickness[:shade[:color|rrggbb]]].  Multiple columns can be delimited by any character other than digits, the decimal point (.), and the colon.  Each column designates a vertical line to draw from the top to bottom edges of the outer box.  If a thickness is specified, then the line is drawn using that thickness (0 would draw no line at all).  The default thickness is 1.  If shade is specified, then a shade region is drawn from the left edge or prior column. gridrows is identical in structure to gridcols, but specifies the horizontal rows rather than vertical columns.  The "icols" and "irows" introducers indicate columns and rows relative to the upper-left corner of the outer box.  The "ccols" and "crows" introducers indicate absolute columns and rows.  In each case, any column or row specification outside the bounds of the box is ignored.

For partial shading, partial color shading, or multiple color shading, see the shade keyword.  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.

Examples:

box 5.5,2.5,34,3,2,10 will draw a box 34 columns wide and 3 lines high, at column 5.5, line 2.5.  The box border will be 2 dots wide (1/150 inch).  It will be filled with 10% gray shading.

box 1,1,55,1 will draw a horizontal line, 55 columns wide, at column 1, line 1.

box "Customer Total",-1,-1,60,3 will draw a box around the text "Customer Total", beginning 1 column before and 1 row up, for 60 columns and 3 rows.

cbox 12,{start_row-.5},40,{end_row+.5} will draw a box with the top and bottom lines based on two numeric variables, which would have been previously calculated in a prepage or precopy code block.  In using the cbox version, the second pair of numbers indicates the lower-right corner, rather than the number of columns and number of rows.  The code block used to calculate these positions might look something like this code, which finds the first and last rows that contain any data in the row range of 22 through 55:

prepage{

start_row=0,end_row=0

for line=22 to 55

 if trim(text$[line])>"" then if start_row=0 then start_row=line

 if trim(text$[line])>"" then end_row=line

next line

}

cbox .5,22,80.5,66,3, ccols=10.5 30 55.5 67.5, crows=23.25:1:20 60 will draw a box from column 0.5, row 22 through column 80.5, row 66.  The lines of this outer box will be 3 pixels wide.  Inside this box will be vertical lines at columns 10.5, 30, 55.5, and 67.5.  Also inside the box will be a 1 pixel high horizontal line at row 23.25, with 20% shading from row 22 to row 23.25, and another 1 pixel horizontal line at row 60.

Drivers: All (gridcols and gridrows options supported only in pcl, ps, pdf), zebra only support 0% or 100% shading.