Java Graphics Device

DESCRIPTION:

Creates a graphics window compatible with Java-enabled S-PLUS.

USAGE:

java.graph(file="", format="", width=-1, height=-1,
           colorscheme=java.colorscheme.default,
           jpeg.quality=1., png.color="color", ...)

OPTIONAL ARGUMENTS:

file
character string naming a bitmap format graphics file. If this is the empty string "" (the default), a java.graph device is displayed on screen. If the file argument is a string that does not contain the character #, only one bitmap file is created, containing the last graphic created before closing the device. If the string contains one or more consecutive # characters, these characters are replaced with numbers to create multiple output files, each containing one page of graphic output.
format
character string giving the bitmap format. Allowable strings are "JPEG", "TIFF", "PNG" (for Portable Network Graphics, an alternative to GIF), "PNM" (for Portable Any Map), "BMP" (Windows bitmap format), or "SPJ" (S-PLUS graphlet files). If file is specified and format is omitted, the file extension will be interpreted. If file is specified and format is anything else, JPEG is created by default.
width
width of the device in pixels. The default -1 results in a Window approximately six inches wide.
height
height of the device in pixels. The default -1 results in a window approximately four inches high.
colorscheme
character string giving the initial color scheme to be used for this instance of the device. This argument is ignored unless either use.device.palette(TRUE) or use.legacy.graphics(TRUE) has been called. S-PLUS uses a global color palette and global image color palette.

The pre-defined color schemes are stored in variables named:

           java.colorscheme.default
           java.colorscheme.standard
           java.colorscheme.trellis
           java.colorscheme.trellis.black.on.white
           java.colorscheme.white.on.black
           java.colorscheme.cyan.magenta
           java.colorscheme.topographical
           java.colorscheme.user.1
           java.colorscheme.user.2

jpeg.quality
number in the range 0.0 to 1.0 specifying the quality of JPEG output. Higher values (toward 1.0) produce larger JPEG files.
png.color
a character string specifying the color map for PNG output. This argument is ignored unless either use.device.palette(TRUE) or use.legacy.graphics(TRUE) has been called. S-PLUS uses a global color palette and global image color palette.

This can be any of the following strings: "gray1", "gray2", "gray4", "gray8", or "color". (The alternate spellings "grey" and "colour" are also recognized.) The option "gray1" gives black and white output.

VALUE:

NULL.

SIDE EFFECTS:

if called with no arguments, or just the width and/or height arguments, java.graph opens a new graphics window and makes it the current device. Subsequent graphics commands are directed to this device until it is closed or another device is made current. If called with the file argument, java.graph does not open a new graphics window, but instead directs the graphics output to a file in the appropriate format. All the bitmap formats except "SPJ" store only a single graph--the last one displaying when dev.off is called. The "SPJ" file can contain multiple graphs in a single file.

DETAILS:

If Java is not already running when java.graph is called, it is automatically started.

On Windows, the winspj library contains another version of java.graph that only supports the creation of "SPJ" files, without using java.

Use java.graph() to open a device and dev.off() to close a device. When creating a file, the file is not created until dev.off() is called.

The java.graph device supports the normal graphics drawing commands, as well as locator (described below). The advanced interactive commands like spin and brush are not currently supported. The printgraph() command is not currently supported: the same functionality can be achieved using the postscript device.

The java.graph device supports the lty= and font= graphics parameters to display different types of dashed lines and fonts. The set of dashed line types and fonts cannot be changed. The java.graph device also supports the col= graphics parameter to change the colors of lines. The colors used can be changed programmatically as described below.

When the locator function is called on a java.graph device, a dialog pops up telling you to select points. Left-click on the graph to select points. To stop selecting points, right-click on the graph, or select the "OK" button in the locator dialog. The dialog displays these instructions, as well as the current mouse position within the graph. The identify function, which calls locator, is handled the same way.

The java.graph device maintains the aspect ratio of the graph to the values specified for width and height. If the window is reshaped, gray borders appear at the sides, top, and bottom, to indicate the real graph region. The aspect ratio is also maintained when printing or saving to a bitmap image, but the borders are not displayed.

By default, S-PLUS uses a global color palette and global image color palette to map color indices to specific colors. Color arguments can have integer values that map into the color palette, or they can be specified by RGB (or RGBA) values or color names. An RGBA value is a hexadecimal representation of color where the red, green, blue, and alpha channel, or transparency, values are specified. The java.graph device supports color transparency for PNG and TIFF formats only. For more information on color specification, see the chapter "Graphics Enhancements" in the Guide to Graphics.

If either use.device.palette(TRUE) or use.legacy.graphics(TRUE) has been called, then the color scheme is set by the colorscheme argument, and each java.graph device has a color scheme that determines the color of the background, the colors of lines, text, etc., and the colors of image bitmaps. There is a single color palette used for lines, text, symbols, and polygons. For details on using, modifying, and defining color schemes, see the section "Device-Specific Color Specification" in the Guide to Graphics.

SEE ALSO:

See the chapter "S-PLUS Graphic Device Support" in the Guide to Graphics. , , , .

EXAMPLES:

# Create graphics interactively
java.graph()
plot(fuel.frame$Weight, fuel.frame$Mileage)
dev.off()

# Create BMP graphics file
java.graph("mileage.bmp", format="BMP")
plot(fuel.frame$Weight, fuel.frame$Mileage)
dev.off()

# Create draft-quality JPEG graphics file
java.graph("mileage.jpeg", format="JPEG",
           jpeg.quality=0.80)
plot(fuel.frame$Weight, fuel.frame$Mileage)
dev.off()

# Create Trellis graphics
trellis.device(java.graph)
xyplot(Mileage ~ Weight | Type, fuel.frame)
dev.off()

# Create a S-PLUS Graphlet data file that displays
# the row name when the mouse is over a point.
java.graph("fuel.spj", format="SPJ")
plot(fuel.frame[["Weight"]], fuel.frame[["Fuel"]])
java.identify(fuel.frame[["Weight"]],
              fuel.frame[["Fuel"]],
              labels=dimnames(fuel.frame)[[1]])
title("Move mouse over a point to see the element name")
dev.off()