Classes | |
class | Animation |
Animation is a helper class for setting up UI animations. More... | |
class | AnimationHelper |
Provides simple static functions wrapping common transformations applied to Qt Widgets. More... | |
class | Scene |
This is an internal object used for tracking Scene information. More... | |
class | ContentAlignmentAnimatingWidget |
Helper widget that animates the alignment of a given child widget. More... | |
class | SceneManager |
Moving between different UI states can be very tedious and end up producing incredibly complex and often indecipherable code. More... | |
class | SceneManager::SceneBuilder |
The SceneBuilder class is a helper for the buildup/teardown process of a Scene. More... | |
class Animation |
Animation is a helper class for setting up UI animations.
Animations can be created as standalone objects (for simpler single-item animations), and can also be used within the Scene Manager for transitions between scenes.
By default, Animation upon being started will interpolate between 0.0 and 1.0.
Accessibility General motion can be enabled/disabled via the binaryninja.ui.motion setting. Whenever motion is disabled, instead of interpolating between values, animations will only fire the start and end value.
Your options regarding this are:
It is worth keeping in mind that this is an accessibility feature, and overriding reduced motion should only be done where it is explicitly appropriate. (e.g. Loading spinners and other simple critical animations.)
Signals | |
void | ended () |
Signal fired after the animation ends and all callbacks have fired. More... | |
Public Member Functions | |
Animation * | named (std::string name) |
Set the name of the animation. More... | |
Animation * | withDuration (int msecs) |
Set the duration of the animation; that is, "how long should it take to interpolate between 0.0 and 1.0?". More... | |
Animation * | withEasingCurve (QEasingCurve curve) |
Allows setting the QEasingCurve for this animation. More... | |
Animation * | thenOnStart (std::function< void(QAbstractAnimation::Direction)> startCallback) |
Callback to fire at the start of the animation. More... | |
Animation * | thenOnValueChanged (std::function< void(double)> callback) |
Callback to fire when this animation's progress is updated. More... | |
Animation * | thenUpdatePropertyOnValueChanged (QObject *obj, QString property) |
By passing this an object and associated property name, a Q_PROPERTY of a given object can be updated with the animation's state. More... | |
Animation * | thenOnEnd (std::function< void(QAbstractAnimation::Direction)> endCallback) |
Callback to fire at the end of the animation. More... | |
Animation * | overridingReducedAnimationsForAVeryGoodReason () |
ONLY use this if you are doing something like a loading spinner. AVOID IT. More... | |
void | start () |
Fire the animation. More... | |
Static Public Member Functions | |
static Animation * | create (QObject *owner=nullptr) |
Create a new animation object. More... | |
static Animation * | createCopy (Animation *animation) |
Creates a copy of the target animation. More... | |
static bool | reducedMotionEnabled () |
Whether reduced motion is enabled for the BinaryNinja Application. More... | |
Protected Member Functions | |
bool | event (QEvent *event) override |
void | updateCurrentValue (const QVariant &value) override |
void | updateState (QAbstractAnimation::State newState, QAbstractAnimation::State oldState) override |
|
static |
Create a new animation object.
A note on lifetimes: if a given Animation
is passed to a SceneManager
, the SceneManager will take ownership of the Animation
, and it will not be deleted until the SceneManager
itself is.
owner |
Animation
object
|
inlinestatic |
Whether reduced motion is enabled for the BinaryNinja Application.
This will return true if the `binaryninja.ui.motion` setting is enabled.
The `binaryninja.ui.motion` setting will be enabled automatically if the Operating System's reduce motion setting is turned on.
|
inline |
Set the name of the animation.
This is only useful for debugging purposes, however if you are working with several animations in a SceneManager, it's highly recommended you give it something, as error messages regarding this animation will report it.
name | Name of the animation. |
Animation
object
|
inline |
Set the duration of the animation; that is, "how long should it take to interpolate between 0.0 and 1.0?".
msecs | Duration of the animation in msecs; |
Animation
object
|
inline |
Allows setting the QEasingCurve for this animation.
It's recommended you read the official Qt documentation here: https://doc.qt.io/qt-6/qeasingcurve.html
curve | Easing curve |
Animation
object Animation * Animation::thenOnStart | ( | std::function< void(QAbstractAnimation::Direction)> | startCallback | ) |
Callback to fire at the start of the animation.
It will be passed an AnimationDirection
value, which is relevant when using animations for linear scene transitions.
startCallback | Function to be called |
Animation
object Animation * Animation::thenOnValueChanged | ( | std::function< void(double)> | callback | ) |
Callback to fire when this animation's progress is updated.
This is where the bulk of your animation logic will go.
Will be passed a double
value between 0.0 and 1.0.
callback | Callback to be fired |
Animation
object Animation * Animation::thenUpdatePropertyOnValueChanged | ( | QObject * | obj, |
QString | property | ||
) |
By passing this an object and associated property name, a Q_PROPERTY of a given object can be updated with the animation's state.
It will be passed a double
, containing a value between 0.0 and 1.0.
(This is functionally equivalent to thenOnValueChanged, with the primary difference being where you decide to implement your animation logic.)
This can be particularly useful if you have an opacity property you want to fade in or out, or you prefer to implement some animation related logic in a QProperty setter. It can also be useful for debugging via the UI debugger.
An example usage of this involves manipulating the properties of ContentAlignmentAnimatingWidget
to move a widget for your animation.
obj | QObject target |
property | Q_PROPERTY target name |
Animation
object Animation * Animation::thenOnEnd | ( | std::function< void(QAbstractAnimation::Direction)> | endCallback | ) |
Callback to fire at the end of the animation.
It will be passed an AnimationDirection
value, which is relevant when using animations for linear scene transitions.
endCallback | Function to be called |
Animation
object
|
inline |
ONLY use this if you are doing something like a loading spinner. AVOID IT.
void Animation::start | ( | ) |
Fire the animation.
These events will occur, in order:
|
signal |
Signal fired after the animation ends and all callbacks have fired.
|
overrideprotected |
|
overrideprotected |
|
overrideprotected |
class AnimationHelper |
Provides simple static functions wrapping common transformations applied to Qt Widgets.
Static Public Member Functions | |
static void | SetLabelOpacity (QLabel *label, double opacity) |
Set the opacity of a given QLabel. More... | |
|
static |
Set the opacity of a given QLabel.
Specifically, this will set the text opacity.
label | Target label. |
opacity | Target opacity. Value between 0.0 and 1.0. |
class Scene |
This is an internal object used for tracking Scene information.
Create an instance of a scene via AnimationStateMachine->createScene();
Signals | |
void | setupScene (std::string transitioningFrom) |
void | teardownScene (std::string transitionedTo) |
|
signal |
|
signal |
class ContentAlignmentAnimatingWidget |
Helper widget that animates the alignment of a given child widget.
Public Slots | |
void | updateWithTransitionState (double transitionState) |
Public Member Functions | |
ContentAlignmentAnimatingWidget (QWidget *parent=nullptr) | |
Qt::Alignment | stopOneAlignment () const |
void | setStopOneAlignment (Qt::Alignment align) |
Qt::Alignment | stopTwoAlignment () const |
void | setStopTwoAlignment (Qt::Alignment align) |
QMargins | padding () const |
void | setPadding (QMargins padding) |
QWidget * | widget () const |
void | setWidget (QWidget *widget) |
Protected Member Functions | |
void | resizeEvent (QResizeEvent *event) override |
Properties | |
Qt::Alignment | stopOneAlignment |
Qt::Alignment | stopTwoAlignment |
QMargins | padding |
QWidget * | widget |
ContentAlignmentAnimatingWidget::ContentAlignmentAnimatingWidget | ( | QWidget * | parent = nullptr | ) |
|
inline |
|
inline |
|
inline |
|
inline |
|
inline |
|
inline |
|
inline |
void ContentAlignmentAnimatingWidget::setWidget | ( | QWidget * | widget | ) |
|
inlineoverrideprotected |
|
slot |
|
readwrite |
|
readwrite |
|
readwrite |
|
readwrite |
class SceneManager |
Moving between different UI states can be very tedious and end up producing incredibly complex and often indecipherable code.
Adding animations into the mix does not help.
The SceneManager class, along with the rest of the utilities provided for Animation, aim to help with writing more maintainable and parseable code for UI state transitions.
This documentation block goes over the general concepts of this class, while the implementation details are documented on the functions themselves.
A general note on multi-stage animations in Binary Ninja:
These should ideally not be used in locations in the application where interactions should feel instant. Login screens, the new tab page, update UI, etc. are valid applications for this; however, animations within your analysis plugin providing UI may feel clunky and out of place.
This manager can, however, be used for managing multiple scenes regardless, with the Animations' simply lacking a valueUpdated callback and duration set to 0ms, relying on setup and teardown callbacks instead.
Linear connections are useful for setting up multi-stage UIs. They can "pathfind" between connected scenes, move in both directions, and be swapped via transitionToScene
.
connectScenesLinear will create a bidirectional link between two Scenes, firing the animation in reverse if a backwards transition is requested. See the Animation
class documentation for more info on reversed animations.
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ ├──────────►│ ├──────────►│ │ │ Scene 1 │ Animat. 1 │ Scene 2 │ Animat. 2 │ Scene 3 │ │ │◄──────────┤ │◄──────────┤ │ └─────────────┘ └─────────────┘ └─────────────┘
In the above described chain, if one were currently in Scene 1, transitionToScene
("scene3") could be called, which would walk the chain of required scenes to transition to Scene 3. In this case, Animation 1 would be fired, and then immediately after it finished, Animation 2 would be fired, ending in Scene 3.
One could also call mySceneManager->transitionToScene
(mySceneManager->nextScene()) , which would transition from Scene 1 to Scene 2.
These aren't recommended, as they can cause minor confusion related to linear pathfinding
See SceneManager::transitionToScene
.
Linear connections can loop back around. This can be useful for setting up simple on-off transitions, carousels, etc. However, in almost all cases, it can be more clear to utilize direct connections for loopbacks, to more explicitly define the behavior required, and to avoid confusion regarding the linear pathfinding.
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ──────────►│ ├──────────►│ ├──────────►│ ├─────────── Animat. 3 │ Scene 1 │ Animat. 1 │ Scene 2 │ Animat. 2 │ Scene 3 │ Animat. 3 ───────────┤ │◄──────────┤ │◄──────────┤ │◄────────── └─────────────┘ └─────────────┘ └─────────────┘
Direct connections are the alternative to linear ones. They allow building out much more complex graphs, more explicit handling of loopbacks, etc, at the cost of not being able to "pathfind" to other animations.
Instead, a scene with only direct connections MUST transition to one it is directly connected to.
Direct connections will also override Linear ones. When doing pathfinding, the Scene Manager will look for any direct links between the current and target scenes before checking for ones Linearly connected.
For more information on pathfinding, see SceneManager::transitionToScene
Scenes also have setup and teardown callbacks. See also SceneBuilder
.
These differ from Animation start and end callbacks in that, a Scene can have multiple animations between different scenes, but may have some shared code that always needs to be ran when transitioning to/away from this scene.
Overview The following is an exhaustive list of what will happen when transitioning between two example scenes, "scene1"
and "scene2"
"scene2"
's onSetup
callback will be fired."scene1"
's onTeardown
callbacks are fired.To transition back, we call, transitionToScene
("scene1").
"scene1"
's onSetup
callback is fired.AnimationDirection::Backwards
AnimationDirection::Backwards
"scene2"
's onTeardown
callbacks are fired. Public Member Functions | |
~SceneManager () | |
SceneManager (QObject *owner=nullptr) | |
Create a new Scene Manager. More... | |
SceneBuilder | createScene (const std::string &name) |
Create a scene with a given name. More... | |
void | setupInitialScene (const std::string &initial) |
Set the initial scene and perform the required setup to load it. More... | |
void | connectScenes (const std::string &firstScene, const std::string &secondScene, Animation *animation) |
Create a connection between firstScene and secondScene with a given animation. More... | |
void | connectScenesLinear (const std::string &firstScene, const std::string &secondScene, Animation *animation) |
Creates a linear connection between two scenes with a given animation. More... | |
const std::string | currentScene () |
Get the currently active scene. More... | |
void | transitionToScene (const std::string targetScene) |
Transition to a given scene. More... | |
std::string | prevScene () |
Returns the name of the current scene's "Previous Scene", if this scene is part of a linear chain. More... | |
std::string | nextScene () |
Returns the name of the current scene's "Next Scene", if this scene is part of a linear chain. More... | |
bool | transitionRunning () const |
Check whether a transition is currently running. More... | |
SceneManager::~SceneManager | ( | ) |
SceneManager::SceneManager | ( | QObject * | owner = nullptr | ) |
Create a new Scene Manager.
owner | Parent QObject. When the parent is deallocated, this SceneManager will be as well. |
SceneBuilder SceneManager::createScene | ( | const std::string & | name | ) |
Create a scene with a given name.
This name will be used as the scene's "identifier", and is what should be passed to all functions of this class that request a scene name.
name | Name of the Scene |
void SceneManager::setupInitialScene | ( | const std::string & | initial | ) |
Set the initial scene and perform the required setup to load it.
onSetup
will be called for the target scene, with the argument ""
initial | target scene |
void SceneManager::connectScenes | ( | const std::string & | firstScene, |
const std::string & | secondScene, | ||
Animation * | animation | ||
) |
Create a connection between firstScene
and secondScene
with a given animation.
This will create a direct link, instead of a linear one. If there's a linear path between these two scenes, this connection will overrule that and use the provided animation to transition directly instead.
This can also be used for transitions that do not need to be bidirectional.
firstScene | Initial scene |
secondScene | Target scene |
animation | Animation to be used when transitioning from firstScene to secondScene. |
void SceneManager::connectScenesLinear | ( | const std::string & | firstScene, |
const std::string & | secondScene, | ||
Animation * | animation | ||
) |
Creates a linear connection between two scenes with a given animation.
In terms of direction, the two scenes will be treated (and connected) as follows:
◄─── Previous ┌────────────────────┐ ┌───────────────▼───┐ ┌──┴────────────────┐ │ │ │ │ │ "firstScene" │ "animation" │ "secondScene" │ │ │ │ │ └───────────────┬───┘ └──▲────────────────┘ └────────────────────┘ Next ──►
By connecting a third scene with "secondScene" here as the first scene, you can create a chain.
firstScene | First scene to connect |
secondScene | Second scene to connect |
animation | Animation linking the two scenes together, which will be used whenever transitioning between the two. |
const std::string SceneManager::currentScene | ( | ) |
Get the currently active scene.
void SceneManager::transitionToScene | ( | const std::string | targetScene | ) |
Transition to a given scene.
This will look for, in this order:
targetScene
It will then kick off the transition to that scene, if it was found. If it was not, serious programmer error is presumed and the application will halt and output debug information via stderr.
targetScene | Scene to transition to. |
std::string SceneManager::prevScene | ( | ) |
Returns the name of the current scene's "Previous Scene", if this scene is part of a linear chain.
If this scene was never passed to connectScenesLinear
as the second scene, this will be empty.
std::string SceneManager::nextScene | ( | ) |
Returns the name of the current scene's "Next Scene", if this scene is part of a linear chain.
If this scene was never passed to connectScenesLinear
as the first scene, this will be empty.
|
inline |
Check whether a transition is currently running.
class SceneManager::SceneBuilder |
The SceneBuilder class is a helper for the buildup/teardown process of a Scene.
SceneManger::createScene!
This is primarily useful for putting up UI prep code, via callbacks to be fired before the Animation is hit. It also allows separating code that should be preserved even if the animations and links between scenes are modified.
As an example, in a multi-scene dialog, one would "place" the objects for the next scene in a setup callback, and would remove or hide them in a teardown callback.
onSetup
will be passed the name of the scene being transitioned away from.
onTeardown
will be passed the name of the scene that was transitioned to.
Example
An example Scene setup pattern might look like this.
onSetup and onTeardown also return references to the given SceneBuilder, so, if it were preferred, one could instead use the following pattern.
Public Member Functions | |
SceneBuilder (SceneManager *mgr, const std::string &name) | |
SceneBuilder & | onSetup (std::function< void(std::string fromScene)> func) |
SceneBuilder & | onTeardown (std::function< void(std::string toScene)> func) |
SceneManager::SceneBuilder::SceneBuilder | ( | SceneManager * | mgr, |
const std::string & | name | ||
) |
SceneBuilder & SceneManager::SceneBuilder::onSetup | ( | std::function< void(std::string fromScene)> | func | ) |
SceneBuilder & SceneManager::SceneBuilder::onTeardown | ( | std::function< void(std::string toScene)> | func | ) |