Package org.jdesktop.swingx

Class JXGraph

java.lang.Object
java.awt.Component
java.awt.Container
javax.swing.JComponent
javax.swing.JPanel
org.jdesktop.swingx.JXPanel
org.jdesktop.swingx.JXGraph
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible, Scrollable
@JavaBean public class JXGraph extends JXPanel

JXGraph provides a component which can display one or more plots on top of a graduated background (or grid.)

User input

To help analyze the plots, this component allows the user to pan the view by left-clicking and dragging the mouse around. Using the mouse wheel, the user is also able to zoom in and out. Clicking the middle button resets the view to its original position.

All user input can be disabled by calling setInputEnabled(boolean) and passing false. This does not prevent subclasses from registering their own event listeners, such as mouse or key listeners.

Initializing the component and setting the view

Whenever a new instance of this component is created, the grid boundaries, or view, must be defined. The view is comprised of several elements whose descriptions are the following:

  • minX: Minimum value initially displayed by the component on the X axis (horizontally.)
  • minY: Minimum value initially displayed by the component on the Y axis (vertically.)
  • maxX: Maximum value initially displayed by the component on the X axis (horizontally.)
  • maxY: Maximum value initially displayed by the component on the Y axis (vertically.)
  • originX: Origin on the X axis of the vertical axis.
  • originY: Origin on the Y axis of the horizontal axis.
  • majorX: Distance between two major vertical lines of the grid.
  • majorY: Distance between two major horizontal lines of the grid.
  • minCountX: Number of minor vertical lines between two major vertical lines in the grid.
  • minCountY: Number of minor horizontal lines between two major horizontal lines in the grid.

View and origin

The default constructor defines a view bounds by -1.0 and +1.0 on both axis, and centered on an origin at (0, 0).

To simplify the API, the origin can be read and written with a Point2D instance (see getOrigin() and setOrigin(Point2D).)

Likewise, the view can be read and written with a Rectangle2D instance (see getView() and setView(Rectangle2D).) In this case, you need not to define the maximum boundaries of the view. Instead, you need to set the origin of the rectangle as the minimum boundaries. The width and the height of the rectangle define the distance between the minimum and maximum boundaries. For instance, to set the view to minX=-1.0, maxX=1.0, minY=-1.0 and maxY=1.0 you can use the following rectangle:

new Rectangle2D.Double(-1.0d, -1.0d, 2.0d, 2.0d);

You can check the boundaries by calling Rectangle2D.getMaxX() and Rectangle2D.getMaxY() once your rectangle has been created.

Alternatively, you can set the view and the origin at the same time by calling the method setViewAndOrigin(Rectangle2D). Calling this method will set the origin so as to center it in the view defined by the rectangle.

Grid lines

By default, the component defines a spacing of 0.2 units between two major grid lines. It also defines 4 minor grid lines between two major grid lines. The spacing between major grid lines and the number of minor grid lines can be accessed through the getters getMajorX(), getMajorY(), getMinorCountX() and getMinorCountY().

You can change the number of grid lines at runtime by calling the setters setMajorX(double), setMajorY(double), setMinorCountX(int) and setMinorCountY(int).

Appearance

Although it provides sensible defaults, this component lets you change its appearance in several ways. It is possible to modify the colors of the graph by calling the setters setAxisColor(Color), setMajorGridColor(Color) and setMinorGridColor(Color).

You can also enable or disable given parts of the resulting graph by calling the following setters:

Usage example

The following code snippet creates a new graph centered on (0, 0), bound to the view [-1.0 1.0 -1.0 1.0], with a major grid line every 0.5 units and a minor grid line count of 5:

 Point2D origin = new Point2D.Double(0.0d, 0.0d);
 Rectangle2D view = new Rectangle2D.Double(-1.0d, 1.0d, 2.0d, 2.0d);
 JXGraph graph = new JXGraph(origin, view, 0.5d, 5, 0.5d, 5);

Plots

Definition

A plot is defined by a mathematical transformation that, given a value on the graph's X axis, returns a value on the Y axis. The component draws the result by plotting a spot of color at the coordinates defined by (X, f(X)) where f() is the aforementionned mathematical transformation. Given the following transformation:

 f(X) = X * 2.0

For X=1.0, the component will show a spot of color at the coordinates (1.0, 2.0).

Creating a new plot

Every plot drawn by the component must be a subclass of JXGraph.Plot. This abstract public class defines a single method to be implemented by its children:

 public double compute(double value)

The previous example can be defined by a concrete JXGraph.Plot as follow:

 class TwiceTheValuePlot extends JXGraph.Plot {
     public double compute(double value) {
         return value * 2.0d;
     }
 }

Most of the time though, a plot requires supplementary parameters. For instance, let's define the X axis of your graph as the mass of an object. To compute the weight of the object given its mass, you need to use the acceleration of gravity (w=m*g where g is the acceleration.) To let the user modify this last parameter, to compute his weight at the surface of the moon for instance, you need to add a parameter to your plot.

While JXGraph.Plot does not give you an API for such a purpose, it does define an event dispatching API (see Component.firePropertyChange(String, double, double).) Whenever a plot is added to the graph, the component registers itself as a property listener of the plot. If you take care of firing events whenever the user changes a parameter of your plot, the graph will automatically update its display. While not mandatory, it is highly recommended to leverage this API.

Adding and removing plots to and from the graph

To add a plot to the graph, simply call the method addPlots(Color, JXGraph.Plot...). You can use it to add one or more plots at the same time and associate them with a color. This color is used when drawing the plots:

 JXGraph.Plot plot = new TwiceTheValuePlot();
 graph.addPlots(Color.BLUE, plot);

These two lines will display our previously defined plot in blue on screen. Removing one or several plots is as simple as calling the method removePlots(JXGraph.Plot...). You can also remove all plots at once with removeAllPlots().

Painting more information

How to draw on the graph

If you need to add more information on the graph you need to extend it and override the method paintExtra(Graphics2D). This method has a default empty implementation and is called after everything has been drawn. Its sole parameter is a reference to the component's drawing surface, as configured by setupGraphics(Graphics2D). By default, the setup method activates antialising but it can be overriden to change the drawing surface. (Translation, rotation, new rendering hints, etc.)

Getting the right coordinates

To properly draw on the graph you will need to perform a translation between the graph's coordinates and the screen's coordinates. The component defines 4 methods to assist you in this task:

If you have defined a graph view centered on the origin (0, 0), the origin of the graph will be at the exact center of the screen. That means the world coordinates (0, 0) are equivalent to the pixel coordinates (width / 2, height / 2). Thus, calling xPositionToPixel(0.0d) would give you the same value as the expression getWidth() / 2.0d.

Converting from world coordinates to pixel coordinates is mostly used to draw the result of a mathematical transformation. Converting from pixel coordinates to world coordinates is mostly used to get the position in the world of a mouse event.

Author:
Romain Guy romain.guy@mac.com
See Also:

  • Constructor Details

    • JXGraph

      public JXGraph()

      Creates a new graph display. The following properties are automatically set:

      • view: -1.0 to +1.0 on both axis
      • origin: At (0, 0)
      • grid: Spacing of 0.2 between major lines; minor lines count is 4

    • JXGraph

      public JXGraph(Rectangle2D view)

      Creates a new graph display with the specified view. The following properties are automatically set:

      • origin: Center of the specified view
      • grid: Spacing of 0.2 between major lines; minor lines count is 4
      Parameters:
      view - the rectangle defining the view boundaries

    • JXGraph

      public JXGraph(Rectangle2D view, double majorX, int minorCountX, double majorY, int minorCountY)

      Creates a new graph display with the specified view and grid lines. The origin is set at the center of the view.

      Parameters:
      view - the rectangle defining the view boundaries
      majorX - the spacing between two major grid lines on the X axis
      minorCountX - the number of minor grid lines between two major grid lines on the X axis
      majorY - the spacing between two major grid lines on the Y axis
      minorCountY - the number of minor grid lines between two major grid lines on the Y axis
      Throws:
      IllegalArgumentException - if minX ≥ maxX or minY ≥ maxY or minorCountX < 0 or minorCountY < 0 or majorX ≤ 0.0 or majorY ≤ 0.0

    • JXGraph

      public JXGraph(Point2D origin, Rectangle2D view)

      Creates a new graph display with the specified view and origin. The following properties are automatically set:

      • grid: Spacing of 0.2 between major lines; minor lines count is 4
      Parameters:
      origin - the coordinates of the main axis origin
      view - the rectangle defining the view boundaries

    • JXGraph

      public JXGraph(Point2D origin, Rectangle2D view, double majorX, int minorCountX, double majorY, int minorCountY)

      Creates a new graph display with the specified view, origin and grid lines.

      Parameters:
      origin - the coordinates of the main axis origin
      view - the rectangle defining the view boundaries
      majorX - the spacing between two major grid lines on the X axis
      minorCountX - the number of minor grid lines between two major grid lines on the X axis
      majorY - the spacing between two major grid lines on the Y axis
      minorCountY - the number of minor grid lines between two major grid lines on the Y axis
      Throws:
      IllegalArgumentException - if minX ≥ maxX or minY ≥ maxY or minorCountX < 0 or minorCountY < 0 or majorX ≤ 0.0 or majorY ≤ 0.0

    • JXGraph

      public JXGraph(double originX, double originY, double minX, double maxX, double minY, double maxY, double majorX, int minorCountX, double majorY, int minorCountY)

      Creates a new graph display with the specified view, origin and grid lines.

      Parameters:
      originX - the coordinate of the major X axis
      originY - the coordinate of the major Y axis
      minX - the minimum coordinate on the X axis for the view
      maxX - the maximum coordinate on the X axis for the view
      minY - the minimum coordinate on the Y axis for the view
      maxY - the maximum coordinate on the Y axis for the view
      majorX - the spacing between two major grid lines on the X axis
      minorCountX - the number of minor grid lines between two major grid lines on the X axis
      majorY - the spacing between two major grid lines on the Y axis
      minorCountY - the number of minor grid lines between two major grid lines on the Y axis
      Throws:
      IllegalArgumentException - if minX ≥ maxX or minY ≥ maxY or minorCountX < 0 or minorCountY < 0 or majorX ≤ 0.0 or majorY ≤ 0.0

  • Method Details

    • isOpaque

      public boolean isOpaque()
      Overrides:
      isOpaque in class JXPanel

    • setEnabled

      public void setEnabled(boolean enabled)
      Overrides:
      setEnabled in class JComponent
      See Also:

    • setInputEnabled

      public void setInputEnabled(boolean enabled)

      Enables or disables user input on the component. When user input is enabled, panning, zooming and view resetting. Disabling input will prevent the user from modifying the currently displayed view.

      Calling setEnabled(boolean) disables the component in the Swing hierarchy and invokes this method.

      Parameters:
      enabled - true if user input must be enabled, false otherwise
      See Also:

    • isInputEnabled

      public boolean isInputEnabled()

      Defines whether or not user input is accepted and managed by this component. The component is always created with user input enabled.

      Returns:
      true if user input is enabled, false otherwise
      See Also:

    • isTextPainted

      public boolean isTextPainted()

      Defines whether or not axis labels are painted by this component. The component is always created with text painting enabled.

      Returns:
      true if axis labels are painted, false otherwise
      See Also:

    • setTextPainted

      public void setTextPainted(boolean textPainted)

      Enables or disables the painting of axis labels depending on the value of the parameter. Text painting is enabled by default.

      Parameters:
      textPainted - if true, axis labels are painted
      See Also:

    • isGridPainted

      public boolean isGridPainted()

      Defines whether or not grids lines are painted by this component. The component is always created with grid lines painting enabled.

      Returns:
      true if grid lines are painted, false otherwise
      See Also:

    • setGridPainted

      public void setGridPainted(boolean gridPainted)

      Enables or disables the painting of grid lines depending on the value of the parameter. Grid painting is enabled by default.

      Parameters:
      gridPainted - if true, axis labels are painted
      See Also:

    • isAxisPainted

      public boolean isAxisPainted()

      Defines whether or not the graph main axis is painted by this component. The component is always created with main axis painting enabled.

      Returns:
      true if main axis is painted, false otherwise
      See Also:

    • setAxisPainted

      public void setAxisPainted(boolean axisPainted)

      Enables or disables the painting of main axis depending on the value of the parameter. Axis painting is enabled by default.

      Parameters:
      axisPainted - if true, axis labels are painted
      See Also:

    • isBackgroundPainted

      public boolean isBackgroundPainted()

      Defines whether or not the background painted by this component. The component is always created with background painting enabled. When background painting is disabled, background painting is deferred to the parent class.

      Returns:
      true if background is painted, false otherwise
      See Also:

    • setBackgroundPainted

      public void setBackgroundPainted(boolean backPainted)

      Enables or disables the painting of background depending on the value of the parameter. Background painting is enabled by default.

      Parameters:
      backPainted - if true, axis labels are painted
      See Also:

    • getMajorGridColor

      public Color getMajorGridColor()

      Gets the major grid lines color of this component.

      Returns:
      this component's major grid lines color
      See Also:

    • setMajorGridColor

      public void setMajorGridColor(Color majorGridColor)

      Sets the color of major grid lines on this component. The color can be translucent.

      Parameters:
      majorGridColor - the color to become this component's major grid lines color
      Throws:
      IllegalArgumentException - if the specified color is null
      See Also:

    • getMinorGridColor

      public Color getMinorGridColor()

      Gets the minor grid lines color of this component.

      Returns:
      this component's minor grid lines color
      See Also:

    • setMinorGridColor

      public void setMinorGridColor(Color minorGridColor)

      Sets the color of minor grid lines on this component. The color can be translucent.

      Parameters:
      minorGridColor - the color to become this component's minor grid lines color
      Throws:
      IllegalArgumentException - if the specified color is null
      See Also:

    • getAxisColor

      public Color getAxisColor()

      Gets the main axis color of this component.

      Returns:
      this component's main axis color
      See Also:

    • setAxisColor

      public void setAxisColor(Color axisColor)

      Sets the color of main axis on this component. The color can be translucent.

      Parameters:
      axisColor - the color to become this component's main axis color
      Throws:
      IllegalArgumentException - if the specified color is null
      See Also:

    • getMajorX

      public double getMajorX()

      Gets the distance, in graph units, between two major grid lines on the X axis.

      Returns:
      the spacing between two major grid lines on the X axis
      See Also:

    • setMajorX

      public void setMajorX(double majorX)

      Sets the distance, in graph units, between two major grid lines on the X axis.

      Parameters:
      majorX - the requested spacing between two major grid lines on the X axis
      Throws:
      IllegalArgumentException - if majorX is ≤ 0.0d
      See Also:

    • getMinorCountX

      public int getMinorCountX()

      Gets the number of minor grid lines between two major grid lines on the X axis.

      Returns:
      the number of minor grid lines between two major grid lines
      See Also:

    • setMinorCountX

      public void setMinorCountX(int minorCountX)

      Sets the number of minor grid lines between two major grid lines on the X axis.

      Parameters:
      minorCountX - the number of minor grid lines between two major grid lines on the X axis
      Throws:
      IllegalArgumentException - if minorCountX is < 0
      See Also:

    • getMajorY

      public double getMajorY()

      Gets the distance, in graph units, between two major grid lines on the Y axis.

      Returns:
      the spacing between two major grid lines on the Y axis
      See Also:

    • setMajorY

      public void setMajorY(double majorY)

      Sets the distance, in graph units, between two major grid lines on the Y axis.

      Parameters:
      majorY - the requested spacing between two major grid lines on the Y axis
      Throws:
      IllegalArgumentException - if majorY is ≤ 0.0d
      See Also:

    • getMinorCountY

      public int getMinorCountY()

      Gets the number of minor grid lines between two major grid lines on the Y axis.

      Returns:
      the number of minor grid lines between two major grid lines
      See Also:

    • setMinorCountY

      public void setMinorCountY(int minorCountY)

      Sets the number of minor grid lines between two major grid lines on the Y axis.

      Parameters:
      minorCountY - the number of minor grid lines between two major grid lines on the Y axis
      Throws:
      IllegalArgumentException - if minorCountY is < 0
      See Also:

    • setViewAndOrigin

      public void setViewAndOrigin(Rectangle2D bounds)

      Sets the view and the origin of the graph at the same time. The view minimum boundaries are defined by the location of the rectangle passed as parameter. The width and height of the rectangle define the distance between the minimum and maximum boundaries:

      • minX: bounds.getX()
      • minY: bounds.getY()
      • maxY: bounds.getMaxX() (minX + bounds.getWidth())
      • maxX: bounds.getMaxY() (minY + bounds.getHeight())

      The origin is located at the center of the view. Its coordinates are defined by calling bounds.getCenterX() and bounds.getCenterY().

      Parameters:
      bounds - the rectangle defining the graph's view and its origin
      See Also:

    • setView

      public void setView(Rectangle2D bounds)

      Sets the view of the graph. The view minimum boundaries are defined by the location of the rectangle passed as parameter. The width and height of the rectangle define the distance between the minimum and maximum boundaries:

      • minX: bounds.getX()
      • minY: bounds.getY()
      • maxY: bounds.getMaxX() (minX + bounds.getWidth())
      • maxX: bounds.getMaxY() (minY + bounds.getHeight())

      If the specified view is null, nothing happens.

      Calling this method leaves the origin intact.

      Parameters:
      bounds - the rectangle defining the graph's view and its origin
      See Also:

    • getView

      public Rectangle2D getView()

      Gets the view of the graph. The returned rectangle defines the bounds of the view as follows:

      • minX: bounds.getX()
      • minY: bounds.getY()
      • maxY: bounds.getMaxX() (minX + bounds.getWidth())
      • maxX: bounds.getMaxY() (minY + bounds.getHeight())
      Returns:
      the rectangle corresponding to the current view of the graph
      See Also:

    • resetView

      public void resetView()

      Resets the view to the default view if it has been changed by the user by panning and zooming. The default view is defined by the view last specified in a constructor call or a call to the methods setView(Rectangle2D) and setViewAndOrigin(Rectangle2D).

      See Also:

    • setOrigin

      public void setOrigin(Point2D origin)

      Sets the origin of the graph. The coordinates of the origin are defined by the coordinates of the point passed as parameter.

      If the specified view is null, nothing happens.

      Calling this method leaves the view intact.

      Parameters:
      origin - the coordinates of the new origin
      See Also:

    • getOrigin

      public Point2D getOrigin()

      Gets the origin coordinates of the graph. The coordinates are represented as an instance of Point2D and stored in double format.

      Returns:
      the origin coordinates in double format
      See Also:

    • addPlots

      public void addPlots(Color color, JXGraph.Plot... plotList)

      Adds one or more plots to the graph. These plots are associated to a color used to draw them.

      If plotList is null or empty, nothing happens.

      This method is not thread safe and should be called only from the EDT.

      Parameters:
      color - the color to be usd to draw the plots
      plotList - the list of plots to add to the graph
      Throws:
      IllegalArgumentException - if color is null
      See Also:

    • removePlots

      public void removePlots(JXGraph.Plot... plotList)

      Removes the specified plots from the graph. Plots to be removed are identified by identity. This means you cannot remove a plot by passing a clone or another instance of the same subclass of JXGraph.Plot.

      If plotList is null or empty, nothing happens.

      This method is not thread safe and should be called only from the EDT.

      Parameters:
      plotList - the list of plots to be removed from the graph
      See Also:

    • removeAllPlots

      public void removeAllPlots()

      Removes all the plots currently associated with this graph.

      This method is not thread safe and should be called only from the EDT.

      See Also:

    • getPreferredSize

      public Dimension getPreferredSize()
      Overrides:
      getPreferredSize in class JComponent

    • yPositionToPixel

      protected double yPositionToPixel(double position)

      Converts a position, in graph units, from the Y axis into a pixel coordinate. For instance, if you defined the origin so it appears at the exact center of the view, calling yPositionToPixel(getOriginY()) will return a value approximately equal to getHeight() / 2.0.

      Parameters:
      position - the Y position to be converted into pixels
      Returns:
      the coordinate in pixels of the specified graph Y position
      See Also:

    • xPositionToPixel

      protected double xPositionToPixel(double position)

      Converts a position, in graph units, from the X axis into a pixel coordinate. For instance, if you defined the origin so it appears at the exact center of the view, calling xPositionToPixel(getOriginX()) will return a value approximately equal to getWidth() / 2.0.

      Parameters:
      position - the X position to be converted into pixels
      Returns:
      the coordinate in pixels of the specified graph X position
      See Also:

    • xPixelToPosition

      protected double xPixelToPosition(double pixel)

      Converts a pixel coordinate from the X axis into a graph position, in graph units. For instance, if you defined the origin so it appears at the exact center of the view, calling xPixelToPosition(getWidth() / 2.0) will return a value approximately equal to getOriginX().

      Parameters:
      pixel - the X pixel coordinate to be converted into a graph position
      Returns:
      the graph X position of the specified pixel coordinate
      See Also:

    • yPixelToPosition

      protected double yPixelToPosition(double pixel)

      Converts a pixel coordinate from the Y axis into a graph position, in graph units. For instance, if you defined the origin so it appears at the exact center of the view, calling yPixelToPosition(getHeight() / 2.0) will return a value approximately equal to getOriginY().

      Parameters:
      pixel - the Y pixel coordinate to be converted into a graph position
      Returns:
      the graph Y position of the specified pixel coordinate
      See Also:

    • paintComponent

      protected void paintComponent(Graphics g)
      Overridden to provide Painter support. It will call backgroundPainter.paint() if it is not null, else it will call super.paintComponent().
      Overrides:
      paintComponent in class JXPanel
      Parameters:
      g - the Graphics context in which to paint

    • paintExtra

      protected void paintExtra(Graphics2D g2)

      This painting method is meant to be overridden by subclasses of JXGraph. This method is called after all the painting is done. By overriding this method, a subclass can display extra information on top of the graph.

      The graphics surface passed as parameter is configured by setupGraphics(Graphics2D).

      Parameters:
      g2 - the graphics surface on which the graph is drawn
      See Also:

    • setupGraphics

      protected void setupGraphics(Graphics2D g2)

      This method is called by the component prior to any drawing operation to configure the drawing surface. The default implementation enables antialiasing on the graphics.

      This method can be overriden by subclasses to modify the drawing surface before any painting happens.

      Parameters:
      g2 - the graphics surface to set up
      See Also:

    • paintBackground

      protected void paintBackground(Graphics2D g2)

      This method is called by the component whenever it needs to paint its background. The default implementation fills the background with a solid color as defined by Component.getBackground(). Background painting does not happen when isBackgroundPainted() returns false.

      It is recommended to subclasses to honor the contract defined by isBackgroundPainted() and setBackgroundPainted(boolean).

      Parameters:
      g2 - the graphics surface on which the background must be drawn
      See Also: