Package: pythonista-scripter
SCRIPTER- Pythonista UI and Scene animationsQuick startIn order to start using the animation effects, just import scripter and call
the effects as functions:from scripter import *

hide(my_button)Effects expect an active UI view as the first argument. Effects run for a
default duration of 0.5 seconds, unless otherwise specified with adurationargument.If you want to create a more complex animation from the effects provided,
combine them in a script:@script
def my_effect(view):
  move(view, 50, 200)
  pulse(view, 'red')
  yield
  hide(view, duration=2.0)Scripts control the order of execution withyieldstatements. Here movement
and a red pulsing highlight happen at the same time. After both actions are
completed, view fades away slowly, in 2 seconds.As the view provided as the first argument can of course beselforsender,
scripts fit naturally as customui.Viewmethods oractionfunctions.As small delays are often needed for natural-feeling animations, you can append
a number after ayieldstatement, to suspend the execution of the script for
that duration, oryield 'wait'for the default duration.Another key for good animations is the use of easing functions that modify how
the value progresses from starting value to the target value. Easing functions
support creating different kinds of accelerating, bouncing and springy effects.
Easing functions can be added as an argument to scripts:slide_value(view, 'x', 200, ease_func=bounce_out)See thisreferenceto pick the right function, or runscripter-demo.pyto try out the available
effects and to find the optimal duration and easing function combo for your purposes.You can change the default speed of all animations by settingScripter.default_duration.Scripter can also be used to animate different kinds of Pythonistascenemodule Nodes, including the Scene itself. Scripter provides roughly the same
functionality asscene.Action, but is maybe a bit more concise, and is
available as an option if you want to use same syntax in both UI and Scene
projects.See the API documentation for individual effects and how to roll your own withset_value,slide_valueandtimer.There are also convenience functions, not separately documented, corresponding
to all animatable attributes of ui views. For example, you can animate theui.View.background_colorattribute with:background_color(view, 'black')APIClass: ScripterMethodsPropertiesClass: ScrollingBannerLabelMethodsPropertiesClass: VectorMethodsPropertiesFunctionsScript managementAnimation primitivesAnimation effectsEasing functionsClass: ScripterClass that contains theupdatemethod used to run the scripts and to control their execution.Runs at default 60 fps, or not at all when there are no scripts to run.Inherits from ui.View; constructor takes all the same arguments as ui.View.Methodsupdate(self)Main Scripter animation loop handler, called by the Puthonista UI loop and never by your
code directly.This method:Activates all newly called scripts and suspends their parents.Calls all active scripts, which will run to their nextyieldor until completion.As a convenience feature, if ayieldreturns'wait'or a specific duration,
kicks off a childtimerscript to wait for that period of time.Cleans out completed scripts.Resumes parent scripts whose children have all completed.Setsupdate_intervalto 0 if all scripts have completed.pause_play_all(self)Pause or play all animations.cancel(self, script)Cancels any ongoing animations and
sub-scripts for the given script.cancel_all(self)Initializes all internal structures.
Used at start and to cancel all running scripts.Propertiesdefault_update_interval (get)The running rate for the update method. Frames per second is here considered to be just an
alternative way of setting the update interval, and this property is linked todefault_fps- change one and the other will change as well.default_fps (get)The running rate for the update method. Frames per second is here considered to be just an
alternative way of setting the update interval, and this property is linked todefault_update_interval- change one and the other will change as well.Class: ScrollingBannerLabelUI component that scrolls the given text indefinitely, in either direction. Will only scroll if the text is too long to fit into this component.Methods__init__(self, **kwargs)In addition to normalui.Viewarguments, you can include:text- To be scrolled as a marquee.Label formatting argumentsfontandtext_color.initial_delay- How long we wait before we start scrolling, to enable reading the beginning of the text. Default is 2 seconds.scrolling_speed- How fast the text moves, in points per second. Default is 100 pts/s.to_right- Set to True if you would like the text to scroll from the left. Default is False.stop(self)Stops the scrolling and places the text at start.restart(self)Restarts the scrolling, including the initial delay, if any.Propertiestext (get)You can change the text displayed at
any point after initialization by setting
this property.FunctionsSCRIPT MANAGEMENTscript(func)Can be used with Scene Nodes.Decorator for the animation scripts. Scripts can be functions, methods or generators.First argument of decorated functions must always be the view to be animated.Calling a script starts the Scripterupdateloop, if not already running.New scripts suspend the execution of the parent script until all the parallel scripts have
completed, after which theupdatemethod will resume the execution of the parent script.find_scripter_instance(view)Can be used with Scene Nodes.Scripts need a "controller" ui.View that runs the update method for them. This function finds
or creates the controller for a view as follows:Check if the view itself is a ScripterCheck if any of the subviews is a ScripterRepeat 1 and 2 up the view hierarchy of superviewsIf not found, create an instance of Scripter as a hidden subview of the root viewIn case of scene Nodes, search starts fromnode.scene.view.If you want cancel or pause scripts, and have not explicitly created a Scripter instance to
run them, you need to use this method first to find the right one.ANIMATION PRIMITIVESset_value(view, attribute, value, func=None)@scriptGenerator that sets theattributeto avalueonce, or several times if the value itself is a
generator or an iterator.Optional keyword parameters:func- called with the value, returns the actual value to be setslide_value(view, attribute, end_value, target=None, start_value=None, duration=None, delta_func=None, ease_func=None, current_func=None, map_func=None, side_func=None)@scriptGenerator that "slides" thevalueof anattributeto anend_valuein a given duration.Optional keyword parameters:start_value- set if you want some other value than the current value of the attribute as the animation start value.duration- time it takes to change to the target value. Default is 0.5 seconds.delta_func- use to transform the range from start_value to end_value to something else.ease_func- provide to change delta-t value to something else. Mostly used for easing; you can provide an easing function name as a string instead of an actual function. See supported easing functionshere.current_func- Given the start value, delta value and progress fraction (from 0 to 1), returns the current value. Intended to be used to manage more exotic values like colors.map_func- Used to translate the current value to something else, e.g. an angle to a Transform.rotation.side_func- Called without arguments each time after the main value has been set. Useful for side effects.slide_tuple(view, *args, **kwargs)@scriptSlide a tuple value of arbitrary length. Supports same arguments asslide_value.slide_color(view, attribute, end_value, **kwargs)@scriptSlide a color value. Supports the same
arguments asslide_value.timer(view, duration=None, action=None)@scriptActs as a wait timer for the given duration in seconds.viewis only used to find the
controlling Scripter instance. Optional action function is called every cycle.ANIMATION EFFECTScenter(view, move_center_to, **kwargs)@scriptMove view center (anchor for Scene Nodes).center_to(view, move_center_to, **kwargs)@scriptAlias forcenter.center_by(view, dx, dy, **kwargs)@scriptAdjust view center/anchor position by dx, dy.expand(view, **kwargs)@scriptNot applicable for Scene Nodes.Expands the view to fill all of its superview.fly_out(view, direction, **kwargs)@scriptMoves the view out of the screen in the given direction. Direction is one of the
following strings: 'up', 'down', 'left', 'right'.hide(view, **kwargs)@scriptFade the view away.move(view, x, y, **kwargs)@scriptMove to x, y.
For UI views, this positions the top-left corner.
For Scene Nodes, this moves the Nodeposition.move_to(view, x, y, **kwargs)@scriptAlias formove.move_by(view, dx, dy, **kwargs)@scriptAdjust position by dx, dy.pulse(view, color='#67cf70', **kwargs)@scriptPulses the background of the view to the given color and back to the original color.
Default color is a shade of green.reveal_text(view, **kwargs)@scriptReveals text one letter at a time in the given duration. View must have atextattribute.roll_to(view, to_center, end_right_side_up=True, **kwargs)@scriptRoll the view to a target position given by theto_centertuple. Ifend_right_side_upis true, view starting angle is adjusted so that the view will end up with 0 rotation at the end, otherwise the view will start as-is, and end in an angle determined by the roll.
View should be round for the rolling effect to make sense. Imaginary rolling surface is below the view - or to the left if rolling directly downwards.rotate(view, degrees, shortest=False, **kwargs)@scriptRotate view to an absolute angle. Set start_value if not starting from 0. Positive number rotates clockwise. For UI views, does not mix with other transformations.Optional arguments:shortest- If set to True (default), will turn in the "right" direction. For UI views, start_value must be set to a sensible value for this to work.rotate_to(view, degrees, **kwargs)Alias forrotate.rotate_by(view, degrees, **kwargs)@scriptRotate view by given degrees.scale(view, factor, **kwargs)@scriptScale view to a given factor in both x and y dimensions. For UI views, you need to explicitly setstart_valueif not starting from 1.scale_to(view, factor, **kwargs)Alias forscale.scale_by(view, factor, **kwargs)@scriptScale view relative to current scale factor.show(view, **kwargs)@scriptSlide alpha from 0 to 1.wobble(view)@scriptLittle wobble of a view, intended to attract attention.wait_for_tap(view)@scriptOverlays the given view with a temporary transparent view, and
yields until the view is tapped.EASING FUNCTIONSmirror(ease_func, t)Runs the given easing function to the end in half the duration, then backwards in the second half. For example, if the function provided islinear, this function creates a "triangle" from 0 to 1, then back to 0; if the function isease_in, the result is more of a "spike".oscillate(t)Basic sine curve that runs from 0 through 1, 0 and -1, and back to 0.