AnimationController Class Reference

Plays one or more animations synchronously. More...

#include <AnimationController.h>

Inheritance diagram for AnimationController:

Inheritance graph

List of all members.

Public Member Functions

virtual Animation * createAnimation (const std::string &name)=0
virtual Animation * getAnimation (const std::string &name) const =0
virtual bool hasAnimation (const std::string &name) const =0
virtual const std::vector
< Animation * > & 		getAnimations () const =0
virtual unsigned int getNumAnimations () const =0
virtual void destroyAnimation (Animation *pAnimation)=0
virtual FrameType getFrameType () const =0
virtual void setCurrentFrame (double frameValue)=0
virtual double getCurrentFrame () const =0
virtual double getStartFrame () const =0
virtual double getStopFrame () const =0
virtual bool getBumpersEnabled () const =0
virtual void setBumpersEnabled (bool enabled)=0
virtual double getStartBumper () const =0
virtual void setStartBumper (double frameValue)=0
virtual double getStopBumper () const =0
virtual void setStopBumper (double frameValue)=0
virtual void setIntervalMultiplier (double multiplier)=0
virtual double getIntervalMultiplier () const =0
virtual const int getFrequency () const =0
virtual boost::rational< int > getMinimumFrameRate () const =0
virtual void setMinimumFrameRate (boost::rational< int > frameRate)=0
virtual void setAnimationState (AnimationState state)=0
virtual AnimationState getAnimationState () const =0
virtual void setAnimationCycle (AnimationCycle cycle)=0
virtual AnimationCycle getAnimationCycle () const =0
virtual void moveToBeginning ()=0
virtual void moveToEnd ()=0
virtual void play ()=0
virtual void pause ()=0
virtual void stop ()=0
virtual void fastForward (double multiplier)=0
virtual void fastRewind (double multiplier)=0
virtual void stepForward ()=0
virtual void stepBackward ()=0
virtual void setCanDropFrames (bool drop)=0
virtual bool getCanDropFrames () const =0

Static Public Member Functions

static double getSettingFrameSpeedSelection ()
static bool hasSettingFrameSpeedSelection ()
static void setSettingFrameSpeedSelection (double newValue, bool setIfSame=false)
static std::string getSettingFrameSpeedSelectionKey ()
static AnimationCycle getSettingAnimationCycleSelection ()
static bool hasSettingAnimationCycleSelection ()
static void setSettingAnimationCycleSelection (AnimationCycle newValue, bool setIfSame=false)
static std::string getSettingAnimationCycleSelectionKey ()
static bool getSettingCanDropFrames ()
static bool hasSettingCanDropFrames ()
static void setSettingCanDropFrames (bool newValue, bool setIfSame=false)
static std::string getSettingCanDropFramesKey ()
static const std::string & signalRenamed ()
static const std::string & signalAnimationAdded ()
static const std::string & signalFrameChanged ()
static const std::string & signalIntervalMultiplierChanged ()
static const std::string & signalAnimationStateChanged ()
static const std::string & signalAnimationCycleChanged ()
static const std::string & signalAnimationRemoved ()
static const std::string & signalFrameRangeChanged ()
static const std::string & signalBumpersEnabledChanged ()
static const std::string & signalBumperStartChanged ()
static const std::string & signalBumperStopChanged ()

Protected Member Functions

virtual ~AnimationController ()

Detailed Description

Plays one or more animations synchronously.

An animation controller allows multiple animations to be played synchronously at a particular rate. This can be particularly useful with time-based controllers. In addition to the animations, the controller stores a start value, stop value, and current value. These values are updated automatically when the frames in an animation change, or when an animation is destroyed. The start value is defined as the minimum value across all frames in all animations according to the frame value type specified at the creation of the controller. Similarly, the stop value is defined as the maximum value across all frames in all animations according to the controller's frame value type. Animations must be created within the animation controller, which guarantees that the animation and the controller will have the same frame type.

When playing animations, each animation is updated at a constant frequency, specified by getFrequency(). This means that rate at which Animation::setCurrentFrame() is called does not change. The value that is passed to the animation when the current frame is set can be modified by changing the interval multiplier. This has the effect of speeding up or slowing down the animations.

The frame rate is based on the frequency and the interval multiplier. In some cases the desired frame rate cannot be achieved due to limitations in the hardware. If this occurs, frames will be dropped when playing through the animations to preserve the integrity of the frame rate.

An animation controller is created and destroyed from the animation window. When an animation controller is destroyed, all animations contained in the controller are also destroyed.

This subclass of Subject will notify upon the following conditions:

See also:
Animation, AnimationDialog

Definition at line 63 of file AnimationController.h.

Constructor & Destructor Documentation

virtual AnimationController::~AnimationController (  )  [protected, virtual]

This should be destroyed by calling AnimationToolbar::destroyAnimationController.

Definition at line 692 of file AnimationController.h.

Member Function Documentation

static double AnimationController::getSettingFrameSpeedSelection (  )  [static]

Returns the current value for this setting.

If this setting does not exist in ConfigurationSettings, a verification error will be logged to the message log and potentially a verification error message box will be displayed to the user.

Please see Settings Macros for more details

Returns:
the current value for this setting.

Definition at line 76 of file AnimationController.h.

static bool AnimationController::hasSettingFrameSpeedSelection (  )  [static]

Returns true if this setting exists and has a value in ConfigurationSettings.

Please see Settings Macros for more details

Returns:
true if this setting exists, false otherwise.

Definition at line 83 of file AnimationController.h.

static void AnimationController::setSettingFrameSpeedSelection ( double  newValue,
bool  setIfSame = false 
) [static]

Changes the current value of this setting to the new value.

Please see Settings Macros for more details

Parameters:
newValue the new value for this setting.
setIfSame If true, the value will be set into ConfigurationSettings even if the newValue and existing value are the same. This has the side-effect of making the value a per-user setting and stored in the user's configuration file. If false, this value will only be set if the newValue and existing value are different. Therefore the value will only be stored in the user's configuration file if the newValue is unique to the user.

Definition at line 99 of file AnimationController.h.

static std::string AnimationController::getSettingFrameSpeedSelectionKey (  )  [static]

Returns the key for this setting that could be passed to ConfigurationSettings::getSetting() or ConfigurationSettings::setSetting().

Please see Settings Macros for more details

Returns:
the key used for this setting.

Definition at line 107 of file AnimationController.h.

static AnimationCycle AnimationController::getSettingAnimationCycleSelection (  )  [static]

Returns the current value for this setting.

If this setting does not exist in ConfigurationSettings, a verification error will be logged to the message log and potentially a verification error message box will be displayed to the user.

Please see Settings Macros for more details

Returns:
the current value for this setting.

Definition at line 118 of file AnimationController.h.

static bool AnimationController::hasSettingAnimationCycleSelection (  )  [static]

Returns true if this setting exists and has a value in ConfigurationSettings.

Please see Settings Macros for more details

Returns:
true if this setting exists, false otherwise.

Definition at line 125 of file AnimationController.h.

static void AnimationController::setSettingAnimationCycleSelection ( AnimationCycle  newValue,
bool  setIfSame = false 
) [static]

Changes the current value of this setting to the new value.

Please see Settings Macros for more details

Parameters:
newValue the new value for this setting.
setIfSame If true, the value will be set into ConfigurationSettings even if the newValue and existing value are the same. This has the side-effect of making the value a per-user setting and stored in the user's configuration file. If false, this value will only be set if the newValue and existing value are different. Therefore the value will only be stored in the user's configuration file if the newValue is unique to the user.

Definition at line 141 of file AnimationController.h.

static std::string AnimationController::getSettingAnimationCycleSelectionKey (  )  [static]

Returns the key for this setting that could be passed to ConfigurationSettings::getSetting() or ConfigurationSettings::setSetting().

Please see Settings Macros for more details

Returns:
the key used for this setting.

Definition at line 149 of file AnimationController.h.

static bool AnimationController::getSettingCanDropFrames (  )  [static]

Returns the current value for this setting.

If this setting does not exist in ConfigurationSettings, a verification error will be logged to the message log and potentially a verification error message box will be displayed to the user.

Please see Settings Macros for more details

Returns:
the current value for this setting.

Definition at line 160 of file AnimationController.h.

static bool AnimationController::hasSettingCanDropFrames (  )  [static]

Returns true if this setting exists and has a value in ConfigurationSettings.

Please see Settings Macros for more details

Returns:
true if this setting exists, false otherwise.

Definition at line 167 of file AnimationController.h.

static void AnimationController::setSettingCanDropFrames ( bool  newValue,
bool  setIfSame = false 
) [static]

Changes the current value of this setting to the new value.

Please see Settings Macros for more details

Parameters:
newValue the new value for this setting.
setIfSame If true, the value will be set into ConfigurationSettings even if the newValue and existing value are the same. This has the side-effect of making the value a per-user setting and stored in the user's configuration file. If false, this value will only be set if the newValue and existing value are different. Therefore the value will only be stored in the user's configuration file if the newValue is unique to the user.

Definition at line 183 of file AnimationController.h.

static std::string AnimationController::getSettingCanDropFramesKey (  )  [static]

Returns the key for this setting that could be passed to ConfigurationSettings::getSetting() or ConfigurationSettings::setSetting().

Please see Settings Macros for more details

Returns:
the key used for this setting.

Definition at line 191 of file AnimationController.h.

static const std::string& AnimationController::signalRenamed (  )  [static]

Emitted with boost::any<std::string> when the controller is renamed.

See also:
AnimationServices::renameAnimationController()

Definition at line 198 of file AnimationController.h.

static const std::string& AnimationController::signalAnimationAdded (  )  [static]

Emitted with boost::any<Animation*> when an Animation is added to the controller.

Definition at line 204 of file AnimationController.h.

static const std::string& AnimationController::signalFrameChanged (  )  [static]

Emitted with boost::any<double> when the current frame changes.

See also:
getCurrentFrame()

Definition at line 211 of file AnimationController.h.

static const std::string& AnimationController::signalIntervalMultiplierChanged (  )  [static]

Emitted with boost::any<double> when the speed multiplier changes.

Definition at line 216 of file AnimationController.h.

static const std::string& AnimationController::signalAnimationStateChanged (  )  [static]

Emitted with boost::any<AnimationState> when the animation state of the controller changes.

Definition at line 222 of file AnimationController.h.

static const std::string& AnimationController::signalAnimationCycleChanged (  )  [static]

Emitted with boost::any<AnimationCycle> when the animation cycle of the controller changes.

Definition at line 228 of file AnimationController.h.

static const std::string& AnimationController::signalAnimationRemoved (  )  [static]

Emitted with boost::any<Animation*> when an Animation is removed from the controller.

This signal will not be emitted when the controller is removing Animations within its destructor.

Definition at line 235 of file AnimationController.h.

static const std::string& AnimationController::signalFrameRangeChanged (  )  [static]

Emitted when the frame range changes for any reason.

Definition at line 240 of file AnimationController.h.

static const std::string& AnimationController::signalBumpersEnabledChanged (  )  [static]

Emitted with boost::any<bool> when the enabled status of the playback bumpers changes for any reason.

Definition at line 246 of file AnimationController.h.

static const std::string& AnimationController::signalBumperStartChanged (  )  [static]

Emitted with boost::any<double> when the start playback bumper changes for any reason.

Definition at line 251 of file AnimationController.h.

static const std::string& AnimationController::signalBumperStopChanged (  )  [static]

Emitted with boost::any<double> when the stop playback bumper changes for any reason.

Definition at line 256 of file AnimationController.h.

virtual Animation* AnimationController::createAnimation ( const std::string &  name  )  [pure virtual]

Creates a new animation and adds it to the controller.

This method creates a new animation with the given name and the same frame type as the controller. The animation is then added to the internal vector of animations. The animation name must be unique within the controller.

Parameters:
name The animation name. This name cannot be empty and must be unique for all animations in the controller.
Returns:
A pointer to the new animation. NULL is returned if an animation of the given name already exists in the controller.
Subject Notifications:
This method will notify signalAnimationAdded() with any<Animation*> after the animation is added to the internal vector.

virtual Animation* AnimationController::getAnimation ( const std::string &  name  )  const [pure virtual]

Retrieves an animation with a given name.

Parameters:
name The animation name.
Returns:
A pointer to the existing animation in the controller. NULL is returned if no animation exists in the controller with the given name.

virtual bool AnimationController::hasAnimation ( const std::string &  name  )  const [pure virtual]

Queries whether an animation with a given name exists in the controller.

Parameters:
name The animation name.
Returns:
True if an animation with the given name exists in the controller, otherwise false.

virtual const std::vector<Animation*>& AnimationController::getAnimations (  )  const [pure virtual]

Retrieves all animations in the controller.

Returns:
A const reference to the internal vector of animations. The vector should not be modified in any way. To change the contents of the vector, use createAnimation() and destroyAnimation() instead.

virtual unsigned int AnimationController::getNumAnimations (  )  const [pure virtual]

Returns the number of animations in the controller.

This is a convenience method that is identical to getAnimations().size().

Returns:
The number of animations in the controller.

virtual void AnimationController::destroyAnimation ( Animation *  pAnimation  )  [pure virtual]

Removes an existing animation from the controller and deletes it.

Parameters:
pAnimation The animation to destroy.
Subject Notifications:
This method will notify signalAnimationRemoved() with any<Animation*> after the animation has been removed from the controller but before the animation is deleted. This method will also notify a second time if the result of removing the animation changes the start and/or stop values for the controller. This notification will occur after the removal notification and before the animation is deleted.

virtual FrameType AnimationController::getFrameType (  )  const [pure virtual]

Returns the type of frame value that the controller uses to set the current frame in the animations.

This method returns whether the controller operates on frame numbers or time values when setting the current frame in the animations. The frame type is specified when the controller is created in AnimationToolBar::createAnimationController(). Once the controller is created, the frame type cannot be changed.

Returns:
The animation controller's frame type.
See also:
setCurrentFrame(), getCurrentFrame(), getStartFrame(), getStopFrame()

virtual void AnimationController::setCurrentFrame ( double  frameValue  )  [pure virtual]

Sets the current frame value in the controller.

This method sets the controller's frame value, and automatically sets the current frame in each animation with the given value. This may or may not actually set the current frame in the animation. Since the value is the same across all animations in the controller, it is the responsibility of the animation to determine whether or not to update its current frame based on the value.

Parameters:
frameValue The new frame value for the controller. The value should correspond to the type returned by getFrameType().
Subject Notifications:
This method will notify signalFrameChanged() with any<const AnimationFrame*>.

virtual double AnimationController::getCurrentFrame (  )  const [pure virtual]

Returns the current frame value in the controller.

Returns:
The current frame value. The value corresponds to the type returned by getFrameType().

virtual double AnimationController::getStartFrame (  )  const [pure virtual]

Returns the starting frame value in the controller.

The starting frame value is defined as the minimum frame value across all frames in all animations.

Returns:
The starting frame value. The value corresponds to the type returned by getFrameType().

virtual double AnimationController::getStopFrame (  )  const [pure virtual]

Returns the ending frame value in the controller.

The ending frame value is defined as the maximum frame value across all frames in all animations.

Returns:
The ending frame value. The value corresponds to the type returned by getFrameType().

virtual bool AnimationController::getBumpersEnabled (  )  const [pure virtual]

Returns the enabled status of the playback bumpers in the controller.

When the playback bumpers are enabled (status of true), the animation playback will be limited to the frame values between the start and stop playback bumpers.

Returns:
The enabled status of the playback bumpers.

virtual void AnimationController::setBumpersEnabled ( bool  enabled  )  [pure virtual]

Sets the enabled status of the playback bumpers in the controller.

When the playback bumpers are enabled (status of true), the animation playback will be limited to the frame values between the start and stop playback bumpers.

Parameters:
enabled The enabled status of the playback bumpers.
Subject Notifications:
This method will notify signalBumpersEnabledChanged() with boost::any<bool>.

virtual double AnimationController::getStartBumper (  )  const [pure virtual]

Returns the start playback bumper value in the controller.

The start playback bumper value is defined as the first frame value across all frames in all animations that will be played back when the playback bumpers are enabled.

Returns:
The start bumper value. The value corresponds to the type returned by getFrameType().

virtual void AnimationController::setStartBumper ( double  frameValue  )  [pure virtual]

Sets the start playback bumper value in the controller.

The start playback bumper value is defined as the first frame value across all frames in all animations that will be played back when the playback bumpers are enabled.

Parameters:
frameValue The start bumper value.
Subject Notifications:
This method will notify signalBumperStartChanged() with boost::any<double>.

virtual double AnimationController::getStopBumper (  )  const [pure virtual]

Returns the stop playback bumper value in the controller.

The stop playback bumper value is defined as the last frame value across all frames in all animations that will be played back when the playback bumpers are enabled.

Returns:
The stop bumper value. The value corresponds to the type returned by getFrameType().

virtual void AnimationController::setStopBumper ( double  frameValue  )  [pure virtual]

Sets the stop playback bumper value in the controller.

The stop playback bumper value is defined as the last frame value across all frames in all animations that will be played back when the playback bumpers are enabled.

Parameters:
frameValue The stop bumper value.
Subject Notifications:
This method will notify signalBumperStopChanged() with boost::any<double>.

virtual void AnimationController::setIntervalMultiplier ( double  multiplier  )  [pure virtual]

Sets the multiplier value associated with the value interval that is used when the controller is advanced.

This method provides the capability to effectively speed up or slow down the animations. The interval is defined as the value that is set when the controller is advanced based on the frequency. The multipler will increase or decrease the interval value used to set the current frame at the same frequency.

Parameters:
multiplier The value to mutliply the interval by when advancing frames in each animation. A value between 0.0 and 1.0 will effectively slow down the animations and a value greater than 1.0 will speed up the animations. This method does nothing if the value is less than or equal to 0.0. The default multiplier is 1.0.
Subject Notifications:
This method will notify signalIntervalMultiplierChanged() with any<double>.
See also:
getFrequency()

virtual double AnimationController::getIntervalMultiplier (  )  const [pure virtual]

Returns the multiplier value associated with the value interval that is used when the controller is advanced.

Returns:
The interval multipler value.
See also:
setIntervalMultiplier()

virtual const int AnimationController::getFrequency (  )  const [pure virtual]

Returns the frequency of when the animations in the controller are updated.

Returns:
The frequency of how often animations are updated.
See also:
setIntervalMultiplier()

virtual boost::rational<int> AnimationController::getMinimumFrameRate (  )  const [pure virtual]

Returns the suggested minimum frame rate.

This is the minimum frame rate needed to completely capture all frames accurately. This defaults to 60fps which is currently the highest frame rate a AnimationController can display at 1x playback speed. If a lower minimum frame rate is possible, plug-ins may set the value with setMinimumFrameRate(). Frame rates are represented as frames/seconds

Returns:
The minimum suggested frame rate.

virtual void AnimationController::setMinimumFrameRate ( boost::rational< int >  frameRate  )  [pure virtual]

Sets the suggested minimum frame rate.

This is the minimum frame rate needed to completely capture all frames accurately. This defaults to 60fps which is currently the highest frame rate a AnimationController can display at 1x playback speed. If a lower minimum frame rate is possible, plug-ins should set this value. Frame rates are represented as frames/seconds

Parameters:
frameRate The minimum suggested frame rate.

virtual void AnimationController::setAnimationState ( AnimationState  state  )  [pure virtual]

Starts or stops the controller.

The animation state applies to the controller so all animations are affected by the new state.

Parameters:
state The new animation state for the controller.
Subject Notifications:
This method will notify signalAnimationStateChanged() with any<AnimationState>.
See also:
AnimationState, play(), pause(), stop()

virtual AnimationState AnimationController::getAnimationState (  )  const [pure virtual]

Returns the current animation state of the controller.

Returns:
The current animation state.
See also:
AnimationState

virtual void AnimationController::setAnimationCycle ( AnimationCycle  cycle  )  [pure virtual]

Sets the behavior of the controller after the stop frame value is set.

Parameters:
cycle The new animation cycle for the controller.
Subject Notifications:
This method will notify signalAnimationCycleChanged() with any<AnimationCycle>.
See also:
AnimationCycle

virtual AnimationCycle AnimationController::getAnimationCycle (  )  const [pure virtual]

Returns the current animation cycle of the controller.

Returns:
The current animation cycle.
See also:
AnimationCycle

virtual void AnimationController::moveToBeginning (  )  [pure virtual]

Sets the current frame to the starting frame value.

See also:
moveToEnd(), setCurrentFrame()

virtual void AnimationController::moveToEnd (  )  [pure virtual]

Sets the current frame to the ending frame value.

See also:
moveToBeginning(), setCurrentFrame()

virtual void AnimationController::play (  )  [pure virtual]

Starts playing animations.

If the controller was previously paused or stopped, the animations play in the forward direction. If the controller was previously playing backward, it continues to do so.

See also:
fastForward(), fastRewind()

virtual void AnimationController::pause (  )  [pure virtual]

Stops playing animations without changing the current frame.

See also:
stop()

virtual void AnimationController::stop (  )  [pure virtual]

Stops playing animations and changes the current frame.

After stopping the controller the current frame is changed to the starting frame if the previous animation state was AnimationState::PLAY_FORWARD. If the previous animation state was AnimationState::PLAY_BACKWARD the current frame is changed to the ending frame.

See also:
pause(), moveToBeginning(), moveToEnd()

virtual void AnimationController::fastForward ( double  multiplier  )  [pure virtual]

Sets the interval multiplier and plays in the forward direction.

Parameters:
multiplier The desired interval multiplier.
See also:
fastRewind(), setIntervalMultiplier()

virtual void AnimationController::fastRewind ( double  multiplier  )  [pure virtual]

Sets the interval multiplier and plays in the backward direction.

Parameters:
multiplier The desired interval multiplier.
See also:
fastForward(), setIntervalMultiplier()

virtual void AnimationController::stepForward (  )  [pure virtual]

Changes the current frame to the next frame in the frame list.

The current frame is changed to the next frame in the frame list.

See also:
fastForward(), fastRewind()

virtual void AnimationController::stepBackward (  )  [pure virtual]

Changes the current frame to the previous frame in the frame list.

The current frame is changed to the previous frame in the frame list.

See also:
fastForward(), fastRewind()

virtual void AnimationController::setCanDropFrames ( bool  drop  )  [pure virtual]

Sets the controller to play the attached animations at without dropping frames.

Due to system limitations, frames may be dropped in order to achieve the desired play rate. This method controls whether or not this is allowed. This is true by default.

Parameters:
drop True if frames are allowed to be dropped, false otherwise.

virtual bool AnimationController::getCanDropFrames (  )  const [pure virtual]

Gets whether the controller is allowed to drop frames in order to play at the desired rate.

Returns:
True if the play may drop frames, false otherwise.
See also:
setCanDropFrames()

Software Development Kit - Opticks 4.9.0 Build 16218