From 4a191d5af9b7dece2c1b1e7566da0aaff3f7be3c Mon Sep 17 00:00:00 2001 From: Evert Timberg Date: Sat, 17 Oct 2020 15:12:34 -0400 Subject: [PATCH] Document and remove APIs that can be replaced by it (#7900) --- docs/docs/developers/api.md | 53 +++-------------------- docs/docs/getting-started/v3-migration.md | 9 ++++ src/core/core.controller.js | 20 --------- types/core/index.d.ts | 6 +-- 4 files changed, 16 insertions(+), 72 deletions(-) diff --git a/docs/docs/developers/api.md b/docs/docs/developers/api.md index 2331e11e2..772857cfd 100644 --- a/docs/docs/developers/api.md +++ b/docs/docs/developers/api.md @@ -91,65 +91,24 @@ myLineChart.toBase64Image(); // => returns png data url of the image on the canvas ``` -## .getElementAtEvent(e) +## .getElementsAtEventForMode(e, mode, options, useFinalPosition) -Calling `getElementAtEvent(event)` on your Chart instance passing an argument of an event, or jQuery event, will return the single element at the event position. If there are multiple items within range, only the first is returned. The value returned from this method is an array with a single parameter. An array is used to keep a consistent API between the `get*AtEvent` methods. +Calling `getElementsAtEventForMode(e, mode, options, useFinalPosition)` on your Chart instance passing an event and a mode will return the elements that are found. The `options` and `useFinalPosition` arguments are passed through to the handlers. -```javascript -myLineChart.getElementAtEvent(e); -// => returns the first element at the event point. -``` - -To get an item that was clicked on, `getElementAtEvent` can be used. +To get an item that was clicked on, `getElementsAtEventForMode` can be used. ```javascript function clickHandler(evt) { - var firstPoint = myChart.getElementAtEvent(evt)[0]; + const points = myChart.getElementAtEventForMode(evt, 'nearest', { intersect: true }, true); - if (firstPoint) { + if (points.length) { + const firstPoint = points[0]; var label = myChart.data.labels[firstPoint._index]; var value = myChart.data.datasets[firstPoint._datasetIndex].data[firstPoint._index]; } } ``` -## .getElementsAtEvent(e) - -Looks for the element under the event point, then returns all elements at the same data index. This is used internally for 'label' mode highlighting. - -Calling `getElementsAtEvent(event)` on your Chart instance passing an argument of an event, or jQuery event, will return the point elements that are at that the same position of that event. - -```javascript -canvas.onclick = function(evt) { - var activePoints = myLineChart.getElementsAtEvent(evt); - // => activePoints is an array of points on the canvas that are at the same position as the click event. -}; -``` - -This functionality may be useful for implementing DOM based tooltips, or triggering custom behaviour in your application. - -## .getElementsAtXAxis(e) - -Returns all elements at the data index the event point is located at. This is similar to `getElementsAtEvent(event)`, but the event point does not have to intersect one of the elements. - -Calling `getElementsAtXAxis(event)` on your Chart instance passing an argument of an event, or jQuery event, will return the point elements that are at that the same position of that event. - -```javascript -canvas.onclick = function(evt) { - var activePoints = myLineChart.getElementsAtXAxis(evt); - // => activePoints is an array of points on the canvas that are at the same X axis as the click event. -}; -``` - -## .getDatasetAtEvent(e) - -Looks for the element under the event point, then returns all elements from that dataset. This is used internally for 'dataset' mode highlighting. - -```javascript -myLineChart.getDatasetAtEvent(e); -// => returns an array of elements -``` - ## .getDatasetMeta(index) Looks for the dataset that matches the current index and returns that metadata. This returned data has all of the metadata that is used to construct the chart. diff --git a/docs/docs/getting-started/v3-migration.md b/docs/docs/getting-started/v3-migration.md index 77c17695a..fe24148de 100644 --- a/docs/docs/getting-started/v3-migration.md +++ b/docs/docs/getting-started/v3-migration.md @@ -350,6 +350,15 @@ The following properties and methods were removed: * `Title.margins` is now private * The tooltip item's `x` and `y` attributes were replaced by `element`. You can use `element.x` and `element.y` or `element.tooltipPosition()` instead. +#### Removal of Public APIs + +The following public APIs were removed. + +* `getElementAtEvent` is replaced with `chart.getElementsAtEventForMode(e, 'nearest', { intersect: true }, false)` +* `getElementsAtEvent` is replaced with `chart.getElementsAtEventForMode(e, 'index', { intersect: true }, false)` +* `getElementsAtXAxis` is replaced with `chart.getElementsAtEventForMode(e, 'index', { intersect: false }, false)` +* `getDatasetAtEvent` is replaced with `chart.getElementsAtEventForMode(e, 'dataset', { intersect: true }, false)` + #### Removal of private APIs The following private APIs were removed. diff --git a/src/core/core.controller.js b/src/core/core.controller.js index 2c2ba3285..95e8d92e7 100644 --- a/src/core/core.controller.js +++ b/src/core/core.controller.js @@ -819,22 +819,6 @@ class Chart { me._plugins.notify(me, 'afterDatasetDraw', [args]); } - /** - * Get the single element that was clicked on - * @return An object containing the dataset index and element index of the matching element. Also contains the rectangle that was draw - */ - getElementAtEvent(e) { - return Interaction.modes.nearest(this, e, {intersect: true}); - } - - getElementsAtEvent(e) { - return Interaction.modes.index(this, e, {intersect: true}); - } - - getElementsAtXAxis(e) { - return Interaction.modes.index(this, e, {intersect: false}); - } - getElementsAtEventForMode(e, mode, options, useFinalPosition) { const method = Interaction.modes[mode]; if (typeof method === 'function') { @@ -844,10 +828,6 @@ class Chart { return []; } - getDatasetAtEvent(e) { - return Interaction.modes.dataset(this, e, {intersect: true}); - } - getDatasetMeta(datasetIndex) { const me = this; const dataset = me.data.datasets[datasetIndex]; diff --git a/types/core/index.d.ts b/types/core/index.d.ts index 5936a5f11..730ae8d4a 100644 --- a/types/core/index.d.ts +++ b/types/core/index.d.ts @@ -286,11 +286,7 @@ export declare class Chart< render(): void; draw(): void; - getElementAtEvent(e: Event): InteractionItem[]; - getElementsAtEvent(e: Event): InteractionItem[]; - getElementsAtXAxis(e: Event): InteractionItem[]; - getElementsAtEventForMode(e: Event, mode: string, options: any, useFinalPosition: boolean): InteractionItem[]; - getDatasetAtEvent(e: Event): InteractionItem[]; + getElementsAtEventForMode(e: Event, mode: string, options: IInteractionOptions, useFinalPosition: boolean): InteractionItem[]; getSortedVisibleDatasetMetas(): IChartMeta[]; getDatasetMeta(datasetIndex: number): IChartMeta; -- 2.47.2