Package com.iizix.prop.ui.chart

Class UIChart

  • All Implemented Interfaces:
    EventListener, IMessageBox, IComponent, ICustomDataProvider, IGProp<GProp<?>[]>, IPropCnr, IPropCnrChoiceSettings<IChartChoiceOption>, IPropCnrColorSettings<ChartColor>, IPropCnrFontSettings<ChartFont>, IPropCnrIntegerSettings<ChartInteger>, IPropCnrKStringSettings<ChartKString>, IUIComp, IUIContextMenuOwner, IVSComponentListener, IVSComponentState, IVSFieldListener, java.lang.Cloneable
    Direct Known Subclasses:
    EUIChart
    public class UIChart
extends UIComp
implements IPropCnrIntegerSettings<ChartInteger>, IPropCnrKStringSettings<ChartKString>, IPropCnrFontSettings<ChartFont>, IPropCnrColorSettings<ChartColor>, IPropCnrChoiceSettings<IChartChoiceOption>, IUIContextMenuOwner
    Chart UI component.

    Chart Components: Plots, Axes, Series

    Defining a basic chart and implementing its theme is quite simple. The real work comes in when defining plots, axes, and series. Each piece serves its own distinct, important purpose.

    Plots

    One of the main focuses of plots within charting is defining the type of chart to be added and providing values for the specific chart type's settings. The charting features numerous 2D charts including:

    • Default - Universal line chart capable of rendering lines, fill areas under those lines, and placing markers at data points. This plot type is used if no plot type was specified when adding it to a chart.
    • Lines - Basic line chart. Uses Default.
    • Areas - Area under data line(s) will be filled. Uses Default.
    • Markers - Lines with markers. Uses Default.
    • MarkersOnly - Markers, sans lines. Uses Default.
    • Stacked - Data sets charted in relation to the previous data set. Extension of Default.
    • StackedLines - Stacked data sets using lines. Uses Stacked.
    • StackedAreas - Stacked data sets with filled areas under chart lines. Uses Stacked.
    • Bars - Horizontal bars.
    • ClusteredBars - Horizontal bars with clustered data sets. Uses Bars.
    • StackedBars - Stacked data sets with horizontal bars. Uses Bars.
    • Columns - Vertical bars.
    • ClusteredColumns - Vertical bars with clustered data sets. Uses Columns.
    • StackedColumns - Stacked data sets with vertical bars. Uses Columns.
    • Pie - The traditional pie chart.
    • Scatter - Similar to MarkerOnly, yet capable of charting using gradient fields.
    • Grid - For adding a grid layer to your chart.

    Some of the standard plot options include:

    • type - The chart type (Pie, Bars, Scatter, etc).
    • lines - Represents if lines should be added within the chart.
    • markers - Represents if markers should be added to data points within the chart.
    • areas - Represents if areas within the chart should be shaded.
    • shadows - Represents if shadows should be added to lines within the plot (ex: {dx:4, dy:4}).
    • tension - Adds curves to lines within plots for added smoothness. Values can be:
      X - Cubic bezier lines.
      x - Similar to "X" but assumes that the point set is closed (a loop). It can be used when plotting true XY data.
      S - Quadratic bezier lines.
    • gap - Represents the number of pixels between bars.

    Each chart type may have its own custom options. The Pie plot type, for example, has a radius setting which defines the size of the chart's radius:

    Axes

    Most charts feature axes and many of those are the traditional x and y setup. An axis may be horizontal (the default) or vertical.

    Some of the standard axis options include:

    • fixUpper - Aligns chart ticks (can be "major", "minor", "micro", and "none").
    • fixLower - Aligns chart ticks (can be "major", "minor", "micro", and "none").
    • leftBottom - Determines the side of the chart the axis is placed (default is true).
    • min - The minimum number an axis can start at.
    • max - The maximum number an axis can end at.

    Series

    This element is simply a series of data to be rendered to the chart. A series is added to the chart with the addSeries method. The addSeries method accepts three arguments:

    • name - The name of the series. Also represents the series label when the Legend plugin is used.
    • data - The array of data.
    • options An object containing series options, which may include:
      stroke - Color and width of lines (ex: { color:"red", width: 2 }).
      fill - Fill color of bar / line / pie piece.
    A chart can have any number of overlapping series as the developer would like. Each element in the data series must be of the same format, i.e. single value, or multi-axes (X/Y).

    Plugins:

    • Legend: Charts often include legends to further clarify the data provided within the chart.
    • Tooltip:
      sheds light on values when hovering over marks and chart pieces, depending on the chart type.
    • Magnify and MoveSlide:
      uses a touch of animation to react to the mouse's mouseover event. MoveSlice moves a pie chart piece and Magnify slightly enlarges chart markers.
    • Highlight: changes the color of an area when the mouse enters the area.
    Author:
    Christopher Mindus

    • Constructor Detail

      • UIChart

        public UIChart()
        Creates the component without a name. The name must be set in all cases using the setPropertyAtom call.

      • UIChart

        public UIChart​(Atom propertyAtom)
        Creates the component with the specified name. All system-reserved names for components begins with "$".
        Parameters:
        propertyAtom - the name of the component, unique within it's parent.

    • Method Detail

      • clone

        public UIChart clone()
        Creates a clone out of this property. The cloning is overridden by the subclasses in order to handle cloning of its class variables appropriately.
        Overrides:
        clone in class UIComp
        Returns:
        A new chart clone with auto-rendering turned on.

      • usesPropIndex

        public final boolean usesPropIndex()
        Checks if index is relevant for this container, e.g. to keep the Z-ordering of components.
        Specified by:
        usesPropIndex in interface IPropCnr
        Overrides:
        usesPropIndex in class PropCnr
        Returns:
        true, the chart is index-sensitive.

      • getDeviceType

        public final int getDeviceType()
        Gets the device type: -1=mobile, 0=both, 1=desktop.
        Specified by:
        getDeviceType in interface IUIComp
        Returns:
        0=both desktop and mobile support.

      • isMobileContextMenuSupported

        public boolean isMobileContextMenuSupported()
        Returns if the component can show the context menu in mobile mode.
        Specified by:
        isMobileContextMenuSupported in interface IUIContextMenuOwner
        Returns:
        Chart support context menus for mobile.

      • mustHaveWidth

        public boolean mustHaveWidth()
        Does this component require a width?
        Overrides:
        mustHaveWidth in class UIComp
        Returns:
        true, always.

      • mustHaveHeight

        public boolean mustHaveHeight()
        Does this component require a height?
        Overrides:
        mustHaveHeight in class UIComp
        Returns:
        true, always.

      • hasImplicitAlignFillX

        public boolean hasImplicitAlignFillX()
        Returns if the component has implicit component horizontal fill.
        Overrides:
        hasImplicitAlignFillX in class UIComp
        Returns:
        Always true: true means component will always fill the space in X.

      • hasImplicitAlignFillY

        public boolean hasImplicitAlignFillY()
        Returns if the component has implicit component vertical fill.
        Overrides:
        hasImplicitAlignFillY in class UIComp
        Returns:
        Always: true means component will always fill the space in Y.

      • canAlignX

        public boolean canAlignX()
        Returns if the component can be aligned left, right, center, or horizontal fill.
        Overrides:
        canAlignX in class UIComp
        Returns:
        true by default, components override to return false if they are fixed in width or take up the entire width.

      • canAlignY

        public boolean canAlignY()
        Returns if the component can be aligned top, bottom, middle or vertical fill.
        Overrides:
        canAlignY in class UIComp
        Returns:
        true by default, components override to return false if they are fixed in height or take up the entire height.

      • createTitleProp

        protected KStringProp createTitleProp()
        Creates the title property a StringProp, KStringProp or PlainKStringProp depending on the component.
        Overrides:
        createTitleProp in class UIComp
        Returns:
        A new KStringProp named Atom.TITLE.

      • getTheme

        public ChartTheme getTheme()
        Gets the chart theme.
        Returns:
        The chart theme.

      • setTheme

        public void setTheme​(ChartTheme theme)
        Sets the chart theme. Null means default theme.
        Parameters:
        theme - The chart theme.

      • getTitlePosition

        public TitlePosition getTitlePosition()
        Gets the title position.
        Returns:
        The title position.

      • addAxis

        public UIChart addAxis​(Axis2D axis)
                throws PropException
        Adds a new axis to the chart.

        Calling this method turns off auto-rendering and you must complete chart rendering with {link @#render()}.

        Parameters:
        axis - The axis instance.
        Returns:
        this instance for concatenation use.
        Throws:
        PropException - If the axis already exists, or if the name is taken.

      • getAxis

        public Axis2D getAxis​(java.lang.String name)
        Gets an axis by name.
        Parameters:
        name - The name of the axis.
        Returns:
        The instance of the axis, or null if not found.

      • getAxes

        public Axis2D[] getAxes()
        Gets all defined axes.
        Returns:
        The axes array in the current order (the top-most axis is the first).

      • removeAxis

        public boolean removeAxis​(java.lang.String name)
                   throws PropException
        Removes an axis by name.
        Parameters:
        name - The name of the axis.
        Returns:
        true for success, false for failure.
        Throws:
        PropException - In case of property errors such as read-only chart property.

      • removeAxis

        public boolean removeAxis​(Axis2D axis)
                   throws PropException
        Removes an axis by reference.
        Parameters:
        axis - The axis instance.
        Returns:
        true for success, false for failure.
        Throws:
        PropException - In case of property errors such as read-only chart property.

      • getDefaultPlot

        public Plot2D getDefaultPlot()
        Gets the default plot of the chart. This instance MUST be present in order for the chart to be rendered. If it has been removed, the chart will be in error state.
        Returns:
        The default plot, or null if it is not yet added or has been removed.

      • addPlot

        public UIChart addPlot​(Plot2D plot)
                throws PropException
        Adds a new plot to the chart.

        Calling this method turns off auto-rendering and you must complete chart rendering with {link @#render()}.

        Parameters:
        plot - The plot instance.
        Returns:
        this instance for concatenation use.
        Throws:
        PropException - If the plot already exists, or if the name is taken.

      • getPlot

        public Plot2D getPlot​(java.lang.String name)
        Gets a plot by name.
        Parameters:
        name - The name of the plot.
        Returns:
        The instance of the plot, or null if not found.

      • getPlots

        public Plot2D[] getPlots()
        Gets all defined plots.
        Returns:
        The plot array in the current order (the top-most plot is the first).

      • removePlot

        public boolean removePlot​(java.lang.String name)
                   throws PropException
        Removes a plot by name.
        Parameters:
        name - The name of the plot.
        Returns:
        true for success, false for failure.
        Throws:
        PropException - In case of property errors such as read-only chart property.

      • removePlot

        public boolean removePlot​(Plot2D plot)
                   throws PropException
        Removes a plot by reference.
        Parameters:
        plot - The plot instance.
        Returns:
        true for success, false for failure.
        Throws:
        PropException - In case of property errors such as read-only chart property.

      • addSeries

        public UIChart addSeries​(Series series)
                  throws PropException
        Adds a new series to the chart.

        Calling this method turns off auto-rendering and you must complete chart rendering with {link @#render()}.

        Parameters:
        series - The series instance.
        Returns:
        this instance for concatenation use.
        Throws:
        PropException - If the series already exists, or if the name is taken.

      • getSeries

        public Series getSeries​(java.lang.String name)
        Gets a series by name.
        Parameters:
        name - The name of the series.
        Returns:
        The instance of the series, or null if not found.

      • getSeries

        public Series[] getSeries()
        Gets all defined series.
        Returns:
        The series array in the current order (the top-most series is the first).

      • removeSeries

        public boolean removeSeries​(java.lang.String name)
                     throws PropException
        Removes a series by name.
        Parameters:
        name - The name of the series.
        Returns:
        true for success, false for failure.
        Throws:
        PropException - In case of property errors such as read-only chart property.

      • removeSeries

        public boolean removeSeries​(Series series)
                     throws PropException
        Removes a series by reference.
        Parameters:
        series - The series instance.
        Returns:
        true for success, false for failure.
        Throws:
        PropException - In case of property errors such as read-only chart property.

      • hasSeries

        public boolean hasSeries​(int vs)
        Returns whether the chart contains data series with or without VS table connections.
        Parameters:
        vs - The VS connection check: -1 = all data series, 0 = only without VS tables, 1 = only with VS tables.
        Returns:
        true if there are data series with the matching VS connection check flag.

      • moveToFront

        public final int moveToFront​(java.lang.String name)
                      throws PropException
        Moves an axis, plot or series to the front.
        Parameters:
        name - The name of the axis, plot or series.
        Returns:
        1 for success and change to chart, zero for success but no change, -1 if not found.
        Throws:
        PropException - In case of property errors such as read-only chart property.

      • moveToFront

        public final int moveToFront​(IChartContainer axisPlotOrSeries)
                      throws PropException
        Moves an axis, plot or series to the front.
        Parameters:
        axisPlotOrSeries - Axis, plot or series to move.
        Returns:
        1 for success and change to chart, zero for success but no change, -1 if not found.
        Throws:
        PropException - In case of property errors such as read-only chart property.

      • moveToBack

        public final int moveToBack​(java.lang.String name)
                     throws PropException
        Moves an axis, plot or series to the back.
        Parameters:
        name - The name of the axis, plot or series.
        Returns:
        1 for success and change to chart, zero for success but no change, -1 if not found.
        Throws:
        PropException - In case of property errors such as read-only chart property.

      • moveToBack

        public final int moveToBack​(IChartContainer axisPlotOrSeries)
                     throws PropException
        Moves an axis, plot or series to the back.
        Parameters:
        axisPlotOrSeries - The axis, plot or series to move.
        Returns:
        1 for success and change to chart, zero for success but no change, -1 if not found.
        Throws:
        PropException - In case of property errors such as read-only chart property.

      • validate

        public java.lang.String validate()
        Validates the chart.
        Returns:
        null for success, otherwise the first error message.

      • isAutoRendering

        public boolean isAutoRendering()
        Returns whether auto-rendering is enabled for the chart or not.

        If not auto-rendered, you MUST call the {link @#render()} method in order to visualize the chart (or its changes).

        If auto-rendered, the chart is rendered immediately upon creation, or for changes with a delay of 300 ms since the last update to the chart or any of its settings, plot, axis, series or values.

        If auto-rendering is on, you may still call the {link @#render()} method in order to perform an immediate rendering.

        Returns:
        The auto-render flag.

      • setAutoRendering

        public boolean setAutoRendering​(boolean on)
        Sets the auto-rendering flag.

        If not auto-rendered, you MUST call the {link @#render()} method in order to visualize the chart (or its changes).

        If auto-rendered, the chart is rendered immediately upon creation, or for changes with a delay of 300 ms since the last update to the chart or any of its settings, plot, axis, series or values.

        If auto-rendering is on, you may still call the {link @#render()} method in order to perform an immediate rendering.

        Parameters:
        on - The auto-rendering flag.
        Returns:
        The auto-render flag.

      • render

        public java.lang.String render()
        Renders the chart. Before rendering, validation is performed in order to check the chart state and a potential error is returned rather than rendering the chart.
        Returns:
        null for success, otherwise the error message.

      • zoomin

        public int zoomin​(Axis2D axis,
                  int start,
                  int end)
        Zooms in on an axis.
        Parameters:
        axis - The axis instance.
        start - The start point measured in axis ticks.
        end - The end point measured in axis ticks.
        Returns:
        1 for success, zero for no change or -1 for failure.

      • zoomout

        public boolean zoomout()
        Zooms out from any axis zoom-in.
        Returns:
        true for success, false for no change.

      • setWindow

        public int setWindow​(double sx,
                     double sy,
                     double dx,
                     double dy,
                     int duration)
        Zooms in or out any plots in two dimensions.
        Parameters:
        sx - The scale for the x axis (greater than zero).
        sy - The scale for the y axis (greater than zero).
        dx - The pixel offset on the x axis.
        dy - The pixel offset on the y axis.
        duration - Duration for the chart zooming animation trigger, zero for none, otherwise a value in milliseconds e.g. 1200.
        Returns:
        1 for success, zero for no change or -1 for failure (sx/sy less or equal to zero, duration negative).

      • clearWindow

        public int clearWindow​(int duration)
        Clears the zooms in or out any plots in two dimensions.
        Parameters:
        duration - Duration for the chart zooming animation trigger, zero for none, otherwise a value in milliseconds e.g. 1200.
        Returns:
        1 for success, zero for no change or -1 for failure (duration negative).

      • getApproximateSize

        public Size getApproximateSize()
        Returns the size of the component in pixels. The size is a calculation and does not exactly reflect the real size that may be different due to additional styles not taken into account by this method. The size is calculated from the font of the component and default or defined values (such as character length or number of lines for text area).
        Specified by:
        getApproximateSize in class UIComp
        Returns:
        The size of the component: 400x300.

      • refresh

        public void refresh()
        Requests a refresh of the chart to update the data series from their respective VS tables and columns.

        The series are not refreshed upon returning from the call, it is done at a later stage.