33
44from .context import SelectionContext , create_child_context
55from .EventHandler import DispatchEventType
6- from .utils import attr_event , queue_event , call_element_fn , is_iterable
6+ from .utils import attr_event , queue_event , update_animation , call_element_fn , is_iterable
77from .types import ElementArg , ElementFn
88
99S = TypeVar ('S' , bound = 'Selection' )
@@ -93,42 +93,41 @@ def eventQ(self: S, queue: Union[str, int, None] = 'default') -> S:
9393 context .queue = str (queue )
9494 return self .__class__ (context )
9595
96- def animate (self : S , animation_type : str ) -> S :
96+ def animate (self : S , animation_type : ElementArg [ str ] ) -> S :
9797 """
9898 Configures the type of animation which should be used for all attribute changes triggered by the selection.
9999
100- :param type : One of the following strings:
100+ :param animation_type : One of the following strings:
101101
102102 * "normal": The standard animation, applicable in most cases.
103103 * "scale": Animates the size of elements being added/removed.
104104 * "fade": Animates the opacity of elements being added/removed.
105105 * "scale-face": Animates both the size and opacity of elements being added/removed.
106- * "traverse": Changes the color of edges using a traversal animation (from source to target).
107- * "traverse-reverse": Changes the color of edges using a reversed traversal animation (from target to source).
106+ * "traverse": Changes the color of edges using a traversal animation.
108107
109- :type animation_type: str
108+ :type animation_type: :data:`~graphics.types.ElementArg` \\ [ str]
110109
111110 :return: A new instance of the current selection using the specified animation type.
112111 """
113112 context = self ._context .copy ()
114- context .animation [ 'type' ] = animation_type
113+ context .animation = update_animation ( context , animation_type , lambda d : { 'type' : d , 'data' : {}})
115114 return self .__class__ (context )
116115
117- def duration (self : S , seconds : Union [int , float ]) -> S :
116+ def duration (self : S , seconds : ElementArg [ Union [int , float ] ]) -> S :
118117 """
119- Configures the duration of all animations triggered by the selection. A duration of 0 will ensure that changes
120- occur immediately.
118+ Configures the duration of all animations triggered by the selection. A duration of ``0`` will ensure that changes
119+ occur immediately. The default duration is ``0.35``.
121120
122121 :param seconds: The animation duration, in seconds.
123- :type seconds: Union[int, float]
122+ :type seconds: :data:`~graphics.types.ElementArg` \\ [ Union[int, float] ]
124123
125124 :return: A new instance of the current selection using the specified animation duration.
126125 """
127126 context = self ._context .copy ()
128- context .animation [ 'duration' ] = seconds
127+ context .animation = update_animation ( context , seconds , lambda d : { 'duration' : d })
129128 return self .__class__ (context )
130129
131- def ease (self : S , ease : str ) -> S :
130+ def ease (self : S , ease : ElementArg [ str ] ) -> S :
132131 """
133132 Configures the ease function used in all animations triggered by the selection. This will affect the way attributes
134133 transition from one value to another. More information is available here: `<https://github.com/d3/d3-ease>`_.
@@ -146,38 +145,39 @@ def ease(self: S, ease: str) -> S:
146145 "back", "back-in", "back-out", "back-in-out",
147146 "bounce", "bounce-in", "bounce-out", "bounce-in-out".
148147
149- :type ease: str
148+ :type ease: :data:`~graphics.types.ElementArg` \\ [ str]
150149
151150 :return: A new instance of the current selection using the specified animation ease.
152151 """
153152 context = self ._context .copy ()
154- context .animation [ 'ease' ] = ease
153+ context .animation = update_animation ( context , ease , lambda d : { 'ease' : d })
155154 return self .__class__ (context )
156155
157- def highlight (self : S , seconds : Optional [Union [int , float ]] = None ) -> S :
156+ def highlight (self : S , seconds : Optional [ElementArg [ Union [int , float ] ]] = None ) -> S :
158157 """
159158 Returns a new selection through which all attribute changes are temporary. This is typically used to draw attention
160159 to a certain element without permanently changing its attributes.
161160
162161 :param seconds: The amount of time attributes should remain 'highlighted', in seconds, before
163- changing back to their original values. If not provided, an appropriate default will be used .
164- :type seconds: Optional[Union[int, float]]
162+ changing back to their original values. Defaults to ``0.5`` .
163+ :type seconds: Optional[:data:`~graphics.types.ElementArg` \\ [ Union[int, float] ]]
165164
166165 :return: A new instance of the current selection, where all attribute changes are temporary.
167166 """
168167 context = self ._context .copy ()
169168 context .highlight = True
170169 if seconds is not None :
171- context .animation [ 'linger' ] = seconds
170+ context .animation = update_animation ( context , seconds , lambda d : { 'linger' : d })
172171 return self .__class__ (context )
173172
174- def data (self : S , data : Union [Iterable [Any ], ElementFn [Any ]]) -> S :
173+ def data (self : S , data : Union [Iterable [Any ], ElementFn [Any ], None ]) -> S :
175174 """
176175 Binds the selection to a list of data values. This will decide the arguments provided whenever an attribute is
177176 configured using a function (see :data:`~graphics.types.ElementArg`).
178177
179178 :param data: An iterable container of values to use as the data of this selection, which should have the same length as the number
180179 of elements in the selection. Alternatively, a function (:data:`~graphics.types.ElementFn`) transforming the selection's previous data.
180+ Use ``null`` to unbind the selection from its data, in which case the selection will fall back on its parent's data.
181181 :type: data: Union[Iterable[Any], ElementFn[Any]]
182182
183183 :raise Exception: If the length of the data does not equal the number of elements in the selection.
0 commit comments