@nativescript-community/ui-chart 1.2.36 → 2.0.1

package/charts/Chart.d.ts

@@ -1,6 +1,6 @@
 import { PanGestureHandlerOptions, PinchGestureHandlerOptions, RotationGestureHandlerOptions, TapGestureHandlerOptions } from '@nativescript-community/gesturehandler';
 import { Canvas, CanvasView, Paint } from '@nativescript-community/ui-canvas';
-import { EventData } from '@nativescript/core';
+import { EventData, Font } from '@nativescript/core';
 import { ChartAnimator, EasingFunction } from '../animation/ChartAnimator';
 import { Description } from '../components/Description';
 import { IMarker } from '../components/IMarker';
@@ -22,40 +22,134 @@ export interface HighlightEventData extends EventData {
     entry?: Entry;
     highlight?: Highlight;
 }
+/**
+ * Baseclass of all Chart-Views.
+ *
+
+ */
 export declare abstract class Chart<U extends Entry, D extends IDataSet<U>, T extends ChartData<U, D>> extends CanvasView implements ChartInterface {
-    abstract getYChartMin(): any;
-    abstract getYChartMax(): any;
-    abstract getMaxVisibleCount(): any;
+    abstract yChartMin: number;
+    abstract yChartMax: number;
+    abstract maxVisibleValueCount: number;
+    /**
+     * object that holds all data that was originally set for the chart, before
+     * it was modified or any filtering algorithms had been applied
+     */
     protected mData: T;
-    protected mHighLightPerTapEnabled: any;
-    private mDragDecelerationEnabled;
-    private mDragDecelerationFrictionCoef;
-    protected mDefaultValueFormatter: DefaultValueFormatter;
-    protected mDescPaint: Paint;
-    protected mInfoPaint: Paint;
-    protected mXAxis: XAxis;
-    protected mTouchEnabled: boolean;
-    protected mDescription: Description;
+    /**
+     * Flag that indicates if highlighting per tap (touch) is enabled
+     */
+    protected mHighlightPerTapEnabled: boolean;
+    /**
+     * If set to true, chart continues to scroll after touch up
+     */
+    dragDecelerationEnabled: boolean;
+    /**
+     * Deceleration friction coefficient in [0 ; 1] interval, higher values
+     * indicate that speed will decrease slowly, for example if it set to 0, it
+     * will stop immediately. value must be < 1.0
+     */
+    dragDecelerationFrictionCoef: number;
+    /**
+     * the default IValueFormatter that has been determined by the chart
+     * considering the provided minimum and maximum values, number of digits depends on provided chart-data
+     */
+    defaultValueFormatter: DefaultValueFormatter;
+    /**
+     * palet object used for drawing the description text in the bottom right
+     * corner of the chart
+     */
+    descPaint: Paint;
+    /**
+     * palet object for drawing the information text when there are no values in
+     * the chart
+     */
+    mInfoPaint: Paint;
+    /**
+     * the object representing the labels on the x-axis
+     */
+    xAxis: XAxis;
+    /**
+     * if true, touch gestures are enabled on the chart
+     */
+    touchEnabled: boolean;
+    /**
+     * the object responsible for representing the description text
+     */
+    mDescription: Description;
+    /**
+     * the legend object containing all data associated with the legend
+     */
     protected mLegend: Legend;
-    protected mChartTouchListener: ChartTouchListener<any>;
-    private mNoDataText;
-    protected mLegendRenderer: LegendRenderer;
-    protected mRenderer: DataRenderer;
-    protected mHighlighter: IHighlighter;
-    protected mViewPortHandler: ViewPortHandler;
-    protected mAnimator: ChartAnimator;
-    private mExtraTopOffset;
-    private mExtraRightOffset;
-    private mExtraBottomOffset;
-    private mExtraLeftOffset;
-    protected mOffsetsCalculated: any;
-    protected noComputeOnNextDraw: any;
-    protected mIndicesToHighlight: Highlight[];
-    protected mMaxHighlightDistance: number;
-    protected mJobs: any[];
+    chartTouchListener: ChartTouchListener<any>;
+    /**
+     * text that is displayed when the chart is empty
+     */
+    noDataText: any;
+    /**
+     * Gesture listener for custom callbacks when making gestures on the chart.
+     */
+    legendRenderer: LegendRenderer;
+    /**
+     * object responsible for rendering the data
+     */
+    renderer: DataRenderer;
+    highlighter: IHighlighter;
+    /**
+     * object that manages the bounds and drawing constraints of the chart
+     */
+    viewPortHandler: ViewPortHandler;
+    /**
+     * object responsible for animations
+     */
+    animator: ChartAnimator;
+    /**
+     * Extra offsets to be appended to the viewport
+     */
+    extraTopOffset: number;
+    extraRightOffset: number;
+    extraBottomOffset: number;
+    extraLeftOffset: number;
+    /**
+     * flag that indicates if offsets calculation has already been done or not
+     */
+    protected offsetsCalculated: any;
+    /**
+     * let the chart know it does not need to compute autoScale
+     * (it can used the cached ones)
+     */
+    noComputeAutoScaleOnNextDraw: boolean;
+    /**
+     * let the chart know it does not need to compute axis and legends
+     * (it can used the cached ones)
+     */
+    noComputeAxisOnNextDraw: boolean;
+    /**
+     * array of Highlight objects that reference the highlighted slices in the
+     * chart
+     */
+    indicesToHighlight: Highlight[];
+    /**
+     * The maximum distance in dp away from an entry causing it to highlight.
+     */
+    maxHighlightDistance: number;
+    /**
+     * Wether to filter highlights by axis. Default is true
+     */
+    highlightsFilterByAxis: boolean;
+    /**
+     * tasks to be done after the view is setup
+     */
+    protected jobs: any[];
+    /**
+     * default constructor for initialization in code
+     */
     constructor();
     initNativeView(): void;
     disposeNativeView(): void;
+    /**
+     * initialize all paints and stuff
+     */
     protected init(): void;
     get infoPaint(): Paint;
     panGestureOptions: PanGestureHandlerOptions & {
@@ -73,102 +167,337 @@ export declare abstract class Chart<U extends Entry, D extends IDataSet<U>, T ex
     rotationGestureOptions: RotationGestureHandlerOptions & {
         gestureTag?: number;
     };
-    setData(data: T): void;
+    /**
+     * Sets a new data object for the chart. The data object contains all values
+     * and information needed for displaying.
+     *
+     * @param data
+     */
+    set data(data: T);
+    /**
+     * Returns the ChartData object that has been set for the chart.
+     */
+    get data(): T;
+    get viewPortScaleX(): number;
+    get viewPortScaleY(): number;
+    /**
+     * Clears the chart from all data (sets it to null) and refreshes it (by
+     * calling invalidate()).
+     */
     clear(): void;
+    /**
+     * Removes all DataSets (and thereby Entries) from the chart. Does not set the data object to null. Also refreshes the
+     * chart by calling invalidate().
+     */
     clearValues(): void;
-    length(): boolean;
+    /**
+     * Returns true if the chart is empty (meaning it's data object is either
+     * null or contains no entries).
+     */
+    get length(): boolean;
+    /**
+     * Lets the chart know its underlying data has changed and performs all
+     * necessary recalculations. It is crucial that this method is called
+     * everytime data is changed dynamically. Not calling this method can lead
+     * to crashes or unexpected behaviour.
+     */
     abstract notifyDataSetChanged(): any;
+    /**
+     * Calculates the offsets of the chart to the border depending on the
+     * position of an eventual legend or depending on the length of the y-axis
+     * and x-axis labels and their position
+     */
     protected abstract calculateOffsets(force?: boolean): any;
+    /**
+     * Calculates the y-min and y-max value and the y-delta and x-delta value
+     */
     protected abstract calcMinMax(): any;
+    /**
+     * Calculates the required number of digits for the values that might be
+     * drawn in the chart (if enabled), and creates the default-value-formatter
+     */
     protected setupDefaultFormatter(min: any, max: any): void;
     onDraw(canvas: Canvas): void;
+    /**
+     * Draws the description text in the bottom right corner of the chart (per default)
+     */
     protected drawDescription(c: Canvas): void;
-    getMaxHighlightDistance(): number;
-    setMaxHighlightDistance(distDp: any): void;
-    getHighlighted(): Highlight<Entry>[];
-    isHighlightPerTapEnabled(): any;
-    setHighlightPerTapEnabled(enabled: any): void;
-    valuesToHighlight(): boolean;
-    protected setLastHighlighted(highs: any): void;
+    /**
+     * Returns the array of currently highlighted values. This might a null or
+     * empty array if nothing is highlighted.
+     */
+    get highlighted(): Highlight<Entry>[];
+    /**
+     * Returns true if there are values to highlight, false if there are no
+     * values to highlight. Checks if the highlight array is null, has a length
+     * of zero or if the first object is null.
+     *
+     */
+    get hasValuesToHighlight(): boolean;
+    /**
+     * Sets the last highlighted value for the touchlistener.
+     *
+     * @param highs
+     */
+    protected set lastHighlighted(highs: any);
+    /**
+     * Highlights the values at the given indices in the given DataSets. Provide
+     * null or an empty array to undo all highlighting. This should be used to
+     * programmatically highlight values.
+     * This method *will not* call the listener.
+     *
+     * @param highs
+     */
     highlightValues(highs: any): void;
+    /**
+     * Highlights any y-value at the given x-value in the given DataSet.
+     * Provide -1 as the dataSetIndex to undo all highlighting.
+     * @param x The x-value to highlight
+     * @param y The y-value to highlight. Supply `NaN` for "any"
+     * @param dataSetIndex The dataset index to search in
+     * @param callListener Should the listener be called for this change
+     */
     highlightValue(x: any, y: any, dataSetIndex: any, callListener?: boolean): void;
-    highlight(high: Highlight, callListener?: boolean): void;
+    /**
+     * Highlights the value selected by touch gesture. Unlike
+     * highlightValues(...), this generates a callback to the
+     * OnChartValueSelectedListener.
+     *
+     * @param high         - the highlight object
+     * @param callListener - call the listener
+     */
+    highlight(high: Highlight | Highlight[], callListener?: boolean): void;
+    /**
+     * Highlights the value selected by touch gesture. Unlike
+     * highlightValues(...), this generates a callback to the
+     * OnChartValueSelectedListener.
+     *
+     * @param high         - the highlight object
+     * @param callListener - call the listener
+     */
+    highlights(highs: Highlight[], callListener?: boolean): void;
+    /**
+     * Returns the Highlights (contains x-index and DataSet index) of the
+     * selected value at the given touch polet inside the Line-, Scatter-, or
+     * CandleStick-Chart.
+     *
+     * @param x
+     * @param y
+     * @return
+     */
+    getHighlightsByTouchPoint(x: any, y: any): Highlight<Entry>[];
+    /**
+     * Returns the Highlight object (contains x-index and DataSet index) of the
+     * selected value at the given touch polet inside the Line-, Scatter-, or
+     * CandleStick-Chart.
+     *
+     * @param x
+     * @param y
+     * @return
+     */
     getHighlightByTouchPoint(x: any, y: any): Highlight<Entry>;
+    /**
+     * Returns the Highlight object (contains x-index and DataSet index) of the
+     * selected value at the given touch polet inside the Line-, Scatter-, or
+     * CandleStick-Chart.
+     *
+     * @param x
+     * @param y
+     * @return
+     */
     getHighlightByXValue(xValue: any): Highlight<Entry>[];
-    protected mDrawMarkers: boolean;
-    protected mMarker: IMarker;
+    /**
+     * ################ ################ ################ ################
+     */
+    /** BELOW CODE IS FOR THE MARKER VIEW */
+    /**
+     * if set to true, the marker view is drawn when a value is clicked
+     */
+    drawMarkersEnabled: boolean;
+    /**
+     * the view that represents the marker
+     */
+    marker: IMarker;
+    /**
+     * draws all MarkerViews on the highlighted positions
+     */
     protected drawMarkers(canvas: Canvas): void;
+    /**
+     * Returns the actual position in pixels of the MarkerView for the given
+     * Highlight object.
+     *
+     * @param high
+     * @return
+     */
     protected getMarkerPosition(high: Highlight): number[];
-    getAnimator(): ChartAnimator;
-    isDragDecelerationEnabled(): boolean;
-    setDragDecelerationEnabled(enabled: any): void;
-    getDragDecelerationFrictionCoef(): number;
-    setDragDecelerationFrictionCoef(newValue: any): void;
+    /**
+     * ################ ################ ################ ################
+     * ANIMATIONS ONLY WORK FOR API LEVEL 11 (Android 3.0.x) AND HIGHER.
+     */
+    /** CODE BELOW THIS RELATED TO ANIMATION */
+    /**
+     * Returns the animator responsible for animating chart values.
+     */
+    get description(): Description;
+    /**
+     * ################ ################ ################ ################
+     * ANIMATIONS ONLY WORK FOR API LEVEL 11 (Android 3.0.x) AND HIGHER.
+     */
+    /** CODE BELOW FOR PROVIDING EASING FUNCTIONS */
+    /**
+     * Animates the drawing / rendering of the chart on both x- and y-axis with
+     * the specified animation time. If animate(...) is called, no further
+     * calling of invalidate() is necessary to refresh the chart. ANIMATIONS
+     * ONLY WORK FOR API LEVEL 11 (Android 3.0.x) AND HIGHER.
+     *
+     * @param durationMillisX
+     * @param durationMillisY
+     * @param easingX         a custom easing function to be used on the animation phase
+     * @param easingY         a custom easing function to be used on the animation phase
+     */
     animateXY(durationMillisX: any, durationMillisY: any, easingX?: EasingFunction, easingY?: EasingFunction): void;
+    /**
+     * Animates the rendering of the chart on the x-axis with the specified
+     * animation time. If animate(...) is called, no further calling of
+     * invalidate() is necessary to refresh the chart. ANIMATIONS ONLY WORK FOR
+     * API LEVEL 11 (Android 3.0.x) AND HIGHER.
+     *
+     * @param durationMillis
+     * @param easing         a custom easing function to be used on the animation phase
+     */
     animateX(durationMillis: any, easing?: EasingFunction): void;
+    /**
+     * Animates the rendering of the chart on the y-axis with the specified
+     * animation time. If animate(...) is called, no further calling of
+     * invalidate() is necessary to refresh the chart. ANIMATIONS ONLY WORK FOR
+     * API LEVEL 11 (Android 3.0.x) AND HIGHER.
+     *
+     * @param durationMillis
+     * @param easing         a custom easing function to be used on the animation phase
+     */
     animateY(durationMillis: any, easing?: EasingFunction): void;
-    getXAxis(): XAxis;
-    getDefaultValueFormatter(): DefaultValueFormatter;
-    getYMax(): number;
-    getYMin(): number;
-    getXChartMax(): number;
-    getXChartMin(): number;
-    getXRange(): number;
-    getCenter(): {
+    /**
+     * ################ ################ ################ ################
+     */
+    /** BELOW THIS ONLY GETTERS AND SETTERS */
+    /**
+     * returns the current y-max value across all DataSets
+     */
+    get yMax(): number;
+    /**
+     * returns the current y-min value across all DataSets
+     */
+    get yMin(): number;
+    get xChartMax(): number;
+    get xChartMin(): number;
+    get xRange(): number;
+    /**
+     * Returns a recyclable MPPointF instance.
+     * Returns the center polet of the chart (the whole View) in pixels.
+     */
+    get center(): {
         x: number;
         y: number;
     };
-    getCenterOffsets(): {
+    /**
+     * Returns a recyclable MPPointF instance.
+     * Returns the center of the chart taking offsets under consideration.
+     * (returns the center of the content rectangle)
+     */
+    get centerOffsets(): {
         x: number;
         y: number;
     };
+    /**
+     * Sets extra offsets (around the chart view) to be appended to the
+     * auto-calculated offsets.
+     *
+     * @param left
+     * @param top
+     * @param right
+     * @param bottom
+     */
     setExtraOffsets(left: any, top: any, right: any, bottom: any): void;
-    setExtraTopOffset(offset: any): void;
-    getExtraTopOffset(): number;
-    setExtraRightOffset(offset: any): void;
-    getExtraRightOffset(): number;
-    setExtraBottomOffset(offset: any): void;
-    getExtraBottomOffset(): number;
-    setExtraLeftOffset(offset: any): void;
-    getExtraLeftOffset(): number;
-    setNoDataText(text: any): void;
-    setNoDataTextColor(color: any): void;
-    setNoDataTextTypeface(tf: any): void;
-    setTouchEnabled(enabled: any): void;
-    setMarker(marker: IMarker): void;
-    getMarker(): IMarker;
-    setMarkerView(v: IMarker): void;
-    getMarkerView(): IMarker;
-    setDescription(desc: Description): void;
-    getDescription(): Description;
-    getLegend(): Legend;
-    getLegendRenderer(): LegendRenderer;
-    getContentRect(): import("@nativescript-community/ui-canvas").RectF;
-    isDrawMarkerViewsEnabled(): boolean;
-    setDrawMarkerViews(enabled: any): void;
-    isDrawMarkersEnabled(): boolean;
-    setDrawMarkers(enabled: any): void;
-    getData(): T;
-    getViewPortHandler(): ViewPortHandler;
-    getRenderer(): DataRenderer;
-    setRenderer(renderer: any): void;
-    getHighlighter(): IHighlighter;
-    setHighlighter(highlighter: IHighlighter): void;
-    getCenterOfView(): {
+    /**
+     * Sets extra offsets (around the chart view) to be appended to the
+     * auto-calculated offsets.
+     *
+     * @param left
+     * @param top
+     * @param right
+     * @param bottom
+     */
+    set extraOffsets(value: [number, number, number, number]);
+    /**
+     * Sets the color of the no data text.
+     *
+     * @param color
+     */
+    set noDataTextColor(color: any);
+    /**
+     * Sets the typeface to be used for the no data text.
+     */
+    set noDataTextTypeface(tf: Font);
+    /**
+     * Returns the Legend object of the chart. This method can be used to get an
+     * instance of the legend in order to customize the automatically generated
+     * Legend.
+     */
+    get legend(): Legend;
+    /**
+     * Returns the rectangle that defines the borders of the chart-value surface
+     * (into which the actual values are drawn).
+     */
+    get contentRect(): import("@nativescript-community/ui-canvas").RectF;
+    /**
+     * Returns a recyclable MPPointF instance.
+     */
+    get centerOfView(): {
         x: number;
         y: number;
     };
-    getChartBitmap(): void;
-    saveToPath(title: any, pathOnSD: any): boolean;
-    saveToGallery(fileName: any, subFolderPath: any, fileDescription: any, format: any, quality: any): void;
+    /**
+     * Flag that indicates if highlighting per tap (touch) is enabled
+     */
+    get highlightPerTapEnabled(): boolean;
+    /**
+     * Flag that indicates if highlighting per tap (touch) is enabled
+     */
+    set highlightPerTapEnabled(value: boolean);
+    /**
+     * Returns the bitmap that represents the chart.
+     */
+    get chartBitmap(): any;
     removeViewportJob(job: any): void;
     clearAllViewportJobs(): void;
+    /**
+     * Either posts a job immediately if the chart has already setup it's
+     * dimensions or adds the job to the execution queue.
+     *
+     * @param job
+     */
     addViewportJob(job: ViewPortJob): void;
+    /**
+     * Returns all jobs that are scheduled to be executed after
+     * onSizeChanged(...).
+     */
     getJobs(): any[];
     onSetWidthHeight(w: number, h: number): void;
     onLayout(left: number, top: number, right: number, bottom: number): void;
     onSizeChanged(w: number, h: number, oldw: number, oldh: number): void;
-    setHardwareAccelerationEnabled(enabled: any): void;
+    /**
+     * Setting this to true will set the layer-type HARDWARE for the view, false
+     * will set layer-type SOFTWARE.
+     *
+     * @param enabled
+     */
+    set hardwareAccelerationEnabled(enabled: any);
+    /**
+     * disables intercept touchevents
+     */
     disableScroll(): void;
+    /**
+     * enables intercept touchevents
+     */
     enableScroll(): void;
 }