selection.hpp
TODO.
-
namespace D3
Functions
-
Selection Select(std::string selector)
Create a selection containing the first DOM element matching [selector] (convenience function to match D3 syntax - you can also just use the constructor)
-
Selection SelectAll(std::string selector)
Create a selection containing all DOM elements matching [selector] (convenience function to match D3 syntax - you can also just use the constructor)
-
template<typename DERIVED>
class SelectionOrTransition : public D3::D3_Base - #include <selection.hpp>
You probably never want to instantiate this class. Its sole purpose is to hold code for methods that are common to selections and transitions.
Developer note: It’s also handy if you want to allow a function to accept either a selection or transition. This is a good idea any time you are only using methods that are applicable to either, and the person calling the function may want to animate its results.
Setters
There are three main types of values you might want to change about a selection: attributes (use
SetAttr), styles (useSetStyle), and properties (useSetProperty). The distinction between these types is rooted in how they are represented in web languages (Javascript, CSS, and HTML) and would ideally be abstracted in this wrapper but can’t be.Additional traits you can set include text and html.
Advanced note: In D3.js, the same functions are used to set and get values (depending on whether an argument is passed). Because C++ needs to have clearly defined return types we need separate getters for each return type.
-
inline DERIVED &SetAttr(std::string name, std::string value)
Assigns [value] to the selection’s [name] attribute. Value can be any primitive type, a string, a function object, or a lambda. If a string is passed, it can be a normal string, or the name of a function in d3, emp (such as one created with JSWrap), or the local window. If it is a function name, that function will be run, receiving bound data, if any, as input
-
inline DERIVED &SetStyle(std::string name, std::string value, bool priority = false)
Sets the selection’s [name] style to [value]. This is the same idea as SetAttr, except for CSS styles. Value can be any primitive type, a string, a function object, or a lambda. If a string is passed, it can be a normal string, or the name of a function in d3, emp (such as one created with JSWrap), or the local window. If it is a function name, that function will be run, receiving bound data, if any, as input
There is a third optional argument, a boolean indicating whether you want to give this setting priority.
Getters
There are three main types of values you might want to access about a selection: attributes (use
GetAttr), styles (useGetStyle), and properties (useGetProperty). The distinction between these types is rooted in how they are represented in web languages (Javascript, CSS, and HTML) and would ideally be abstracted in this wrapper but can’t be.Additional traits you can set include text and html.
Advanced note: In D3.js, the same functions are used to set and get values (depending on whether an argument is passed). Because C++ needs to have clearly defined return types (and because different macros are required to return different types from Javascript), we need separate getters for each return type.
-
inline std::string GetAttrString(std::string name) const
Get the value of this object’s [name] attribute when it’s a string.
-
inline int GetAttrInt(std::string name) const
Get the value of this object’s [name] attribute when it’s an int.
-
inline double GetAttrDouble(std::string name) const
Get the value of this object’s [name] attribute when it’s a double.
-
inline std::string GetStyleString(std::string name) const
Get the value of this object’s [name] style when it’s a string.
-
inline int GetStyleInt(std::string name) const
Get the value of this object’s [name] style when it’s an int.
-
inline double GetStyleDouble(std::string name) const
Get the value of this object’s [name] style when it’s a double.
-
inline bool Empty() const
Returns true if there are no elements in this selection (or all elements are null)
-
inline int Size() const
Returns number of elements in this selection.
Public Functions
-
inline SelectionOrTransition()
-
inline SelectionOrTransition(int id)
-
inline SelectionOrTransition(const SelectionOrTransition<DERIVED> &s)
-
inline DERIVED Select(std::string selector) const
Create a new selection/transition containing the first element matching the [selector] string that are within this current selection/transition
-
inline DERIVED SelectAll(std::string selector) const
Create a new selection/transition containing all elements matching the [selector] string that are within this current selection/transition
-
inline DERIVED &Call(std::string function)
Call the given function once on the entire selection/transition. [function] can either be a C++ function or a string with the name of a Javascript function in the d3, emp, or current window namespace. To get around the problem of passing selections into C++, this function assumes that the function you are passing expects a single argument: an int, representing the id of the selection to be operated on (which you can then convert to a selection object with
D3::Selection(i)).
-
inline DERIVED Filter(std::string selector) const
Returns a new selection/transition, representing the current selection/transition filtered by [selector]. [selector] can be a C++ function that returns a bool, a string representing a function in either the d3, emp, or window namespaces that returns a bool, or a string containing a selector to filter by.
For more information see the D3 documentation
-
inline DERIVED &Each(std::string function)
Call the given function on each element of the selection/transition. [function] can either be a C++ function or a string with the name of a Javascript function in the d3, emp, or current window namespace.
-
inline void Remove()
Remove the elements in this selection/transition from the document For transitions, this happens at the end of the transition.
-
inline DERIVED &SetAttr(std::string name, std::string value)
-
class Transition : public D3::SelectionOrTransition<Transition>
- #include <selection.hpp>
Transitions are similar to selections, but when you make a change to them (attr or style), it will be animated. For additional discussion of transitions in d3, see this article.
Constructors
Usually transitions are constructed from selections by calling the selection.MakeTransition() method. In rare cases you may want to construct a new transition, though.
-
inline Transition()
Default constructor - construct empty transition.
-
inline Transition(int id)
Advanced: Construct new transition pointing to the [id]th element in js.objects.
-
inline Transition NewTransition(std::string name = "") const
Create a transition from the current transition. If a [name] is specified the transition will be given that name
Note: In D3.js this method is just called transition(), but in C++ that would cause a collision with the constructor
Setters
There are three main types of values you might want to change about a selection: attributes (use
SetAttr), styles (useSetStyle), and properties (useSetProperty). The distinction between these types is rooted in how they are represented in web languages (Javascript, CSS, and HTML) and would ideally be abstracted in this wrapper but can’t be.Additional traits you can set include text and html.
Advanced note: In D3.js, the same functions are used to set and get values (depending on whether an argument is passed). Because C++ needs to have clearly defined return types we need separate getters for each return type.
-
inline Transition &On(std::string type, std::string listener = "null", bool capture = false)
-
inline Transition &SetDuration(double time)
-
inline Transition &SetProperty(std::string name, std::string value)
Sets special properties of DOM elements (e.g. “checked” for checkboxes) Value can be a number, function, string, or string naming a Javascript function See the d3 documentation for more information.
-
inline Transition &SetHtml(std::string value)
Sets this selection’s inner html to the specified string, or the string returned by running the specified function on the element’s bound data
-
inline Transition &SetClassed(std::string classname, bool value)
Change whether or not element in this selection have the [classname] class. Example: Add the data-point class with selection.SetClassed(“data-point”, true);
Getters
There are three main types of values you might want to access about a selection: attributes (use
GetAttr), styles (useGetStyle), and properties (useGetProperty). The distinction between these types is rooted in how they are represented in web languages (Javascript, CSS, and HTML) and would ideally be abstracted in this wrapper but can’t be.Additional traits you can set include text and html.
Advanced note: In D3.js, the same functions are used to set and get values (depending on whether an argument is passed). Because C++ needs to have clearly defined return types (and because different macros are required to return different types from Javascript), we need separate getters for each return type.
-
inline std::string GetPropertyString(std::string name) const
Get the value of this object’s [name] property when its a string.
-
inline Transition()
-
class Selection : public D3::SelectionOrTransition<Selection>
- #include <selection.hpp>
Selections are the primary way that d3 allows you to operate on DOM elements (i.e. objects on your webpage). A selection is effectively an array of DOM elements that you can act on at the same time and bind a collection of data to.
For a deep dive into how selections work in d3, see this article.
Constructors
You may prefer to use the Select or SelectAll functions for improved code clarity/consistency with d3.js
-
inline Selection()
Default constructor - constructs empty selection.
-
inline Selection(int id)
Create Selection object with a specific id.
Advanced note: This is useful when creating a Selection object to point to a selection
-
inline Selection(std::string selector, bool all = false)
This is the Selection constructor you usually want to use. It takes a string saying what to select and a bool saying whether to select all elements matching that string [true] or just the first [false]
-
inline ~Selection()
Destructor.
Binding Data
This group of functions allows you to bind data to the current selection and deal with new data you have just bound (the enter selection) and data that was previously bound to to the selection but is not present in the set of data that was most recently bound (the exit selection)
The process of binding data to a selection is called a “join” in d3-speak. For more in-depth explanation, see this article.
-
inline Selection Data(Dataset &values, std::string key = "")
Bind data to selection. Accepts any contiguous container (such as an array or vector) or a D3::Dataset object (which stores the data Javascript). Optionally also accepts a key function to run on each element to determine which elements are equivalent (if no key is provided, elements are expected to be in the same order each time you bind data to this selection). This function can either be a string with the name of a function in Javascript, or it can be a C++ function pointer, std::function object, or lambda.
-
inline Selection EnterAppend(std::string type)
This function appends the specified type of nodes to this selection’s enter selection, which merges the enter selection with the update selection.
Selection must have an enter selection (i.e. have just had data bound to it).
-
inline Selection EnterInsert(std::string name, std::string before = NULL)
Insert elements of type [name] into current enter selection
For more information, see the D3 documention on insert
-
inline Selection Enter()
Sometimes you want to perform multiple operations on the enter selection. If so, you can use the Enter() method to get the enter selection, rather than using one of the convenience functions like EnterAppend().
Returns a selection object pointing at this selection’s enter selection.
-
inline void ExitRemove()
Selection must have an exit selection (i.e. have just had data bound to it).
Pretty much the only thing you ever want to do with the exit() selection is remove all of the nodes in it. This function does just that.
-
inline Selection Exit()
Usually the only thing you want to do with the exit selection is remove its contents, in which case you should use the ExitRemove method. However, advanced users may want to operate on the exit selection, which is why this method is provided.
Returns a selection object pointing at this selection’s exit selection.
Setters
There are three main types of values you might want to change about a selection: attributes (use
SetAttr), styles (useSetStyle), and properties (useSetProperty). The distinction between these types is rooted in how they are represented in web languages (Javascript, CSS, and HTML) and would ideally be abstracted in this wrapper but can’t be.Additional traits you can set include text and html.
Advanced note: In D3.js, the same functions are used to set and get values (depending on whether an argument is passed). Because C++ needs to have clearly defined return types we need separate getters for each return type.
-
inline Selection &SetProperty(std::string name, std::string value)
Sets special properties of DOM elements (e.g. “checked” for checkboxes) Value can be a number, function, string, or string naming a Javascript function See the d3 documentation for more information.
Getters
There are three main types of values you might want to access about a selection: attributes (use
GetAttr), styles (useGetStyle), and properties (useGetProperty). The distinction between these types is rooted in how they are represented in web languages (Javascript, CSS, and HTML) and would ideally be abstracted in this wrapper but can’t be.Additional traits you can set include text and html.
Advanced note: In D3.js, the same functions are used to set and get values (depending on whether an argument is passed). Because C++ needs to have clearly defined return types (and because different macros are required to return different types from Javascript), we need separate getters for each return type.
-
inline std::string GetPropertyString(std::string name) const
Get the value of this object’s [name] property when its a string.
Public Functions
-
inline Selection Append(std::string name)
Append DOM element(s) of the type specified by [name] to this selection.
-
inline Selection Insert(std::string name, std::string before = NULL)
Insert DOM element of type “name” into the current selection before the element selected by the element specified by the [before] string
For more information, see the D3 documention on insert
-
inline Transition MakeTransition(std::string name = "")
Create a transition from the current selection. If a [name] is specified the transition will be given that name
-
inline Transition MakeTransition(Transition &t)
-
inline Selection &Interrupt(std::string name = "")
Interrupt the transition with the name [name] on the current selection.
-
inline Selection &Move(int x, int y)
Move the elements in this selection by [x] in the x direction and [y] in the y direction. Note for advanced users: this method is just a shortcut for setting the “transform” attribute to “translate(x, y)”, because doing that is a pain in C++ (even more so than in Javascript)
-
inline Selection &Rotate(int degrees)
Rotate the elements in this selection by [degrees]. Note for advanced users: this method is just a shortcut for setting the “transform” attribute to “rotate(degrees)”, because doing that is a pain in C++ (even more so than in Javascript)
-
inline Selection &Order()
Change the order of elements in the document to match their order in this selection.
-
inline Selection &On(std::string type, std::string listener = "null", bool capture = false)
Listen for an event of type [type] and call [listener] when it happens [listener] can be a string containing the name of a Javascript function, or a C++ function
The third paramter for the listener function is the id of a selection containing the relevant DOM object.
To remove an event listener, call On with that type and “null” as the listener (default)
Advanced note: the optional capture flag invokes Javascript’s useCapture option
-
inline Selection &Sort(std::string comparator = "ascending")
Sort the selection by the given comparator function. The function can be a C++ function or a stirng indicating a function in the d3 namespace, the emp namespace (as results from JSWrapping C++ functions), or the window namespace. These three options are checked sequentially in that order, so a C++ function with the same name as d3 built-in will not override the built-in. Similarly, a function declared directly in the window will be overriden by a JSWrapped function with the same name.
-
inline Selection()
-
Selection Select(std::string selector)