Send PostScript Options

DESCRIPTION:

Provides a means to control some of the behavior of the PostScript printer driver embedded in the current graphics device. It is only effective for devices that support printgraph. It is not intended for general use, but is intended for use by the device initialization functions.

USAGE:

ps.options.send(defaults=lapply(ps.options(), eval), <<see below>>, 
                force=F) 

OPTIONAL ARGUMENTS:

defaults
list object defining the default values for each of the other arguments to this function (except for force). The argument names are the same as the names of the components of the defaults list and are enumerated in the OPTION NAMES section below.
force
logical value: If TRUE, all PostScript options will be sent to the current graphics device. If FALSE, only the given options will be sent.

OPTION NAMES:

ARGUMENTS:

background
numeric object specifying a background color to use. If background is a single positive integer, it is treated as an index into the colors argument. If it is a negative number, then there is no background. Otherwise, it is assumed to be a single explicit color specification as in the colors argument. The default is -1 (no background).
black.and.white
character object containing the PostScript code for determining whether or not the current printer device is a black and white printer or a color. It should be a fragment of PostScript code that expects nothing on the stack and pushes either a true or false value onto the stack. It should push a true if the printer is black and white, false if it can really do colors. This boolean is used in deciding whether or not to override the color setting when doing line drawing by explicitly setting the current color to black. The PostScript interpreter on a black and white printer will try to simulate colors by using a fill pattern. This causes confusion when done to lines, so an attempt is made to explicitly use either black or white for lines in such cases.
bullet
character object containing the PostScript procedure for plotting a "bullet" character. The "bullet" character is plotted whenever the pch graphical parameter is set to "*". It also contains a PostScript procedure that is called whenever the pch parameter is set to "*" to take care of any needed initializations. The default for this is a solidly filled dot, when used with the default value of setfont. This may need adjustment if a different setfont value is used. The builtin datasets ps.bullet.latin1 and ps.bullet.std give the standard PostScript "bullet" for the latin1 and PostScript standard font encodings.
colors
numeric object giving an assignment of colors to color numbers. Using the default setcolor specification, there are two possibilities. If colors is a vector, it is used to define gray levels (0=black to 1=white) beginning with color number 1. If colors is a 3-column matrix, it is used to define colors in the RGB model (see the PostScript Language Reference Manual), one per row, beginning with color number 1.

The matrix ps.colors.rgb can be subsetted to provide a value for this argument. Also, the function ps.hsb2rgb can be used to convert colors from the HSB model to the RGB model equivalents. See the examples section below.
command
character string containing a UNIX command that will be performed on the PostScript output. The default command is the environment variable S_POSTSCRIPT_PRINT_COMMAND. The name of the file containing the PostScript output will be appended to the command string. If command is an empty string, printing will be disabled.
dsc
number denoting the version of Adobe's Document Structuring Conventions(DSC) to use. This argument is primarily used to force an older version of the DSC headers to accommodate older software that may need to interpret those headers. Its use is not generally recommended.
extra.setup
character object containing PostScript code to be inserted in the document setup section of the resulting output. This can be used to add site or user specific customizations to the PostScript output without having to copy and modify the entire preamble shipped with S-PLUS. It's default value is the empty string, "".
font
number giving the default font for text (see fonts). A negative number will select the font in its outline form. The default value is 1 to pick the 1st font in fonts.
fonts
character object enumerating the fonts you want available in PostScript. Font number i will be the i-th font named in this vector.
height
height of plotting region in inches. height refers to the y axis dimension.
horizontal
logical flag: if TRUE, plots are in landscape mode (x axis is along the longer edge of the paper). Otherwise, plots are in portrait mode.
image.colors
numeric objects giving an assignment of colors to color numbers. These colors are used as fill colors for use with the image function. Refer to the colors component for specification details.
max.vertices
number denoting the maximum number of vertices to output in a polygon before forcing a line drawing operation (instead of filling). There is a limit to the number of vertices that can be used to describe a filled polygon (generally, the limit is around 1500).
maximize
logical flag: if TRUE, the page is used to the fullest (reasonable) extent. If FALSE, the PostScript output will try to match the actual size of the plot. The aspect ratio (or relative proportions) of the plot is maintained in either case.
paper
character string indicating the size of the paper loaded into the PostScript printer. Some values accepted for paper are "letter", "legal" or "a4". Most standard ANSI and ISO paper sizes are accepted. This is used to determine the "imageable region" area of the paper. This argument, along with the ps.paper.regions dataset, will determine the default value for the region argument.
pointsize
base size of text, in points (one point = 1/72 inches). If the graphical parameter cex is equal to 1, text will appear in this size. The default value is 14 points. If you are creating small figures, you may want to specify a smaller point size.
preamble
character object containing the PostScript program that defines the driver. The components preamble, setcolor and setfont are provided to allow for changing the behavior of the generated PostScript code. They will be concatenated (in that order) to form the full PostScript preamble in the resulting output. Generally, they should not be changed except by users with a knowledge of PostScript. Indiscriminately changing these components can result in undesirable behavior such as lost output or hung printers. It's default value is a reference to the S-PLUS dataset ps.preamble.std.
rasters
number of plotting units per inch. The default is the typical laser printer device resolution of 300 units per inch.
region
numeric vector of length 4 giving the coordinates of the lower left and upper right corners of the imageable region for the printer, in default PostScript coordinates. The default is determined by the paper argument and the ps.paper.regions dataset.

See the ps.paper.regions documentation for a way to discover the imageable region of your printer.
setcolor
character object containing the PostScript procedure for setting the current color. The procedure will be called with an integer color number by the PostScript program, or with a floating point number between 0 and 1 denoting a gray level. Typical values for this are contained in the ps.setcolor.rgb and ps.setcolor.hsb datasets.
setfont
character object containing the PostScript procedure for setting the current font. The procedure will be called with an integer font number by the PostScript program. This may be used to reencode the font with a different encoding vector (e.g. ISOLatin1Encoding). Typical values for this are contained in the ps.setfont.std and ps.setfont.latin1 datasets.
tempfile
character string to be used as a template for naming a file where the PostScript commands are to go. The first sequence of "#" characters will be replaced with a number in the generated filenames. For instance, the first file generated using a value of "ps.out.####.ps" will be "ps.out.0001.ps".
title
character string that will be used for the %%Title: header in the PostScript output. The default value is the string "S-PLUS Graphics". This can be used to help keep track of what is contained within each PostScript output file.
width
width of the plotting region in inches. width refers to the x axis dimension. The default values for width and height are determined by region.

SIDE EFFECTS:

Cause the currently active graphics device to update the controlling options for its embedded PostScript printer driver.

WARNINGS:

Some printer driving software may have an option to reverse the order of the pages being output to the printer. In that case, the software needs to understand the DSC headers that are present in the PostScript output. Some older software may not properly understand the headers at the default value for the dsc option. Using a ps.options(dsc=2) may resolve such problems. Evidence of this sort of problem may be in a log file for the specific printer in the form of an error message sent back from the printer. The message would probably be complaining about the usage of an undefined command.

SEE ALSO:

, , , , , , , , , , , , ,

EXAMPLES:

# Change the colors used by the PostScript driver 
ps.options.send (colors=ps.colors.rgb[c("red", "green", "blue"),]) 
# Approximate colors used by current motif/openlook driver 
ps.options.send (colors=xgetrgb('lines'), 
                 background=xgetrgb('background'), 
                 image.colors=xgetrgb('images')) 
# Use existing HSB color model specifications 
ps.options.send (colors=ps.hsb2rgb(my.hsb.ps.colors)) 
ps.options.send (colors=my.hsb.ps.colors, setcolor=ps.setcolor.hsb) 
# Change the bullet character to an asterisk 
ps.options.send (bullet=c("/IBu {Pch 0 (*) put SetPchSize} def", 
                          "/Bu {Pc} def")) 
# Change the bullet to a solidly filled semi-circle 
ps.options.send (bullet=c("/IBu {} def", 
   "/Bu {currentpoint gsave newpath", 
   "     PointSize 7 div Cex mul RastersPerPoint mul", 
   "     0 180 arc closepath fill grestore} def")) 
# Send all of the PostScript options 
ps.options.send (force=T) 
# Force assumption of a color PostScript printer 
ps.options.send (black.and.white="false") 
# Try to force use of legal size paper 
ps.options.send (paper='legal', extra.setup=c( 
    "%%BeginFeature: *PageSize Legal", 
    "legal", 
    "%%EndFeature"))