oracle.ord.media.chart.piechart
Class PieChart

java.lang.Object
  |
  +--java.awt.Component
        |
        +--oracle.ord.media.chart.Chart
              |
              +--oracle.ord.media.chart.legend.Legend
                    |
                    +--oracle.ord.media.chart.piechart.PieChart

All Implemented Interfaces:

java.awt.image.ImageObserver, java.awt.MenuContainer, java.io.Serializable

Direct Known Subclasses:

PieChartInteractive

public class PieChart

extends Legend

Pie charts are implemented by the PieChart class. Users define the data for the pie slice with setSeries(), parameterized by an array of pie slice descriptors (PieSliceDesc oracle.ord.media.chart.types.PieSliceDesc). Each pie slice descriptor defines the size of the slice and the associated label.

Pie slice labels can be automatically rewritten to include numerical information by using setDeriveLabelPct() or setDeriveLabelVal(). The method setDeriveLabelPct() rewrites the label by extending it with the percentage of the pie consumed by the slice, while setDeriveLabelVal() rewrites the label by extending it with the numerical value associated with the pie slice.

By default, the first slice is drawn starting 0 degrees. The start angle can be set by the user with setStartAngle(). Slices are drawn counter-clockwise.

The diameter of the pie is derived automatically, based on the pie chart dimensions and borders, as well as any titles, subtitles and footnotes that are defined.

Labels will be drawn inside the slice if there is enough space. Labels that cannot be drawn inside the slice will be drawn outside the pie, with a connector between the circumference of the slice and the associated label. If no label can be placed inside any slice, then labels will be placed in a color-coded legend. If a combination of internal/external labels will not fit in the chart boundaries, labels will be placed inside a legend. External labeling can be disabled by calling setExternalLabelsOff().

Use setForeground() to set the color of all labels (including all slice labels, any title, subtitle, and footnote) and lines. Use setBackground() to set the color of the rectangular window behind the pie. Note that setBackground() is defined in the Chart class.

The colors of pie slices can be set either individually or automatically. Colors can be set automatically by using the setAutoSliceColor() method. This method requires two Color parameters. The first color parameter specifies the color of the first slice, and the second specifies the color of the last slice. The colors of all slices in between are interpolated between the colors of the first and last slice.

Slice colors can be set individually by using the setBackground() methods of the appropriate slice descriptor (PieSliceDesc). Label colors can also be configured in a similar fashion, by using the setLabelColor() method of the slice descriptor.

Users may specify that selected words of slice labels be placed on separate lines. For example, to specify that the last line of each label be placed on a separate line, use setLastWordNewline(). Additionally or alternatively, to specify that all words containing a specific character be placed on a separate line, use setSeparateLine().

When placing labels within a slice, labels containing multiple words that do not fit on a single line will be broken into one or more lines. The space character (' ') is the default delimiter for determining line breaks. Users can define their own delimiters with setDelimiter(). For example, if URLs are used as labels, the user may want to include a period as a delimiter. In this case, the user should call setDelimiter(char[] {' ', '.') to include both a space and a period, or setDelimiter(char[] {'.') to include only a period. The width of the line used to draw the slices can be specified with setPieStroke(). The width of the line used to draw connectors to external labels can be specified with setConnectorStroke().

See Also:

Chart, Serialized Form

Inner classes inherited from class oracle.ord.media.chart.legend.Legend

Legend.LegendElement

Inner classes inherited from class oracle.ord.media.chart.Chart

Chart.ChartLabel

Fields inherited from class oracle.ord.media.chart.legend.Legend

DERIVED, EAST, NORTH, NORTHEAST, NORTHWEST, SOUTH, SOUTHEAST, SOUTHWEST, USERDEFINED, WEST

Fields inherited from class java.awt.Component

BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT

Fields inherited from interface java.awt.image.ImageObserver

ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH

Constructor Summary

PieChart()
Constructor

Method Summary

void	drawBuffer(java.awt.Graphics2D g2) Render the chart into the buffered image associated with g2.
java.awt.BasicStroke	getConnectorStroke() Get the stroke used to draw lines connecting external labels to pie slices.
java.awt.Color	getForeground() Get the color used to draw the pie circumference and the pie slices.
char[]	getImageMapCS() Return the server-side image map for the chart.
char[]	getImageMapSS() Return the server-side image map for the chart.
PieSliceDesc	getPieSliceDesc(int index) Return the PieSliceDesc at the specified index.
java.awt.BasicStroke	getPieStroke() Get the stroke used to draw the pie circumference and the pie slices.
void	paint(java.awt.Graphics g) Paints this component.
void	redrawBuffer(java.awt.Graphics2D g2)
void	setAutoSliceColor(java.awt.Color c1, java.awt.Color c2) Automatically assign colors to pie slices.
void	setBackgroundRectOff() Disable the drawing of the background rectangle.
void	setBounds(int x, int y, int w, int h) Move and resize the component.
void	setBounds(java.awt.Rectangle rect) Move and resize the component.
void	setConnectorStroke(java.awt.BasicStroke stroke) Set the stroke used to draw lines connecting external labels to pie slices.
void	setDelimiter(char delimiter) Define a single delimiter to be used in placing line breaks in pie slice labels.
void	setDelimiter(char[] delimiters) Define the delimiters to be used in placing line breaks in pie slice labels.
void	setDeriveLabelPct() For each pie slice, rewrite the label to include the slice percentage.
void	setDeriveLabelPct(int nDigits) Deprecated. Replaced by setDeriveLabelPct(NumberFormat).
void	setDeriveLabelPct(java.text.NumberFormat numFormat) For each pie slice, rewrite the label to include the slice percentage, formatting the percentage with the NumberFormat instance.
void	setDeriveLabelVal() For each pie slice, rewrite the label to include the slice value.
void	setDeriveLabelVal(int nDigits) Deprecated. Replaced by setDeriveLabelVal(NumberFormat).
void	setDeriveLabelVal(java.text.NumberFormat numFormat) For each pie slice, rewrite the label to include the slice value, using the supplied NumberFormat.
void	setEnableImageMapCS(ImageMapDesc desc) Enable the client-side image map.
void	setEnableImageMapCS(ImageMapDesc[] desc) Enable the client-side image map.
void	setEnableImageMapSS(ImageMapDesc desc) Enable the server-side image map.
void	setExternalLabelsOff() Disable the generation of external labels.
void	setFont(java.awt.Font f) Set the font for all labels.
void	setForeground(java.awt.Color c) Set the color used to draw the pie circumference, the outline of the pie slices, and the pie slice labels.
void	setLabelInteriorPct() Configure the labeling style to label the interior of all pie slices with percentages.
void	setLabelInteriorVal() Configure the labeling style to label the interior of all pie slices with values.
void	setLastWordNewline() Force the last word of each slice label to reside on a newline.
void	setPieStroke(java.awt.BasicStroke stroke) Set the stroke used to draw the pie circumference and the pie slices.
void	setSeparateLine(char delimiter) Force slice label words containing the character delimiter to reside on a separate line.
void	setSeparateLine(char[] delimiters) Force slice label words containing any of the characters in delimiter[] to reside on a separate line.
void	setSeries(PieSliceDesc[] SliceDesc) Define the pie slices using an array of PieSliceDesc.
void	setSize(java.awt.Dimension d) Set the dimensions of the chart.
void	setSize(int width, int height) Set the dimensions of the chart.
void	setStartAngle(double angle) Set the angle of the first slice.

Methods inherited from class oracle.ord.media.chart.legend.Legend

getLegendAlignment, getLegendBackground, getLegendDisable, getLegendDisplaySingleSeries, getLegendEdgeColor, getLegendEdgeDisable, getLegendForeground, getLegendInside, setLegendAlignment, setLegendBackground, setLegendDisable, setLegendDisplaySingleSeries, setLegendEdgeColor, setLegendEdgeDisable, setLegendFont, setLegendForeground, setLegendInside, setLegendOffsetX, setLegendOffsetY

Methods inherited from class oracle.ord.media.chart.Chart

getBackground, getBorderBottom, getBorderLeft, getBorderRight, getBorderTop, getEdgeColor, getFootnote, getHeight, getMinimumSize, getPreferredSize, getRenderingHintsChart, getSize, getSubtitle, getTitle, getVersion, getWidth, isSetRenderingHintsChart, setBackground, setBorderBottom, setBorderLeft, setBorderRight, setBorderTop, setEdgeColor, setRenderingHintsChart, setTitlesForeground

Methods inherited from class java.awt.Component

action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addNotify, addPropertyChangeListener, addPropertyChangeListener, bounds, checkImage, checkImage, contains, contains, createImage, createImage, deliverEvent, disable, dispatchEvent, doLayout, enable, enable, enableInputMethods, getAccessibleContext, getAlignmentX, getAlignmentY, getBounds, getBounds, getColorModel, getComponentAt, getComponentAt, getComponentOrientation, getCursor, getDropTarget, getFont, getFontMetrics, getGraphics, getGraphicsConfiguration, getInputContext, getInputMethodRequests, getListeners, getLocale, getLocation, getLocation, getLocationOnScreen, getMaximumSize, getName, getParent, getPeer, getSize, getToolkit, getTreeLock, getX, getY, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, invalidate, isDisplayable, isDoubleBuffered, isEnabled, isFocusTraversable, isLightweight, isOpaque, isShowing, isValid, isVisible, keyDown, keyUp, layout, list, list, list, list, list, locate, location, lostFocus, minimumSize, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, preferredSize, prepareImage, prepareImage, print, printAll, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeNotify, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, repaint, requestFocus, reshape, resize, resize, setComponentOrientation, setCursor, setDropTarget, setEnabled, setLocale, setLocation, setLocation, setName, setVisible, show, show, size, toString, transferFocus, update, validate

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

PieChart

public PieChart()

Constructor

Method Detail

setFont

public void setFont(java.awt.Font f)

Set the font for all labels.

Overrides:

setFont in class java.awt.Component

setStartAngle

public void setStartAngle(double angle)

Set the angle of the first slice. By default, the first slice begins at 0 degrees.

Parameters:

angle - Angle (in degrees) to start the first pie slice.

setExternalLabelsOff

public void setExternalLabelsOff()

Disable the generation of external labels. By default, labels that cannot fit inside the pie will be drawn outside the pie. If one calls setExternalLabelsOff() but all labels do not fit inside the pie, all labels will be placed inside a legend.

setBackgroundRectOff

public void setBackgroundRectOff()

Disable the drawing of the background rectangle.

setLastWordNewline

public void setLastWordNewline()

Force the last word of each slice label to reside on a newline. This call is typically used if the last word of the label is a numerical value.

See Also:

setSeparateLine(char)

setSeparateLine

public void setSeparateLine(char delimiter)

Force slice label words containing the character delimiter to reside on a separate line. This method is typically used when users want words with special characters, such as "$" or "%", to be placed on separate lines. setSeparateLine(char[]) provides the same functionality, but allows multiple characters to be defined.

Parameters:

delimiter - Any word containing delimiter will be placed in a separate line.

See Also:

setLastWordNewline(), setSeparateLine(char[])

setSeparateLine

public void setSeparateLine(char[] delimiters)

Force slice label words containing any of the characters in delimiter[] to reside on a separate line. This call is typically used when users want words with special characters, such as "$" and "%", to be placed on separate lines. setSeparateLine(char) provides the same functionality, but only allows a single character to be defined.

Parameters:

delimiter - Any word containing delimiter will be placed in a separate line.

See Also:

setLastWordNewline(), setSeparateLine(char)

setDelimiter

public void setDelimiter(char delimiter)

Define a single delimiter to be used in placing line breaks in pie slice labels. The default delimiter is the space (" "). setDelimiter(char[]) provides similar functionality, but allows multiple delimiters to be defined.

Parameters:

delimiter - Defines the character that serves as delimiter.

See Also:

setDelimiter(char)

setDelimiter

public void setDelimiter(char[] delimiters)

Define the delimiters to be used in placing line breaks in pie slice labels. Multiple delimiters can be defined. For example, to define spaces, forward and backward slashes as delimiters, the appropriate call would be: setDelimiter(" /\"); The default delimiter is the space (" ").

Parameters:

delimiters - Defines the characters that serve as delimiters.

See Also:

setDelimiter(char)

setAutoSliceColor

public void setAutoSliceColor(java.awt.Color c1,
                              java.awt.Color c2)

Automatically assign colors to pie slices. The colors of all slices between the first and last are assigned to colors between c1 and c2, interpolated via RGB components.

Note that colors set with this method will supercede any colors set with slice descriptor parameters of setSeries(). However, one can change individual slice colors by calling getPieSliceDesc().setBackground() after setAutoSliceColor().

Parameters:

c1 - Color of the first slice.

c2 - Color of the last slice.

See Also:

getPieSliceDesc(int), PieSliceDesc.setBackground(Color), setSeries(PieSliceDesc[])

getPieSliceDesc

public PieSliceDesc getPieSliceDesc(int index)
                             throws ChartException

Return the PieSliceDesc at the specified index. This method provides a handle to a slice descriptor, enabling users to update attributes of pie slices dynamically.

Parameters:

index - - Index of the slice.

Throws:

ChartException - if the pie slice index has not been defined.

setDeriveLabelPct

public void setDeriveLabelPct()
                       throws ChartException

For each pie slice, rewrite the label to include the slice percentage. Each pie slice label will be augmented with a numerical percentage value. This value is derived from the portion of the pie that the pie slice consumes. For example, suppose the user defines a pie chart containing two slices, with the first slice, with the label "label1", consuming 60% of the pie and the second slice, with the label "label2", consuming 40% of the pie:

  
  PieCh = new PieChart();          
  PieSliceDesc sliceDesc[2];
  sliceDesc[0] = new PieSliceDesc("label1", 60);
  sliceDesc[1] = new PieSliceDesc("label2", 40);
  PieCh.setSeries(sliceDesc);
  PieCh.setDeriveLabelPct();
  
  

In this case, calling setDeriveLabelPct() will rewrite the label "label1" to be "label1 60%", and "label2" to be "label2 40%".

Throws:

ChartException - if the user has previously invoked setLabelInteriorVal.

See Also:

setDeriveLabelVal(), setSeries(PieSliceDesc[])

setDeriveLabelPct

public void setDeriveLabelPct(java.text.NumberFormat numFormat)
                       throws ChartException

For each pie slice, rewrite the label to include the slice percentage, formatting the percentage with the NumberFormat instance. For details about label rewrite, please see the comment for setDeriveLabelPct(). The percentages will be formatted based on the NumberFormat instance.

The following example derives percent labels using two fractional digits:

 
     NumberFormat nf = NumberFormat.getPercentInstance();
     nf.setMinimumFractionDigits(2);
     myChart.setDeriveLabelPct(nf);
  

Parameters:

numFormat - A percent instance of NumberFormat.

Throws:

ChartException - if the user has previously invoked setLabelInteriorVal().

See Also:

setDeriveLabelPct()

setDeriveLabelPct

public void setDeriveLabelPct(int nDigits)
                       throws ChartException

Deprecated. Replaced by setDeriveLabelPct(NumberFormat).

For each pie slice, rewrite the label to include the slice percentage, using nDigits precision. For nDigits, a value of 0 implies integer labels, while a value of 1 or more specifies nDigits past the decimal point. See setDeriveLabelPct() for more details about label rewrite.

Parameters:

nDigits - Number of digits past the decimal place to display.

See Also:

setDeriveLabelPct()

setLabelInteriorPct

public void setLabelInteriorPct()
                         throws ChartException

Configure the labeling style to label the interior of all pie slices with percentages. Note that these slice percentages are calculated based on the values defined in the PieSliceDesc parameter to setSeries(). (setLabelInteriorPct() internally invokes setDeriveLabelPct()). The format of these percentages can be altered with setDeriveLabelPct(NumberFormat).

All user-supplied labels will be placed in a legend.

Throws:

ChartException - if the user has previously invoked setLabelInteriorVal().

setLabelInteriorVal

public void setLabelInteriorVal()

Configure the labeling style to label the interior of all pie slices with values. Note that these slice values correspond to the values defined in the PieSliceDesc parameter to setSeries(). (setLabelInteriorVal() internally invokes setDeriveLabelVal()). The format of these values can be altered with setDeriveLabelVal(NumberFormat).

All user-supplied labels will be placed in a legend.

setDeriveLabelVal

public void setDeriveLabelVal()
                       throws ChartException

For each pie slice, rewrite the label to include the slice value. Each pie slice label will be augmented with a numerical value. This value is extracted from the value field of the PieSliceDesc object that is a parameter to setSeries(). For example, suppose the user defines a pie chart containing two slices, with the first slice having the label "label1" and a value of 700 and the second slice having the label "label2" and a value of 100:

  
  PieCh = new PieChart();          
  PieSliceDesc sliceDesc[2];
  sliceDesc[0] = new PieSliceDesc("label1", 700);
  sliceDesc[1] = new PieSliceDesc("label2", 100);
  PieCh.setSeries(sliceDesc);
  PieCh.setDeriveLabelVal();
  
  

In this case, calling setDeriveLabelVal() will rewrite the label "label1" to be "label1 700", and "label2" to be "label2 100".

Note that this method can be used only in conjunction with setSeries() calls that have PieSliceDesc parameters.

Throws:

ChartException - if the user has previously invoked setLabelInteriorPct().

See Also:

setDeriveLabelPct(), setSeries(PieSliceDesc[])

setDeriveLabelVal

public void setDeriveLabelVal(java.text.NumberFormat numFormat)
                       throws ChartException

For each pie slice, rewrite the label to include the slice value, using the supplied NumberFormat. For details about label rewrite, please see the comment for setDeriveLabelPct().

The following example derives labels using the currency of the current locale:

 
  myChart.setDeriveLabelVal(NumberFormat.getCurrencyInstance());
  

Parameters:

numFormat - a percent instance of NumberFormat.

Throws:

ChartException - if the user has previously invoked setLabelInteriorVal().

See Also:

setDeriveLabelPct()

setDeriveLabelVal

public void setDeriveLabelVal(int nDigits)
                       throws ChartException

Deprecated. Replaced by setDeriveLabelVal(NumberFormat).

For each pie slice, rewrite the label to include the slice value, using nDigits precision. For nDigits, a value of 0 implies integer labels, while a value of of 1 or more specifies nDigits past the decimal point. See setDeriveLabelVal() for more details about label rewrite.

Parameters:

nDigits - Number of digits past the decimal place to display.

See Also:

setDeriveLabelVal()

setSeries

public void setSeries(PieSliceDesc[] SliceDesc)
               throws ChartException

Define the pie slices using an array of PieSliceDesc.

Parameters:

SliceDesc[] - Array of PieSliceDesc.

Throws:

ChartError - if a negative slice value is supplied.

ChartError - if a null SliceDesc is supplied.

redrawBuffer

public void redrawBuffer(java.awt.Graphics2D g2)
                  throws ChartException

getPieStroke

public java.awt.BasicStroke getPieStroke()

Get the stroke used to draw the pie circumference and the pie slices.

Returns:

stroke BasicStroke

setPieStroke

public void setPieStroke(java.awt.BasicStroke stroke)

Set the stroke used to draw the pie circumference and the pie slices.

Parameters:

stroke - BasicStroke

getConnectorStroke

public java.awt.BasicStroke getConnectorStroke()

Get the stroke used to draw lines connecting external labels to pie slices.

Returns:

stroke BasicStroke

setConnectorStroke

public void setConnectorStroke(java.awt.BasicStroke stroke)

Set the stroke used to draw lines connecting external labels to pie slices.

Parameters:

stroke - BasicStroke

getForeground

public java.awt.Color getForeground()

Get the color used to draw the pie circumference and the pie slices.

Overrides:

getForeground in class java.awt.Component

Returns:

Color

setForeground

public void setForeground(java.awt.Color c)

Set the color used to draw the pie circumference, the outline of the pie slices, and the pie slice labels. The labels include all slice labels, as well as any title, subtitle, and footnote. Note that setForeground() will have no effect on the pie slice label color if setSeries() is called after setForeground(). In this case, the colors defined in each slice descriptor will take effect.

Overrides:

setForeground in class java.awt.Component

Parameters:

color - Color of the pie slice.

See Also:

PieSliceDesc

drawBuffer

public void drawBuffer(java.awt.Graphics2D g2)
                throws ChartException

Render the chart into the buffered image associated with g2. Note that when using applets, it is not necessary to invoke drawBuffer().

Throws:

ChartException - if no pie slices have been defined.

setEnableImageMapSS

public void setEnableImageMapSS(ImageMapDesc desc)
                         throws ChartException

Enable the server-side image map. Must be called before drawBuffer().

See Also:

drawBuffer(Graphics2D), getImageMapSS()

setEnableImageMapCS

public void setEnableImageMapCS(ImageMapDesc desc)
                         throws ChartException

Enable the client-side image map. Must be called before drawBuffer(). Note that image map attributes, such as the mapName, areaSpecText, and the hrefPrefix are defined with the ImageMapDesc object.

Parameters:

ImageMapDesc - Defines attributes of the image map.

See Also:

drawBuffer(Graphics2D), getImageMapCS(), ImageMapDesc

setEnableImageMapCS

public void setEnableImageMapCS(ImageMapDesc[] desc)
                         throws ChartException

Enable the client-side image map.

getImageMapSS

public char[] getImageMapSS()
                     throws ChartException

Return the server-side image map for the chart.

Throws:

ChartException - if drawBuffer() was not previously invoked.

See Also:

setEnableImageMapSS(ImageMapDesc)

getImageMapCS

public char[] getImageMapCS()
                     throws ChartException

Return the server-side image map for the chart.

Throws:

ChartException - if drawBuffer() was not previously invoked.

See Also:

setEnableImageMapCS(ImageMapDesc)

setBounds

public void setBounds(int x,
                      int y,
                      int w,
                      int h)

Move and resize the component.

Overrides:

setBounds in class java.awt.Component

setBounds

public void setBounds(java.awt.Rectangle rect)

Move and resize the component.

Overrides:

setBounds in class java.awt.Component

setSize

public void setSize(java.awt.Dimension d)

Set the dimensions of the chart.

Overrides:

setSize in class java.awt.Component

setSize

public void setSize(int width,
                    int height)

Set the dimensions of the chart.

Overrides:

setSize in class java.awt.Component

Parameters:

width - Width of the chart.

height - Height of the chart.

paint

public void paint(java.awt.Graphics g)

Paints this component.

Overrides:

paint in class java.awt.Component