- All Implemented Interfaces:
GraphicsCreator
,OSGraphicsOps
OSGraphicsOps
.
Instead of writing to an output stream, the graphics operations
will be performed on a JPanel, allowing the graphics to be viewed
on a display without first creating an image file.
When an instance of this class is created, one will specify a width
and height. This height and width will represent the width and
height of a rectangle, called the drawing area, in user space. The
origin of this rectangle is (0, 0). The drawing area may be scaled to
fit the current size of the associated JPanel
with the scaling depending on the mode
configured by calling setMode(PanelGraphics.Mode)
.
The default mode is PanelGraphics.Mode.FIT
.
The use-case that led to the creation of this class is that
of a Graph
that should be displayed on
a screen instead of being written to a file.
Users of this class will typically write the following code:
Alternatively, one may use the newFramedInstance method:import org.bzdev.swing.PanelGraphics; import javax.swing.JPanel; ... PanelGraphics pg = new PanelGraphics(...); JPanel panel = pg.getPanel(); // perform 'swing' operations on the panel. ... // create the graphics to be displayed Graphics2D g2d = pg.createGraphics(); ... // display the results pg.imageComplete();
import org.bzdev.swing.PanelGraphics; import javax.swing.JPanel; ... PanelGraphics pg = PanelGraphics.newFramedInstance(...); ... // create the graphics to be displayed Graphics2D g2d = pg.createGraphics(); ... // display the results pg.imageComplete();
To create a graph, one can use the following statements:
The graph will be displayed in the panel. If the frame was created so that it is not visible, one can callimport org.bzdev.swing.PanelGraphics; import org.bzdev.graph.*; import javax.swing.JPanel; ... PanelGraphics pg = PanelGraphics.newFramedInstance(...); Graph graph = new Graph(pg); // perform normal graph operations to create the graph ... graph.write();
orpg.setVisible(true);
to make it visible.pg.getPanelWindow().setVisible(true);
While the PanelGraphics class has Java 'swing' components associated with it, the constructors and the newFramedInstance methods are thread safe - their use is not restricted to the event dispatch thread. Consequently, it is easy to create a command-line program that will open a window to display its output and exit when that window is closed.
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionclass
Off-screen GraphicsCreator.static class
Class to determine how an application can exit,even when a security manager is installed, given a window created withnewFramedInstance(int,int,String,boolean,ExitAccessor)
is closed.static enum
PanelGraphics modes. -
Constructor Summary
ConstructorsConstructorDescriptionPanelGraphics
(int targetWidth, int targetHeight, boolean requestAlpha) Constructor with default JPanel options.PanelGraphics
(int targetWidth, int targetHeight, boolean requestAlpha, boolean isDoubleBuffered) Constructor with double-buffering option.PanelGraphics
(int targetWidth, int targetHeight, boolean requestAlpha, LayoutManager layout) Constructor specifying a layout manager.PanelGraphics
(int targetWidth, int targetHeight, boolean requestAlpha, LayoutManager layout, boolean isDoubleBuffered) Constructor specifying a layout manager and a double-buffer option. -
Method Summary
Modifier and TypeMethodDescriptionboolean
canReset()
Test if the methodOSGraphicsOps.reset()
is supported.void
close()
Close resources.Get a graphics context for drawing.void
Dispose this PanelGraphic's window if that was created by a call to newFramedInstance.void
flush()
Flush the output.Get the background color for the panel associated with this object.Get the color model for the image that will be produced.int
Get the image height parameter in user space.getMode()
Get the current modegetPanel()
Get the JPanel associated with this instance.Find the top-level container for the panel associated with this object and return non-null if the container is a Window.int
getWidth()
Get the image width parameter in user space.void
Final processing for writing an image file to the output stream.boolean
Determine if the window containing the panel associated with this instance of PanelGraphics is visible.static PanelGraphics
newFramedInstance
(int width, int height, String title, boolean visible, boolean exitOnClose) Create an instance of PanelGraphics with the associated panel in a frame.static PanelGraphics
newFramedInstance
(int width, int height, String title, boolean visible, boolean exitOnClose, boolean addButtons) Create an instance of PanelGraphics with the associated panel in a frame, optionally adding Print and Save-As buttons.static PanelGraphics
newFramedInstance
(int width, int height, String title, boolean visible, PanelGraphics.ExitAccessor accessor) Create an instance of PanelGraphics with the associated panel in a frame with the exit mode determined by an exit accessor.static PanelGraphics
newFramedInstance
(int width, int height, String title, boolean visible, PanelGraphics.ExitAccessor accessor, boolean addButtons) Create an instance of PanelGraphics with the associated panel in a frame with the exit mode determined by an ExitAccessor, optionally adding Print and Save-As buttons.newPanelGraphicsCreator
(boolean mode) Create a new set of graphics contexts.newPanelGraphicsCreator
(boolean mode, int count) Create a new set of graphics contexts with a repetition count.void
print()
Print this object using the default printer.void
print
(boolean showDialog) Print this object, optionally displaying a dialog box that allows a user to choose a printer.void
print
(PrinterJob job, PrintRequestAttributeSet aset) Print this object given a printer job and attribute set.boolean
Determine if this instance is requesting an alpha channel.void
reset()
Reset the panel so that its contents are empty and clear any existing graphics operations.void
Set the background color for the panel associated with this object.void
setFlushImmediately
(boolean mode) Determine ifflush()
method immediately updates the display or if the update occurs with normal processing delay.void
setMode
(PanelGraphics.Mode mode) Set the modevoid
setVisible
(boolean visible) Set the visibility of the panel associated with this PanelGraphics.void
write
(OSGraphicsOps osg) Write the image that this object generates to a stream.
-
Constructor Details
-
PanelGraphics
public PanelGraphics(int targetWidth, int targetHeight, boolean requestAlpha) Constructor with default JPanel options. The drawing area is specified by the parameters targetWidth, targetHeight, and preferAlpha.- Parameters:
targetWidth
- the width of the drawing areatargetHeight
- the height of the drawing arearequestAlpha
- true if the drawing area should be configured with an alpha channel; false otherwise
-
PanelGraphics
public PanelGraphics(int targetWidth, int targetHeight, boolean requestAlpha, boolean isDoubleBuffered) Constructor with double-buffering option. The drawing area is specified by the parameters targetWidth, targetHeight, and preferAlpha. The isDoubleBuffered argument is used to construct the panel.- Parameters:
targetWidth
- the width of the drawing areatargetHeight
- the height of the drawing arearequestAlpha
- true if the drawing area should be configured with an alpha channel; false otherwiseisDoubleBuffered
- true if the panel is double buffered; false otherwise.
-
PanelGraphics
Constructor specifying a layout manager. The drawing area is specified by the parameters targetWidth, targetHeight, and preferAlpha. The layout argument is used to construct the panel.- Parameters:
targetWidth
- the width of the drawing areatargetHeight
- the height of the drawing arearequestAlpha
- true if the drawing area should be configured with an alpha channel; false otherwiselayout
- the layout manager to use for the panel
-
PanelGraphics
public PanelGraphics(int targetWidth, int targetHeight, boolean requestAlpha, LayoutManager layout, boolean isDoubleBuffered) Constructor specifying a layout manager and a double-buffer option. The drawing area is specified by the parameters targetWidth, targetHeight, and preferAlpha. The layout and isDoubleBuffered arguments are used to construct the panel.- Parameters:
targetWidth
- the width of the drawing areatargetHeight
- the height of the drawing arearequestAlpha
- true if the drawing area should be configured with an alpha channel; false otherwiselayout
- the layout manager to use for the panelisDoubleBuffered
- true if the panel is double buffered; false otherwise.
-
-
Method Details
-
setFlushImmediately
public void setFlushImmediately(boolean mode) Determine ifflush()
method immediately updates the display or if the update occurs with normal processing delay.When true the JComponent method
JComponent.paintImmediately(java.awt.Rectangle)
- Parameters:
mode
- true if the flush operation should occur immediately; false if normal processing delays are acceptable.
-
disposeFrame
public void disposeFrame()Dispose this PanelGraphic's window if that was created by a call to newFramedInstance. -
newFramedInstance
public static PanelGraphics newFramedInstance(int width, int height, String title, boolean visible, boolean exitOnClose) Create an instance of PanelGraphics with the associated panel in a frame. The dimensions provided by the first two arguments are the dimensions of the panel that displays the graphics that will be created through the use of this class. The frame will be larger to allow room for some buttons, combo boxes, labels, and text fields.This method is particularly useful for simple applications in which one wants a window to display something, perhaps a graph, but where a full-fledged GUI is not needed.
- Parameters:
width
- the width of the panelheight
- the height of the paneltitle
- the frame titlevisible
- true if the frame is visible; false otherwiseexitOnClose
- true if the application should exit when the frame closes; false if the frame should be hidden.- Returns:
- the new instance of PanelGraphics
-
newFramedInstance
public static PanelGraphics newFramedInstance(int width, int height, String title, boolean visible, PanelGraphics.ExitAccessor accessor) Create an instance of PanelGraphics with the associated panel in a frame with the exit mode determined by an exit accessor. The dimensions provided by the first two arguments are the dimensions of the panel that displays the graphics that will be created through the use of this class. The frame will be larger to allow room for some buttons, combo boxes, labels, and text fields.This method is particularly useful for simple applications in which one wants a window to display something, perhaps a graph, but where a full-fledged GUI is not needed.
- Parameters:
width
- the width of the panelheight
- the height of the paneltitle
- the frame titlevisible
- true if the frame is visible; false otherwiseaccessor
- an exit accessor that determines if the frame will ask the user if the application should exit before exiting the application; null implies that the application will exit immediately.- Returns:
- the new instance of PanelGraphics
-
newFramedInstance
public static PanelGraphics newFramedInstance(int width, int height, String title, boolean visible, boolean exitOnClose, boolean addButtons) Create an instance of PanelGraphics with the associated panel in a frame, optionally adding Print and Save-As buttons. The dimensions provided by the first two arguments are the dimensions of the panel that displays the graphics that will be created through the use of this class. The frame will be larger to allow room for some buttons, combo boxes, labels, and text fields when the addButtons argument istrue
.This method is particularly useful for simple applications in which one wants a window to display something, perhaps a graph, but where a full-fledged GUI is not needed.
- Parameters:
width
- the width of the panel and frameheight
- the height of the panel and frametitle
- the frame titlevisible
- true if the frame is visible; false otherwiseexitOnClose
- true if the application should exit when the frame closes; false if the frame should be hidden.addButtons
- true if the frame should include buttons for printing and writing to files; false otherwise- Returns:
- the new instance of PanelGraphics
-
newFramedInstance
public static PanelGraphics newFramedInstance(int width, int height, String title, boolean visible, PanelGraphics.ExitAccessor accessor, boolean addButtons) Create an instance of PanelGraphics with the associated panel in a frame with the exit mode determined by an ExitAccessor, optionally adding Print and Save-As buttons. The dimensions provided by the first two arguments are the dimensions of the panel that displays the graphics that will be created through the use of this class. The frame will be larger to allow room for some buttons, combo boxes, labels, and text fields when the addButtons argument istrue
.This method is particularly useful for simple applications in which one wants a window to display something, perhaps a graph, but where a full-fledged GUI is not needed.
- Parameters:
width
- the width of the panel and frameheight
- the height of the panel and frametitle
- the frame titlevisible
- true if the frame is visible; false otherwiseaccessor
- an exit accessor that determines if the frame will ask the user if the application should exit before exiting the application; null implies that the application will exit immediately.addButtons
- true if the frame should include buttons for printing and writing to files; false otherwise- Returns:
- the new instance of PanelGraphics
-
getPanelWindow
Find the top-level container for the panel associated with this object and return non-null if the container is a Window.- Returns:
- the window; null if there is none
-
setVisible
public void setVisible(boolean visible) Set the visibility of the panel associated with this PanelGraphics. This method has no effect if the panel is not contained in a window.- Parameters:
visible
- true if the panel should be visible; false otherwise
-
isVisible
public boolean isVisible()Determine if the window containing the panel associated with this instance of PanelGraphics is visible.- Returns:
- true if it is visible; false if it is not visible or if the panel is not contained within a window
-
requestsAlpha
public boolean requestsAlpha()Description copied from interface:OSGraphicsOps
Determine if this instance is requesting an alpha channel. The value may be changed from that provided in the constructor due to the capabilities of a particular image format.- Specified by:
requestsAlpha
in interfaceOSGraphicsOps
- Returns:
- true if an alpha channel is requested; false otherwise
-
getWidth
public int getWidth()Description copied from interface:OSGraphicsOps
Get the image width parameter in user space. Unless a graphics context is modified, this value represents an upper bound on the X coordinate of points that will appear in the image in the coordinate system used by the graphics context independent of the orientation.The parameter typically refers to some object such as a buffered image so that the value returned by this method is constant.
- Specified by:
getWidth
in interfaceOSGraphicsOps
- Returns:
- the width in user-space coordinates
-
getHeight
public int getHeight()Description copied from interface:OSGraphicsOps
Get the image height parameter in user space. Unless a graphics context is modified, this value represents an upper bound on the Y coordinate of points that will appear in the image in the coordinate system used by the graphics context independent of the orientation.The parameter typically refers to some object such as a buffered image so that the value returned by this method is constant.
- Specified by:
getHeight
in interfaceOSGraphicsOps
- Returns:
- the height in user-space coordinates
-
setBackground
Set the background color for the panel associated with this object.- Parameters:
c
- the color; null if the color of the panel's parent should be used
-
getBackground
Get the background color for the panel associated with this object.- Returns:
- the background color
-
getPanel
Get the JPanel associated with this instance.- Returns:
- the panel
-
newPanelGraphicsCreator
Create a new set of graphics contexts.- Parameters:
mode
- true if the object created will be used after its apply method is called; false otherwise- Returns:
- a graphics creator
-
newPanelGraphicsCreator
Create a new set of graphics contexts with a repetition count. The value of the repetition count can be used in animations to indicate the number of times a frame should be repeated.- Parameters:
mode
- true if the object created will be used after its app method is called; false otherwisecount
- a positive integer giving the repetition count- Returns:
- a graphics creator
- See Also:
-
canReset
public boolean canReset()Description copied from interface:OSGraphicsOps
Test if the methodOSGraphicsOps.reset()
is supported.- Specified by:
canReset
in interfaceOSGraphicsOps
- Returns:
- true if
OSGraphicsOps.reset()
is supported; false otherwise
-
reset
public void reset()Reset the panel so that its contents are empty and clear any existing graphics operations. It is the caller's responsibility to make sure that all graphics contexts previously created by this instance of PanelGraphics are not used subsequently. .- Specified by:
reset
in interfaceOSGraphicsOps
-
setMode
Set the mode- Parameters:
mode
- the mode, as described byPanelGraphics.Mode
-
getMode
Get the current mode- Returns:
- the mode
-
write
Write the image that this object generates to a stream. The orientation of the image is determined by the OutputStreamGraphics argument. The mode determines how this object is scaled. If the full image is to appear in the output stream, the mode should bePanelGraphics.Mode.FIT
(the default mode) orPanelGraphics.Mode.FILL
: otherwise part of the image might be lost.- Parameters:
osg
- the object managing the output stream- Throws:
IOException
- an IO error occurred- See Also:
-
print
Print this object using the default printer. If error messages (e.g., due to a printer not being available) should be shown in a dialog box, the methodSwingErrorMessage.setComponent(java.awt.Component)
must be called with a non-null argument.Note: this method will print the object on a single page, scaling or truncating the image as specified by the mode set by this instance of PanelGraphics.
- Throws:
PrinterException
- an error occurred while printing.- See Also:
-
print
Print this object, optionally displaying a dialog box that allows a user to choose a printer. A dialog will be created to allow the user to choose a printer.If showDialog is false, and error messages (e.g., due to a printer not being available) should be shown in a dialog box, the method
SwingErrorMessage.setComponent(java.awt.Component)
must be called with a non-null argument.Note: this method will print the object on a single page, scaling or truncating the image as specified by the mode set by this instance of PanelGraphics. The orientation used for printing (portrait or landscape) will be set so that the printed image is as large as possible, but when a printing dialog is displayed, the user can override this choice. For more fine-grained control over the printing process when a printing dialog box is not displayed, use the method
print(PrinterJob,PrintRequestAttributeSet)
.- Parameters:
showDialog
- true if a dialog box allowing the user to choose a printer should be displayed; false to use the default.- Throws:
PrinterException
- an error occurred while printing.- See Also:
-
print
Print this object given a printer job and attribute set. This method is provided for the case where the caller determines the printer and the attributes used for printing.Note: this method will print the object on a single page, scaling or truncating the image as specified by the mode set by this instance of PanelGraphics. If the caller has not requested an orientation (e.g., portrait or landscape), the orientation will be set so that the printed image is as large as possible.
- Parameters:
job
- a printer jobaset
- a print-request attribute set- Throws:
PrinterException
- an error occurred while printing.- See Also:
-
createGraphics
Description copied from interface:OSGraphicsOps
Get a graphics context for drawing. The graphics context created is not valid afterOSGraphicsOps.flush()
orOSGraphicsOps.reset()
is called.- Specified by:
createGraphics
in interfaceGraphicsCreator
- Specified by:
createGraphics
in interfaceOSGraphicsOps
- Returns:
- a new graphics context.
-
close
public void close()Close resources. For this implementation ofOSGraphicsOps
, there is nothing to do.- Specified by:
close
in interfaceOSGraphicsOps
-
getColorModel
Description copied from interface:OSGraphicsOps
Get the color model for the image that will be produced.- Specified by:
getColorModel
in interfaceOSGraphicsOps
- Returns:
- the color model
-
flush
Description copied from interface:OSGraphicsOps
Flush the output. This method will provide a partial image or partial graphics if possible or feasible. After this method is called, the user must not use graphics contexts that were previously created. Whether this method performs any action depends on the implementation of each class or subclass implementing this interface.- Specified by:
flush
in interfaceOSGraphicsOps
- Throws:
IOException
- - if an IO exception occurred- See Also:
-
imageComplete
Description copied from interface:OSGraphicsOps
Final processing for writing an image file to the output stream. This method does not close an IO stream, but will flush it.Subclasses should implement this method so that it throws an exception if called multiple times without a successful intervening call to
OSGraphicsOps.reset()
. The methodOSGraphicsOps.canReset()
can be called to test if resets are allowed.- Specified by:
imageComplete
in interfaceOSGraphicsOps
- Throws:
IOException
- IO failure, or a PrintException (which will be provided as the cause of the IOException), or an indication that this method was called multiple times
-