Class PanelGraphics

java.lang.Object
org.bzdev.swing.PanelGraphics
All Implemented Interfaces:
GraphicsCreator, OSGraphicsOps

public class PanelGraphics extends Object implements OSGraphicsOps
Class implementing output-stream graphics for a JPanel. This class implements the interface 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:


  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();
 
Alternatively, one may use the newFramedInstance method:

  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:


  import 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();
 
The graph will be displayed in the panel. If the frame was created so that it is not visible, one can call

      pg.setVisible(true);
 
or

      pg.getPanelWindow().setVisible(true);
 
to make it visible.

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.

  • 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 area
      targetHeight - the height of the drawing area
      requestAlpha - 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 area
      targetHeight - the height of the drawing area
      requestAlpha - true if the drawing area should be configured with an alpha channel; false otherwise
      isDoubleBuffered - true if the panel is double buffered; false otherwise.
    • PanelGraphics

      public PanelGraphics(int targetWidth, int targetHeight, boolean requestAlpha, LayoutManager layout)
      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 area
      targetHeight - the height of the drawing area
      requestAlpha - true if the drawing area should be configured with an alpha channel; false otherwise
      layout - 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 area
      targetHeight - the height of the drawing area
      requestAlpha - true if the drawing area should be configured with an alpha channel; false otherwise
      layout - the layout manager to use for the panel
      isDoubleBuffered - true if the panel is double buffered; false otherwise.
  • Method Details

    • setFlushImmediately

      public void setFlushImmediately(boolean mode)
      Determine if flush() 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 panel
      height - the height of the panel
      title - the frame title
      visible - true if the frame is visible; false otherwise
      exitOnClose - 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 panel
      height - the height of the panel
      title - the frame title
      visible - true if the frame is visible; false otherwise
      accessor - 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 is true.

      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 frame
      height - the height of the panel and frame
      title - the frame title
      visible - true if the frame is visible; false otherwise
      exitOnClose - 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 is true.

      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 frame
      height - the height of the panel and frame
      title - the frame title
      visible - true if the frame is visible; false otherwise
      accessor - 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

      public Window 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 interface OSGraphicsOps
      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 interface OSGraphicsOps
      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 interface OSGraphicsOps
      Returns:
      the height in user-space coordinates
    • setBackground

      public void setBackground(Color c)
      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

      public Color getBackground()
      Get the background color for the panel associated with this object.
      Returns:
      the background color
    • getPanel

      public JPanel getPanel()
      Get the JPanel associated with this instance.
      Returns:
      the panel
    • newPanelGraphicsCreator

      public PanelGraphics.Creator newPanelGraphicsCreator(boolean mode)
      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

      public PanelGraphics.Creator newPanelGraphicsCreator(boolean mode, int count)
      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 otherwise
      count - 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 method OSGraphicsOps.reset() is supported.
      Specified by:
      canReset in interface OSGraphicsOps
      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 interface OSGraphicsOps
    • setMode

      public void setMode(PanelGraphics.Mode mode)
      Set the mode
      Parameters:
      mode - the mode, as described by PanelGraphics.Mode
    • getMode

      public PanelGraphics.Mode getMode()
      Get the current mode
      Returns:
      the mode
    • write

      public void write(OSGraphicsOps osg) throws IOException
      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 be PanelGraphics.Mode.FIT (the default mode) or PanelGraphics.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

      public void print() throws PrinterException
      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 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.

      Throws:
      PrinterException - an error occurred while printing.
      See Also:
    • print

      public void print(boolean showDialog) throws PrinterException
      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

      public void print(PrinterJob job, PrintRequestAttributeSet aset) throws PrinterException
      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 job
      aset - a print-request attribute set
      Throws:
      PrinterException - an error occurred while printing.
      See Also:
    • createGraphics

      public Graphics2D createGraphics()
      Description copied from interface: OSGraphicsOps
      Get a graphics context for drawing. The graphics context created is not valid after OSGraphicsOps.flush() or OSGraphicsOps.reset() is called.
      Specified by:
      createGraphics in interface GraphicsCreator
      Specified by:
      createGraphics in interface OSGraphicsOps
      Returns:
      a new graphics context.
    • close

      public void close()
      Close resources. For this implementation of OSGraphicsOps, there is nothing to do.
      Specified by:
      close in interface OSGraphicsOps
    • getColorModel

      public ColorModel getColorModel()
      Description copied from interface: OSGraphicsOps
      Get the color model for the image that will be produced.
      Specified by:
      getColorModel in interface OSGraphicsOps
      Returns:
      the color model
    • flush

      public void flush() throws IOException
      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 interface OSGraphicsOps
      Throws:
      IOException - - if an IO exception occurred
      See Also:
    • imageComplete

      public void imageComplete() throws IOException
      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 method OSGraphicsOps.canReset() can be called to test if resets are allowed.

      Specified by:
      imageComplete in interface OSGraphicsOps
      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