Charts
1. Chart types
A chart is a GUI component based on JavaFX's XYChart class that can be used to conveniently draw numeric and statistical data. All charts are designed to be compatible with Eclipse RCP applications and SWT framework.
1.1. Line Charts
Line Charts are used to show linear plots or clouds of points in two-dimensional coordinates and represented by two different implementations depending on the type of horizontal axis: TimeLineChart
or NumericLineChart
. TimeLineChart
is used to display time-relative numeric data as horizontal axis ticks, NumericLineChart
is used to display simple numeric data as horizontal axis ticks. The examples below shows how to create a simple Line Charts for a given swt parent composite:
TimeLineChart timeLineChart = Charts.line(parentComposite, ChronoUnit.DAYS);
NumericLineChart numericLineChart = Charts.lineNumeric(parentComposite);
1.2. Gantt Charts
Gantt Charts are used to show history of some state changes or schedules. The example below shows how to create a simple TimeGanttChart
for a given swt parent composite:
TimeGanttChart ganttChart = Charts.gantt(parentComposite, ChronoUnit.DAYS);
1.3. Bar Charts
Bar Charts are used to show statistical data by categories as well as histograms. The examples below shows how to create a simple BarChart
or HistogramChart
for a given swt parent composite:
BarChart barChart = Charts.bar(parentComposite);
HistogramChart histogramChart = Charts.histogram(parentComposite);
Note that only one chart can be shown at the same time on the same parent composite.
2. Chart elements
Regardless of type, any chart consists of the following elements:
-
Title — the text that can be displayed above the chart typically containing the title of the data being shown
-
Content — the area where the data is actually plotted
-
Axes — the horizontal and vertical axes of a chart
-
Legend — the area showing additional information for the data items
-
Scrollbars — horizontal scrollbar can appear in the bottom of a chart if the currently displayed range of X-axis values does not contain all the data. Vertical scrollbar can appear in the right area of a chart if the currently displayed range of Y-axis values does not contain all the data
Method | Description |
---|---|
|
Specifies whether the chart should be drawn |
|
Checks whether the chart should be drawn |
|
Causes the chart to be redrawn. Not only affects the visual representation but also recalculate the contents of the displayed data. All visuals, axes and other chart’s components are also redrawn and recalculated. |
|
Disposes the chart. Called to release all resources allocated for the chart. After calling this method, the chart no longer can be used. Attempts to use disposed charts will cause undefined behavior |
|
Checks if the chart is already disposed |
|
Copies the contents displayed on the chart to the clipboard. Method copies the full content including items not displayed in the current displayed range. This action uses the clipboard defined by the operating system. |
|
Updates the location and size of the chart and redraws its content. Redraw works similar to redraw method - it updates all visuals, all content and all other components of the chart. Doing nothing if none of the method parameters has changed with no forceUpdate option set to true. |
|
Updates the chart size and redraws its content. Redraw works similar to redraw method - it updates all visuals, all content and all other components of the chart. Doing nothing if none of the method parameters has changed with no forceResize option set to true. |
|
Checks whether the chart is in the process of being redrawn. All chart redrawing operations are performed in a separate thread, so the chart provides the opportunity to determine whether an redraw operation is currently being performed. The addRedrawFinishedHandler method can be used to determine whether a redraw has finished. |
Method | Description |
---|---|
Mouse pressed handlers |
|
|
Adds the action that will be executed every time when a mouse button has been pressed |
|
Removes the mouse button press action |
|
Removes all the mouse button press actions |
Mouse released handlers |
|
|
Adds the action that will be executed every time when a mouse button has been released |
|
Removes the mouse button release action |
|
Removes all the mouse button release actions |
Mouse dragged handlers |
|
|
Adds the action that will be executed every time when a mouse has perform drag operation |
|
Removes the mouse drag action |
|
Removes all the mouse drag actions |
Mouse entered handlers |
|
|
Adds the action that will be executed every time when a mouse has been entered to any visual element borders |
|
Removes the mouse enter action |
|
Removes all the mouse enter actions |
Mouse exited handlers |
|
|
Adds the action that will be executed every time when the mouse has exited the previously entered element’s bounds |
|
Removes the mouse exit action |
|
Removes all the mouse exit actions |
Key pressed handlers |
|
|
Adds the action that will be executed every time when the key has been pressed |
|
Removes the key pressed action |
|
Removes all the key pressed actions |
Key released handlers |
|
|
Adds the action that will be executed every time when the key has been released after being pressed |
|
Removes the key released action |
|
Removes all the key released actions |
Redraw finished handlers |
|
|
Adds the action that will be executed every time when chart’s redrawing has been completed |
|
Removes the chart redrawing action |
|
Removes all the chart redrawing actions |
Gantt Chart mouse click handlers |
|
|
Adds the action that will be executed every time the contents area is clicked |
|
Removes the contents area click action |
|
Removes all the contents area click actions |
3. Context Menu
Charts provides the Context Menu
that appears by right-click on the content area.
The user can programmatically enable or disable pre-installed menu items (for example, the "copy to clipboard" option) and also add completely custom items.
Custom items can be added to the context menu to expand the functionality of user interaction with the displayed data.
Such custom menu items, for example, can be used to add, remove or change the currently displayed data, or to get more information about the visuals being right-clicked or simply displayed.
Method | Description |
---|---|
|
Specifies whether to display the |
|
Specifies whether the 'Copy to clipboard' menu item should be drawn. True by default |
|
Adds a context menu element that controls the search and navigation for elements of the Gantt-chart Y-axis. Used only in the |
|
Adds the new context menu item to the end of the items list |
|
Removes the context menu item |
|
Removes all context menu items added by the 'addContextMenuItem' calls. Does not affect pre-installed items such as 'copy to clipboard' etc |
4. Visual sets
The data drawn on charts is passed to them using VisualSets. A visual set is abstraction that contains information about how to extract data from some source (e.g. a list of Double values) and present them on a chart.
A chart can show several visual sets simultaneously. A group of one or several visual sets to be displayed on a chart must be put into a VisualSetContainer. Apart from containing the visual sets, VisualSetContainer defines how they must be shown in relation to one another. A chart can show only one VisualSetContainer
A visual set is created inside every chart and can be retrieved by getVisualSetContainer
method.
A different VisualSetContainer with different set of visual sets can be set to a chart with setVisualSetContainer
method.
Method | Description |
---|---|
|
Set a |
|
Returns the |
|
Specifies whether the |
|
Checks whether the |
5. Chart title
Chart title can be set by setTitle
method and switched on and off by setTitleVisible
method.
Method | Description |
---|---|
State changing methods |
|
|
Sets the new title and redraws the chart |
|
Specifies whether the title should be drawn and redraws the chart |
|
Sets the font to the title and redraws the chart |
|
Sets the font size to the title and redraws the chart |
|
Sets the new color to the title and redraws the chart |
Getters and state retrieving methods |
|
|
Returns the title of the chart |
|
Checks whether the chart title should be drawn |
|
Returns the font of the chart title |
|
Returns the font size of the chart title |
|
Returns the color of the chart title |
6. Background and margins
Background of the entire chart area can be set by setBackgroundColor
method.
Background of chart content area can be set by setContentBackgroundColor
method.
By default, chart content area is transparent.
Method | Description |
---|---|
State changing methods |
|
|
Sets the background color of the entire chart area. Transparent and semi-transparent colors are allowed |
|
Sets the background color of the chart content area. Transparent and semi-transparent colors are allowed |
|
Sets the top margin of the chart, in pixels. Top margin is the vertical distance between top border of the chart and content area of the chart. Redraws the chart after set |
|
Sets the bottom margin of the chart, in pixels. Bottom margin is the vertical distance between Bottom border of the chart and content area of the chart. Redraws the chart after set |
|
Sets the left margin of the chart, in pixels. Left margin is the horizontal distance between top border of the chart and content area of the chart. Redraws the chart after set |
Getters and state retrieving methods |
|
|
Returns the background color of the entire chart area |
|
Returns the background color of the chart content area |
|
Returns the top margin of the chart, in pixels |
|
Returns the bottom margin of the chart, in pixels |
|
Returns the left margin of the chart, in pixels |
7. Chart Axis
Chart Axis holds properties for ranging, ticks and labels along the axis. Each chart has two axes, horizontal (X) and vertical (Y). Depending on the axis type not only ticks/labels can be supported, but also additional functionality of zoom, manual shift of the view area (pan), etc.
7.1. Axis title
The axis title is used to label its assignment and is displayed parallel to the direction of the axis. Axis title can be set by setTitle method and switched on and off by setTitleVisible method.
Method | Description |
---|---|
State changing methods |
|
|
Sets the new title to the axis |
|
Specifies whether the axis title should be drawn |
|
Sets the new font to the axis title |
|
Sets the new font size to the axis title |
|
Sets the new color to the axis title |
Getters and state retrieving methods |
|
|
Returns the color of the axis title |
|
Returns the title of the axis |
|
Checks whether the axis title should be drawn |
|
Returns the font of the axis title |
|
Returns the font size of the axis title |
7.2. Axis labels
The axis labels represents values associated with axis ticks and grid lines. Depending on the axis type, values can be not only numerical, but also categorical etc
Method | Description |
---|---|
State changing methods |
|
|
Sets the new font to the axis labels |
|
Sets the new font size to the axis labels |
|
Sets the new color to the axis labels |
|
Sets the formatter to axis labels, i.e. the function that takes a Double value and produces a String that should be drawn to represent this value |
|
Sets the AxisTimeStyle that specifies the formatting and ticks details for axis in case it shows calendar time. Used only for time-relative axes |
|
Sets the AxisNumericStyle that specifies the formatting and ticks details for axis in case it shows numeric values. Used only for numeric axes |
Getters and state retrieving methods |
|
|
Returns the font of the axis labels |
|
Returns the font size of the axis labels |
|
Returns the color of the axis labels |
|
Returns the AxisTimeStyle |
7.3. Y-Axis auto-adjustment
Some Y-axes (for example, the Y-axis of a Line Chart) support auto-adjustment, depending on the Y-values that displayed within the current X-axis range. Auto-adjustment can be enabled separately for minimum or maximum values. When Auto-adjustment is enabled, the min/max values will dynamically change while the user changes the current X-axis range
Method | Description |
---|---|
State changing methods |
|
|
Specifies an axis mode in which zero is always exists in the displayed range |
|
Specifies an axis mode in which the minimum value is equal to the minimum value of the currently displayed contents |
|
Specifies an axis mode in which the maximum value is equal to the maximum value of the currently displayed contents |
Getters and state retrieving methods |
|
|
Checks whether zero is always exists in the displayed range |
|
Checks whether the minimum value is equal to the minimum value of the currently displayed contents |
|
Checks whether the maximum value is equal to the maximum value of the currently displayed contents |
7.4. X-Axis current value guideline
Chart X-axes with time-related values provide the ability to set the current value (current time). This value is displayed as a guideline that dynamically redraws itself as the current time changes. The chart supports the automatically change of the currently displayed X-axis range following the current time changes. However, this option can be disabled by user.
Method | Description |
---|---|
State changing methods |
|
|
Specifies whether the current value guideline should be drawn |
|
Sets the color of the current value guideline. Transparent and semi-transparent colors are allowed |
|
Sets the width of the current value guideline |
|
Sets the axis current value |
Getters and state retrieving methods |
|
|
Checks if the current value guideline is visible |
|
Returns the color of the current value guideline |
|
Returns the width of the current value guideline |
|
Returns the axis current value |
8. Vertical guideline
This functionality allows you to mark a position on the horizontal axis to get more detailed information about the content values for that position. The values of the crossed content will be displayed in the legend next to the corresponding content titles. A guideline can only be set in those places where the gridline is located. Trying again to set the guideline to the same value will hide it.
Method | Description |
---|---|
State changing methods |
|
|
Specifies whether the vertical guideline functionality should be drawn. True by default. |
|
Specifies whether the vertical guideline label should be drawn. True by default. |
|
Specifies whether the legend values should be drawn. The displayed values are the result of the intersection of the corresponding visual elements with a vertical guideline. True by default. |
|
Shows the vertical guideline in the specified x-axis display position.
Does nothing if the vertical guideline functionality is disabled by calling |
|
Hides the current displayed vertical guideline. Does nothing if the vertical guideline is not currently displayed |
|
Sets the new color to the vertical guideline |
|
Sets the new width to the vertical guideline |
|
Sets the formatter to vertical guideline label, i.e. the function that takes a Double value and produces a String that should be drawn to represent this value |
Getters and state retrieving methods |
|
|
Checks whether vertical guideline is drawn |
|
Checks whether the vertical guideline label is drawn |
|
Checks whether the legend values are drawn |
|
Returns the current color of the vertical guideline |
|
Returns the current width of the vertical guideline |
|
Checks whether vertical guideline is displayed |
|
Returns the current position of vertical guideline |
|
Return the formatter of the vertical guideline label |
Event handlers |
|
|
Adds the action that will be executed every time the vertical guideline visibility or position changed |
|
Removes the vertical guideline visibility or position changed action |
|
Clear all the vertical guideline visibility or position changed actions |
8.1. X-Axis displayed range
The displayed range is the current view area along the X-axis. The options provided for working with this range allow user to view a small number of values in more detail or a large number of values in less detail. This range can be shifted to view the most important range of the content, zoom in/out to control the number of values viewed, fixed with the ability to change the displayed range, or scaled to view all contents displayed on the chart.
Method | Description |
---|---|
State changing methods |
|
|
Sets the minimum size of displayed values range of axis. 0 by default. This size limits the users' ability to scale the range of axis down |
|
Sets the maximum size of displayed values range of axis. Maximum is not limited by default. This size limits the users' ability to scale the range of axis up |
|
Specifies the displayed values range can be changed |
|
Specifies the displayed values range cannot be changed. Displayed values range becomes equals to displayedRangeSize |
|
Sets the currently displayed values range of axis. Scrolls and scales the axis accordingly and redraws the chart |
|
Sets the minimum and maximum displayed values equal to the minimum and maximum values in the chart contents. Used to display a complete set of data within a single displayed range |
|
Resets displayed range to default values. The default state is the range of data items, including the last one i.e. with zero scroll |
|
Specifies whether the displayed range is auto-scrolled during setting new values to any of the displayed visual sets |
Getters and state retrieving methods |
|
|
Returns the minimum size of displayed values range of axis |
|
Returns the maximum size of displayed values range of axis |
|
Checks whether the displayed values range can be changed |
|
Returns the currently displayed values range of axis |
|
Checks if displayed range is auto-scrolled during setting new values to any of the displayed visual sets |
|
Checks whether the value is displayed on the axis |
Event handlers |
|
|
Adds the action that will be executed every time the displayed range changed |
|
Removes the displayed range changed action |
|
Clear all the displayed range changed actions |
9. Grid lines
Grid lines are the lines in the background of the chart visuals, corresponding to the key values of the chart axis. The combination of horizontal and vertical lines forms the coordinate grid of the chart.
Method | Description |
---|---|
State changing methods |
|
|
Specifies whether the chart grid lines should be drawn |
|
Sets the new color to the grid lines. Transparent and semi-transparent colors are allowed |
|
Sets the new width to the grid lines |
|
Specifies whether the zero grid line should be drawn |
|
Sets the new color to the zero grid line |
|
Sets the new width to the zero grid line |
Getters and state retrieving methods |
|
|
Checks whether the grid lines are visible |
|
Returns the color of grid lines |
|
Returns the width of grid lines |
|
Checks whether the zero grid line is visible |
|
Returns the color of zero grid line |
|
Returns the width of zero grid lines |
9.1. Y-axis value limits
The displayed values on the vertical numeric axis can be limited by setting the minimum or maximum possible value. Values less than the minimum or greater than the maximum will not be displayed on the chart, however, all visuals will be displayed as if these values still exist outside the content area.
Method | Description |
---|---|
State changing methods |
|
|
Sets the minimum possible value that can be displayed on axis. The displayed range of axis cannot include values less than the specified value. Scrolling of axis is limited accordingly. |
|
Sets the maximum possible value that can be displayed on axis. The displayed range of axis cannot include values more than the specified value. Scrolling of axis is limited accordingly. |
|
Convenience method, can be used instead of calling two methods setMinValue and setMaxValue. |
Getters and state retrieving methods |
|
|
Returns the minimum possible value that can be displayed on axis |
|
Returns the maximum possible value that can be displayed on axis |
9.2. Gantt-chart Y-axis
The vertical axis of the Gantt-chart differs from other vertical axes by displaying categorical rather than numerical values.
The VisualSets
displayed on the Gantt-chart can be grouped into categories and displayed simultaneously on top of each other, or displayed within different categories.
These categories are called GanttChartRows
.
The list of such GanttChartRows
is a set of vertical axis values and it can be scrolled, navigated, string-searched, and so on.
Method | Description |
---|---|
State changing methods |
|
|
Navigates Y-axis displayed range to specified ganttChartRow. Scrolls the axis accordingly and redraws the chart. Does nothing if the specified ganttChartRow is already in the displayed range |
|
Navigates Y-axis displayed range to ganttChartRow with specified index. Scrolls the axis accordingly and redraws the chart. Does nothing if the specified ganttChartRow is already in the displayed range |
|
Adds tooltip text to display when the mouse is hovered over a vertical axis element |
|
Sets the new font to the tooltip text |
|
Sets the new font size to the tooltip text |
|
Sets the new left margin calculation rule. The possible possible values are: FIXED, DYNAMIC_BY_SHOWED_CONTENT DYNAMIC_BY_SHOWED_CONTENT rule automatically calculates the margin based on the length of the vertical axis element names |
Getters and state retrieving methods |
|
|
Checks if specified value is currently displayed |
|
Returns the index of the first current displayed ganttChartRow |
|
Returns the current left margin calculation rule |
Event handlers |
|
|
Adds the action that will be executed every time any element on the vertical axis is clicked |
|
Removes vertical axis click handler |
|
Removes all vertical axis click handlers |
10. Scrollbars
The scrollbar is an alternative way to change the current displayed range. The main and most commonly used navigation method of X-axis is panning with the right mouse button, however this functionality is duplicated by a scrollbar. Also, the scroll bar allows user to visually determine what part of the contents is currently being displayed.
Method | Description |
---|---|
State changing methods |
|
|
Specifies whether the scrollbar should be drawn if scrolling the displayed range of axis is possible. True by default. If set to false, the scrollbar will never be drawn but the functionality of scrolling the axis will still remain. |
Getters and state retrieving methods |
|
|
Checks whether the horizontal scrollbar should be drawn if scrolling the displayed rang of Y-axis is possible. |
|
Checks whether the horizontal scrollbar is currently displayed |
11. Legend
Legend is a chart visual that displays a list of items with symbols in a box. Clicking on the legend objects allows user to control several ways of displaying visuals on the chart - REGULAR, SHADOWED and HIDDEN. Also the legend is used by the vertical guideline to display Y-axis values for a specific X-axis value.
Method | Description |
---|---|
State changing methods |
|
|
Specifies whether the legend should be drawn |
|
Sets the new font to the legend |
|
Sets the new font size to the legend |
|
Sets the new color to the legend |
|
Resets the set of enabled states of legend items to the default setting. The default setting is {REGULAR, SHADOWED}. |
|
Sets the formatter to legend values, i.e. the function that takes a Double value and produces a String that should be drawn to represent this value |
|
Sets the new state to legend item. Redraws the chart to refresh its contents, axis and legend |
|
Specifies the enabled SHADOWED state of legend items |
|
Specifies the enabled HIDDEN state of legend items |
Getters and state retrieving methods |
|
|
Checks whether the legend should be drawn |
|
Returns the font of the legend |
|
Returns the font font of the legend |
|
Returns the color of the legend |
|
Returns the formatter of the legend values |
|
Returns the current state of legend item |
|
Checks if SHADOWED state of legend items is enabled |
|
Checks if HIDDEN state of legend items is enabled |
Event handlers |
|
|
Adds the action that will be executed every time the legend item state changed |
|
Removes the legend item state changed action |
|
Removes all the legend item state changed actions |
12. Histogram
Bar chart
provides an opportunity to display histograms, which is an approximate representation of the distribution of numerical data.
The displayed values are distributed into ranges with a minimum and maximum value, and the Y-axis provides an opportunity to evaluate the percentage distribution of values in different ranges.
Method | Description |
---|---|
State changing methods |
|
|
Specifies whether the labels of CDF (cumulative distribution function) should be drawn. |
|
Specifies whether the line of CDF (cumulative distribution function) should be drawn. |
|
Sets the new color to the line of CDF (cumulative distribution function) |
|
Sets the new width to the line of CDF (cumulative distribution function) |
Getters and state retrieving methods |
|
|
Checks if the line of the CDF (cumulative distribution function) should be drawn |
|
Checks if the labels of the CDF (cumulative distribution function) should be drawn |
|
Returns the color of the line of CDF (cumulative distribution function) |
|
Returns the width of the line of CDF (cumulative distribution function) |