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:
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.
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 accomodate older software that may need to interpret those headers. It's 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.
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:
ps.options , printgraph , postscript , ps.setfont.std, ps.setfont.latin1 , ps.paper.regions , ps.colors.rgb, rgb2matrix , ps.hsb2rgb , ps.rgb2hsb , ps.setcolor.rgb, ps.setcolor.hsb , ps.preamble.std , xgetrgb
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"))