Package org.faceless.graph2

Class Graph

  • Direct Known Subclasses:
    AxesGraph, DialGraph, PieGraph
    public abstract class Graph
extends Object

    The abstract base class for all Graphs in the Big Faceless Graph Library version 2.x. All the types of Graph in the package have certain things in common.

    • All the graphs are fully 3-D. By default they are seen head-on and so look two-dimensional, but can be rotated to any angle to give a 3D effect by calling setXRotation(double) and friends.
    • When a Graph is complete the draw method is called to write the Graph to an Output, which could be a PNG image, a PDF or similar. Once it's drawn to an output, it cannot be redrawn.

    Currently the two types of Graph available are PieGraph and AxesGraph, and you should see those classes for more information

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static String VERSION
      The current version of the Graph library.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void addKey​(Key key, double x, double y)
      Set a Key on the graph, and position it at the specified location on the Graph.
      void addKey​(Key key, int position)
      Set a Key on the graph and position it at the edges of the Output.
      void addText​(String text, TextStyle style)
      Add some text to the Graph.
      void draw​(Output out)
      Draw the Graph to the specified Output object.
      Point2D getActualOffset()
      Return the actual centre value used for this graph.
      double getActualZoom()
      Return the actual zoom value used for this graph.
      Locale getLocale()
      Return the Locale set by setLocale(java.util.Locale)
      void interrupt()
      Interrupt the draw() method.
      boolean isInterrupted()
      Return whether the graph has been interrupted before it could be finalized.
      boolean isOverlapping()
      Return true if there were any markers overlapping other markers when this graph was drawn.
      void setAutoColors​(Color c1, Color c2)
      Set the Graph to auto-generate colors for its data by adjusting the hue, saturation and brightness between the two specified colors.
      void setColorOrdering​(String order)
      Set the order the auto-generated colors are used.
      void setDefaultColors​(Paint[] colors)
      Set the default colors for the graph.
      void setFixedAspectRatio​(boolean val)
      Whether this graph should have a fixed aspect ratio.
      void setFixedSize​(double zoom, double x, double y)
      When plotting a number of graphs that are supposed to be exactly the same size, this method can be used to set the zoom, x and y position to fixed values, rather than allowing the graph to be autosized to fit.
      static void setLicenseKey​(String key)
      Set the license key for the library.
      void setLightLevel​(int level)
      Set the level of light (technically, the level of shade) that should be applied to a graph.
      void setLightVector​(int x, int y, int z)
      Set the vector of where the light is coming from.
      void setLocale​(Locale locale)
      Set the Locale to be used for formatting numbers.
      void setMetaData​(String key, String value)
      Set some descriptive text on the graph.
      void setOption​(String key, String value)
      Set an option to fine-tune the graph's rendering.
      void setXRotation​(double val)
      How far to rotate the graph around the X-axis (the line running from the left of the graph to the right), in degrees clockwise.
      void setYRotation​(double val)
      How far to rotate the graph around the Y-axis (the line running from the top of the graph to the bottom), in degrees clockwise.
      void setZRotation​(double val)
      How far to rotate the graph around the Z-axis (the line running from the front of the graph to the back), in degrees clockwise.

    • Field Detail

      • VERSION

        public static final String VERSION
        The current version of the Graph library. Typically this will be a string value like "2.0". Please be sure to include this information with any bug reports

    • Method Detail

      • setLocale

        public void setLocale​(Locale locale)
        Set the Locale to be used for formatting numbers. The default is Locale.getDefault()
        Since:
        2.4.9

      • setAutoColors

        public final void setAutoColors​(Color c1,
                                Color c2)
        Set the Graph to auto-generate colors for its data by adjusting the hue, saturation and brightness between the two specified colors.
        Parameters:
        c1 - the first Color in the range
        c2 - the first Color in the range
        Since:
        2.4

      • setDefaultColors

        public void setDefaultColors​(Paint[] colors)
        Set the default colors for the graph. Each new element that is added will use the next color in this list - if there are no unused colors left, the list is reset to the beginning.
        Parameters:
        colors - the colors to use

      • setColorOrdering

        public void setColorOrdering​(String order)
        Set the order the auto-generated colors are used. By default the first color is applied to the first data item, the second to the second and so on. Setting this to "value" will apply the first color to the largest data item and so on. This works with PieCharts and graphs showing a single BarSeries, but is unlikely to give useful results for more complex graphs
        Parameters:
        order - the ordering to use - "value" or anything else to use the default
        Since:
        2.4

      • addKey

        public void addKey​(Key key,
                   int position)
        Set a Key on the graph and position it at the edges of the Output. Currently a Graph can only have one key, so repeated calls to this will overwrite any earlier values.
        Parameters:
        key - the Key to use on the graph
        position - where to position the Key - a combination of values from the Align class

      • addKey

        public void addKey​(Key key,
                   double x,
                   double y)
        Set a Key on the graph, and position it at the specified location on the Graph. The location is specified as two doubles, which range from 0 to 1 (0 being left or bottom, 1 being right or top). Any value between these two ranges may be used to position the Key over the Graph itself. Currently a Graph can only have one key, so repeated calls to this will overwrite any earlier values.
        Parameters:
        key - the Key to use on the graph
        x - the X co-ordinate to position the key, from 0 to 1
        y - the Y co-ordinate to position the key, from 0 to 1

      • addText

        public void addText​(String text,
                    TextStyle style)
        Add some text to the Graph. Typically this is used to add a title, a footnote or similar - if you want to add text to the actual contents of the graph, see the Text class. The alignment of the style parameter determines where on the graph the text is displayed.
        Parameters:
        text - the text to display
        style - the style to display the text in

      • setXRotation

        public void setXRotation​(double val)
        How far to rotate the graph around the X-axis (the line running from the left of the graph to the right), in degrees clockwise. A positive value will rotate the top of the graph towards the viewer.
        Parameters:
        val - the rotation to use

      • setYRotation

        public void setYRotation​(double val)
        How far to rotate the graph around the Y-axis (the line running from the top of the graph to the bottom), in degrees clockwise. A positive value will turn the right side of the graph towards the viewer.
        Parameters:
        val - the rotation to use

      • setZRotation

        public void setZRotation​(double val)
        How far to rotate the graph around the Z-axis (the line running from the front of the graph to the back), in degrees clockwise. Setting this value and leaving X and Y rotation set to zero is the equivalent of rotating a graph in 2D. To draw horizontal bar graphs, try setting this to 90.

        Since 2.4.6, a value of NaN will rotate the graph to achieve the maximum possible size. This is unlikely to be useful for any types of Graph other than PieGraphs.
        Parameters:
        val - the rotation to use

      • setFixedAspectRatio

        public void setFixedAspectRatio​(boolean val)
        Whether this graph should have a fixed aspect ratio. If false, the graph may be stretched horizontally or vertically to fill the space available. If true, the width and height will stay fixed, which is more appropriate for graphs like PieGraphs.
        Parameters:
        val - whether to have a fixed aspect ratio or not. Default is true for PieGraphs, false otherwise.

      • setFixedSize

        public void setFixedSize​(double zoom,
                         double x,
                         double y)

        When plotting a number of graphs that are supposed to be exactly the same size, this method can be used to set the zoom, x and y position to fixed values, rather than allowing the graph to be autosized to fit. Be warned that for some types of graph (eg. those plotted against a DateAxis), the values that should be set here could seem quite 'odd', so a fair amount of experimentation will be required to find appropriate values for each graph.

        As a hint, for date axes you probably want to set zoom to about 0.0002 and x to something near to -DateAxis.toDouble(date), where "date" is the first date being plotted. For PieGraphs, X and Y should be about equal to center the graph, which has a default radius of 100.

        Parameters:
        zoom - the zoom value, or 0 to auto-size
        x - the amount to add to the X co-ordinates of the graph, or NaN to auto-position
        y - the amount to add to the Y co-ordinates of the graph, or NaN to auto-position. Remember in graphs, y=0 is at the bottom of the graph, so positive values move items on the graph up the page.
        See Also:
        getActualZoom(), getActualOffset()

      • isOverlapping

        public boolean isOverlapping()
        Return true if there were any markers overlapping other markers when this graph was drawn. Markers area considered to be overlapping if their bounding boxes overlap, or if one crosses the "anchor line" of ther other (applicable to PieGraphs only). This may or may not result in an actual visible overlap, depending on the exact shape of the marker, but graphs where this method returns true might warrant a visual inspection. Prior to the call to draw(org.faceless.graph2.Output) this method returns false
        Since:
        2.4.6

      • draw

        public final void draw​(Output out)
        Draw the Graph to the specified Output object. Once this method has been called once, it cannot be called again on the same graph.
        Parameters:
        out - the Output to draw the graph to
        Throws:
        IllegalStateException - if the graph has already been drawn.

      • setLightLevel

        public void setLightLevel​(int level)
        Set the level of light (technically, the level of shade) that should be applied to a graph. A value of 0 is no shading at all, a value of 100 gives deep shadows. The default is 70.
        Parameters:
        level - the level of lighting used to shade the graph

      • setLightVector

        public void setLightVector​(int x,
                           int y,
                           int z)
        Set the vector of where the light is coming from. The light is assumed to be coming from an infinite distance away in the specified direction, so don't worry about the length of the vector. The default is (1,0,0), which makes the light appear to come from the right side of the graph. Calling graph.setLightVector(-1,0,-1) would put the light to the left and in front of the graph, while a vector (0,-1,0) would put the light directly underneath the graph, for a strange result indeed.
        Parameters:
        x - the X component of the vector
        y - the Y component of the vector
        z - the Z component of the vector

      • setMetaData

        public void setMetaData​(String key,
                        String value)
        Set some descriptive text on the graph. The effect of this method depends very much on the type of Output being used, but typically will result in metadata of some sort being embedded in the final graph. For instance, to set the author of the graph you could call setMetaData("Author", "Joe Bloggs").
        Parameters:
        key - The type of MetaData to use. Values recognised include Author, Title, Description and Copyright, although other keys may be used and will be inserted if possible.
        value - the value to insert

      • setOption

        public void setOption​(String key,
                      String value)
        Set an option to fine-tune the graph's rendering. Current options are
        markerPriorityAlways draw markers ahead of faces. This may be needed to correctly display markers in some types of graph.
        Since:
        2.4.5

      • interrupt

        public final void interrupt()
        Interrupt the draw() method. This may be called from another thread to interrupt the drawing routine if the resulting graph is no longer of interest. The Output the draw() method is writing to should be discarded, as it will be left in an undefined state, as will this object. If this method is called before the draw() method has been called, then when it is called it will exit immediately. If called afterwards, it will have no effect.
        Since:
        2.1.2

      • isInterrupted

        public final boolean isInterrupted()
        Return whether the graph has been interrupted before it could be finalized. If this method returns true then the Output written to by the draw() method will be in an undefined state and should be discarded.
        Since:
        2.1.2

      • setLicenseKey

        public static void setLicenseKey​(String key)

        Set the license key for the library. When the library is purchased, the Big Faceless Organization supplies a key which removes the "DEMO" stamp on each of the graphs.

        Please note this method is static - it should be called BEFORE the first Graph is created, like so: 

          Graph.setLicenseKey(.....);
  Graph graph = new AxesGraph();
        Parameters:
        key - the license key