| /* |
| * Copyright 2014 Google Inc. All rights reserved. |
| * |
| * Use of this source code is governed by a BSD-style |
| * license that can be found in the LICENSE file or at |
| * https://developers.google.com/open-source/licenses/bsd |
| */ |
| /* |
| * TODO(prsd): Document library |
| */ |
| library charted.selection; |
| |
| import "dart:html" show Element, Event, EventListener, document; |
| import "dart:math" as math; |
| import "package:charted/core/utils.dart"; |
| import "package:charted/selection/transition.dart"; |
| |
| part "selection_scope.dart"; |
| part "src/selection_impl.dart"; |
| |
| /** |
| * Callback to access key value from a given data object. During the process |
| * of binding data to Elements, the key values are used to match Elements |
| * that have previously bound data |
| */ |
| typedef SelectionKeyFunction(datum); |
| |
| /** |
| * Callback for all DOM related operations - The first parameter [datum] is |
| * the piece of data associated with the node, [ei] is the index of the |
| * element in it's group and [c] is the context to which the data is |
| * associated to. |
| */ |
| typedef E SelectionCallback<E>(datum, int index, Element element); |
| |
| /** Callback used to access a value from a datum */ |
| typedef E SelectionValueAccessor<E>(datum, int index); |
| |
| /** Create a ChartedCallback that always returns [val] */ |
| SelectionCallback/*<T>*/ toCallback/*<T>*/(/*=T*/ val) => (datum, index, element) => val; |
| |
| /** Create a ChartedValueAccessor that always returns [val] */ |
| SelectionValueAccessor toValueAccessor(val) => (datum, index) => val; |
| |
| /** |
| * [Selection] is a collection of elements - this collection defines |
| * operators that can be applied on all elements of the collection. |
| * |
| * All operators accept parameters either as a constant value or a callback |
| * function (typically using the named parameters "val" and "fn"). These |
| * operators, when invoked with the callback function, the function is |
| * called once per element and is passed the "data" associated, the "index" |
| * and the element itself. |
| */ |
| abstract class Selection { |
| /** |
| * Collection of groups - A selection when created by calling [selectAll] |
| * on an existing [Selection], could contain more than one group. |
| */ |
| List<SelectionGroup> groups; |
| |
| /** |
| * Scope of this selection that manages the element, data associations for |
| * all elements in this selection (and the sub-selections) |
| */ |
| SelectionScope get scope; |
| |
| /** Indicates if this selection is empty */ |
| bool get isEmpty; |
| |
| /** Number of elements in this selection */ |
| int get length; |
| |
| /** First non-null element in this selection, if any. */ |
| Element get first; |
| |
| /** |
| * Creates and returns a new [Selection] containing the first element |
| * matching [selector] under each element in the current selection. |
| * |
| * If an element does not have a matching descendant, a placeholder is used |
| * in it's position - thus being able to match the indices of elements in |
| * the current and the created sub-selection. |
| * |
| * Any data bound to elements in this selection is inherited by the |
| * selected descendants. |
| */ |
| Selection select(String selector); |
| |
| /** |
| * Same as [select], but calls [fn] for each non-null element in the |
| * selection (with data associated to the element, index of the element in |
| * it's group and the element itself) to get the selected element that will |
| * be selected. |
| */ |
| Selection selectWithCallback(SelectionCallback<Element> fn); |
| |
| /** |
| * Creates and returns a new [Selection] containing all elements matching |
| * [selector] under each element in the current selection. |
| * |
| * The resulting [Selection] is nested with elements from current selection |
| * as parents and the selected descendants grouped by elements in the |
| * current selection. When no descendants match the selector, the |
| * collection of selected elements in a group is empty. |
| * |
| * Data bound to the elements is not automatically inherited by the |
| * selected descendants. |
| */ |
| Selection selectAll(String selector); |
| |
| /** |
| * Same as [selectAll], but calls [fn] for each non-null element in the |
| * selection (with data associated to the element, index of the element in |
| * it's group and the element itself) to get a collection of selected |
| * elements that will be part of the new selection. |
| */ |
| Selection selectAllWithCallback(SelectionCallback<Iterable<Element>> fn); |
| |
| /** |
| * Sets the attribute [name] on all elements when [val] is not null. |
| * Removes the attribute when [val] is null. |
| */ |
| void attr(String name, val); |
| |
| /** |
| * Same as [attr], but calls [fn] for each non-null element in the |
| * selection (with data associated to the element, index of the element in |
| * it's group and the element itself) to get the value of the attribute. |
| */ |
| void attrWithCallback(String name, SelectionCallback fn); |
| |
| /** |
| * Ensures presence of a class when [val] is true. Ensures that the class |
| * isn't present if [val] is false. |
| */ |
| void classed(String name, [bool val = true]); |
| |
| /** |
| * Same as [classed], but calls [fn] for each non-null element in the |
| * selection (with data associated to the element, index of the element in |
| * it's group and the element itself) to get the boolean value that |
| * indicates if the class must be added or removed. |
| */ |
| void classedWithCallback(String name, SelectionCallback<bool> fn); |
| |
| /** Sets CSS [property] to [val] on all elements in the selection. */ |
| void style(String property, val, {String priority}); |
| |
| /** |
| * Same as [style], but calls [fn] for each non-null element in the |
| * selection (with data associated to the element, index of the element in |
| * it's group and the element itself) to get the value of the property. |
| */ |
| void styleWithCallback(String property, SelectionCallback<String> fn, |
| {String priority}); |
| |
| /** |
| * Sets textContent of all elements in the selection to [val]. A side-effect |
| * of this call is that any children of these elements will not be part of |
| * the DOM anymore. |
| */ |
| void text(String val); |
| |
| /** |
| * Same as [text], but calls [fn] for each non-null element in |
| * the selection (with data associated to the element, index of the |
| * element in it's group and the element itself) to get the text content |
| */ |
| void textWithCallback(SelectionCallback<String> fn); |
| |
| /** |
| * Sets innerHtml of all elements in the selection to [val]. A side-effect |
| * of this call is that any children of these elements will not be part of |
| * the DOM anymore. |
| */ |
| void html(String val); |
| |
| /** |
| * Same as [html], but calls [fn] for each non-null element in |
| * the selection (with data associated to the element, index of the |
| * element in it's group and the element itself) to get the html content |
| */ |
| void htmlWithCallback(SelectionCallback<String> fn); |
| |
| /** |
| * Appends a new child element to each element in the selection. |
| * |
| * Returns a [Selection] containing the newly created elements. As with |
| * [select], any data bound to the elements in this selection is inherited |
| * by the new elements. |
| */ |
| Selection append(String tag); |
| |
| /** |
| * Same as [append], but calls [fn] for each non-null element in the |
| * selection (with data associated to the element, index of the element in |
| * it's group and the element itself) to get the element to be appended. |
| */ |
| Selection appendWithCallback(SelectionCallback<Element> fn); |
| |
| /** |
| * Inserts a child node to each element in the selection before the first |
| * element matching [before] or before the element returned by [beforeFn]. |
| * |
| * Returns a [Selection] containing the newly created elements. As with |
| * [select], any data bound to the elements in this selection is inherited |
| * by the new elements. |
| */ |
| Selection insert(String tag, |
| {String before, SelectionCallback<Element> beforeFn}); |
| |
| /** |
| * Same as [insert], but calls [fn] for each non-null element in the |
| * selection (with data associated to the element, index of the element in |
| * it's group and the element itself) to get the element to be inserted. |
| */ |
| Selection insertWithCallback(SelectionCallback<Element> fn, |
| {String before, SelectionCallback<Element> beforeFn}); |
| |
| /** Removes all selected elements from the DOM */ |
| void remove(); |
| |
| /** Calls [fn] on each element in this selection */ |
| void each(SelectionCallback fn); |
| |
| /** |
| * Adds or removes an event [listener] to each element in the selection for |
| * the specified [type] (Eg: "mouseclick", "mousedown") |
| * |
| * Any existing listener of the same type will be removed. To register |
| * multiple listener for the same event type, the [type] can be suffixed |
| * with a namespace. (Eg: "mouseclick.foo", "mousedown.bar") |
| * |
| * When [listener] is null, any existing listener of the same type and in |
| * the same namespace will be removed (Eg: Using "mouseclick.foo" as type |
| * will only remove listeners for "mouseclick.foo" and not "mouseclick.bar") |
| * |
| * To remove listeners of an event type in all namespaces, prefix the type |
| * with a "." (Eg: ".mouseclick" will remove "mouseclick.bar", |
| * "mouseclick .foo" and all other mouseclick event listeners) |
| * |
| * To summarize, [type] can be any DOM event type optionally in the format |
| * "event.namespace" where event is the DOM event type and namespace is |
| * used to distinguish between added listeners. |
| * |
| * When [listener] is called, it is passed the current value associated with |
| * the element. Please note that index passed to the listener contains a |
| * value as it was at the time of adding the listener. |
| */ |
| void on(String type, [SelectionCallback listener, bool capture]); |
| |
| /** |
| * Associates data with the selected elements. |
| * Computes the enter, update and exit selections. |
| */ |
| DataSelection data(Iterable vals, [SelectionKeyFunction keyFn]); |
| |
| /** |
| * Same as [data], but calls [fn] for each non-null element in the |
| * selection (with data associated to the element, index of the element in |
| * it's group and the element itself) to get the data to be set on the |
| * current element. |
| */ |
| DataSelection dataWithCallback(SelectionCallback<Iterable> fn, |
| [SelectionKeyFunction keyFn]); |
| |
| /** |
| * Associates data with all the elements - no join is performed. Unlike |
| * [data], this does not compute the enter, update and exit selections. |
| */ |
| void datum(Iterable vals); |
| |
| /** |
| * Same as [datum], but calls [fn] for each non-null element in the |
| * selection (with data associated to the element, index of the element in |
| * it's group and the element itself) to get the data to be set on the |
| * current element. |
| */ |
| void datumWithCallback(SelectionCallback<Iterable> fn); |
| |
| /** |
| * Starts a transition for the current selection. Transitions behave much |
| * like selections, except operators animate smoothly over time rather than |
| * applying instantaneously. |
| */ |
| Transition transition(); |
| } |
| |
| /* |
| * Group of elements in the selection. |
| * Each selection may contain more than one group of elements. |
| */ |
| abstract class SelectionGroup { |
| List<Element> elements; |
| Element parent; |
| } |
| |
| /** |
| * [EnterSelection] is a sub-selection that represents missing elements of a |
| * selection - an element is considered missing when there is data and no |
| * corresponding element in a selection. |
| */ |
| abstract class EnterSelection { |
| /** |
| * Indicate if this selection is empty |
| * See [Selection.isEmpty] for more information. |
| */ |
| bool get isEmpty; |
| |
| /** [DataSelection] that corresponds to this selection. */ |
| DataSelection get update; |
| |
| /** |
| * Appends an element to all elements in this selection and return |
| * [Selection] containing the newly added elements. |
| * |
| * See [Selection.append] for more information. |
| * The new nodes are merged into the [DataSelection] |
| */ |
| Selection append(String tag); |
| |
| /** |
| * Same as [append] but calls [fn] to get the element to be appended. |
| * See [Selection.appendWithCallback] for more information. |
| */ |
| Selection appendWithCallback(SelectionCallback<Element> fn); |
| |
| /** |
| * Insert a child node to each element in the selection and return |
| * [Selection] containing the newly added elements. |
| * |
| * See [Selection.insert] for more information. |
| * The new nodes are merged into the [UpdateSelection] |
| */ |
| Selection insert(String tag, |
| {String before, SelectionCallback<Element> beforeFn}); |
| |
| /** |
| * Same as [insert] but calls [fn] to get the element to be inserted. |
| * See [Selection.insertWithCallback] for more information. |
| */ |
| Selection insertWithCallback(SelectionCallback<Element> fn, |
| {String before, SelectionCallback<Element> beforeFn}); |
| |
| /** |
| * For each element in the current selection, select exactly one |
| * descendant and return [Selection] containing the selected elements. |
| * |
| * See [Selection.select] for more information. |
| */ |
| Selection select(String selector); |
| |
| /** |
| * Same as [select] but calls [fn] to get the element to be inserted. |
| * See [Selection.selectWithCallback] for more information. |
| */ |
| Selection selectWithCallback(SelectionCallback<Element> fn); |
| } |
| |
| /* |
| * [ExitSelection] is a sub-selection that represents elements that don't |
| * have data associated to them. |
| */ |
| abstract class ExitSelection extends Selection { |
| DataSelection get update; |
| } |
| |
| /* |
| * Selection that consists elements in the selection that aren't part of |
| * [EnterSelection] or the [ExitSelection] |
| * |
| * An [UpdateSelection] is only available after data() is attached and is |
| * currently exactly the same as [Selection] itself. |
| */ |
| abstract class DataSelection extends Selection { |
| /** |
| * A view of the current selection that contains a collection of data |
| * elements which weren't associated with an element in the DOM. |
| */ |
| EnterSelection get enter; |
| |
| /** |
| * A view of the current selection containing elements that don't have data |
| * associated with them. |
| */ |
| ExitSelection get exit; |
| } |