GG::DynamicGraphic

GG::DynamicGraphic Class Reference

a control that replays images in sequence, forwards or backwards, animated or one frame at a time. More...

#include <DynamicGraphic.h>

Inheritance diagram for GG::DynamicGraphic:

GG::Control GG::Wnd List of all members.

Signal Types

typedef boost::signal< void(int)> StoppedSignalType
typedef boost::signal< void(int)> EndFrameSignalType

Slot Types

typedef StoppedSignalType::slot_type StoppedSlotType
typedef EndFrameSignalType::slot_type EndFrameSlotType

Accessors

StoppedSignalType StoppedSignal
EndFrameSignalType EndFrameSignal
int Frames () const
bool Playing () const
bool Looping () const
double FPS () const
int FrameIndex () const
int TimeIndex () const
int StartFrame () const
int EndFrame () const
int Margin () const
int FrameWidth () const
int FrameHeight () const
Flags< GraphicStyle > Style () const

Structors

 DynamicGraphic (int x, int y, int w, int h, bool loop, int frame_width, int frame_height, int margin, const std::vector< boost::shared_ptr< Texture > > &textures, Flags< GraphicStyle > style=GRAPHIC_NONE, int frames=-1, Flags< WndFlag > flags=Flags< WndFlag >())

Mutators

virtual void Render ()
void AddFrames (const Texture *texture, int frames=-1)
void AddFrames (const boost::shared_ptr< Texture > &texture, int frames=-1)
void AddFrames (const std::vector< boost::shared_ptr< Texture > > &textures, int frames=-1)
void Play ()
void Pause ()
void NextFrame ()
void PrevFrame ()
void Stop ()
void Loop (bool b=true)
void SetFPS (double fps)
void SetFrameIndex (int idx)
void SetTimeIndex (int idx)
void SetStartFrame (int idx)
void SetEndFrame (int idx)
void SetStyle (Flags< GraphicStyle > style)
virtual void DefineAttributes (WndEditor *editor)

Exceptions

 GG_ABSTRACT_EXCEPTION (Exception)
 GG_CONCRETE_EXCEPTION (CannotAddFrame, GG::DynamicGraphic, Exception)

Structors

 DynamicGraphic ()

Accessors

int FramesInTexture (const Texture *t) const
const std::vector< FrameSet > & Textures () const
int CurrentTexture () const
int CurrentSubTexture () const
int FirstFrameTime () const
int LastFrameTime () const

Protected Attributes

const int m_margin
const int m_frame_width
const int m_frame_height

Classes

struct  FrameSet

Detailed Description

a control that replays images in sequence, forwards or backwards, animated or one frame at a time.

Frames of animation are stored in GG::Textures. The frames are assumed to be laid out int rows from right to left, top to bottom, like text. The location of each frame is calculated by DynamicGraphic; the user just needs to lay out the frames in the right order in the Texture(s) and give them to DynamicGraphic. If a Texture is to be used that has "dead space" where there are no frames, that space must be at the end of the Texture, and the number of frames in the Texture should be supplied when the Texture is added. When laying out the frames in the textures, the user can leave a margin between the frames and between the frames and the edge of the overall image, to make Texture creation and editing easier. The width of this margin must be supplied to DynamicGraphic's ctor, and is constant once set. The margin applies to the top and left of each image, so the margins at the right and bottom edges of the texture are optional. The multiple-Texture ctor assumes that all Textures but the last are packed with frames; if you need to specify multiple Textures with dead space, construct using the single-Texture ctor and use AddFrames(). Note that DynamicGraphic doesn't have "animated" in its name; it can replay images at any speed, and moreover it can be used as a sort of slideshow, and doesn't necessarily need to be animated at all.

Note:
This is a situation in which the "last+1" idiom used throughout GG does not apply; when you set the end frame index to N, the last frame to be shown will be N, not N - 1. Also, while this control does not need to be the same size as the frames replayed within it, the size of the frames is taken from the size of the control when it is contructed.

Definition at line 57 of file DynamicGraphic.h.

Member Typedef Documentation

typedef boost::signal<void (int)> GG::DynamicGraphic::StoppedSignalType

emitted whenever playback ends because the last frame was reached and Looping() == false; the argument is the index of the last frame (may be the first frame, if playing in reverse).

Note:
Unlike most other signals, this one is emitted during the execution of Render(), so keep this in mind when processing this signal.

Definition at line 64 of file DynamicGraphic.h.

typedef boost::signal<void (int)> GG::DynamicGraphic::EndFrameSignalType

emitted whenever the last frame of animation is reached; the argument is the index of the last frame (may be the first frame, if playing in reverse).

Note:
Unlike most other signals, this one is emitted during the execution of Render(), so keep this in mind when processing this signal.

Definition at line 69 of file DynamicGraphic.h.

typedef StoppedSignalType::slot_type GG::DynamicGraphic::StoppedSlotType

type of functor(s) invoked on a StoppedSignalType

Definition at line 73 of file DynamicGraphic.h.

typedef EndFrameSignalType::slot_type GG::DynamicGraphic::EndFrameSlotType

type of functor(s) invoked on a EndFrameSignalType

Definition at line 74 of file DynamicGraphic.h.

Constructor & Destructor Documentation

GG::DynamicGraphic::DynamicGraphic ( int  x,
int  y,
int  w,
int  h,
bool  loop,
int  frame_width,
int  frame_height,
int  margin,
const std::vector< boost::shared_ptr< Texture > > &  textures,
Flags< GraphicStyle >  style = GRAPHIC_NONE,
int  frames = -1,
Flags< WndFlag >  flags = Flags< WndFlag >() 
)

ctor taking a vector of GG::Textures and the number of frames in those Textures.

The default frames value -1 indicates all possible area is considered to contain valid frames. Regardless of the value of frames, all Textures but the last are assumed to have the maximum number of frames based on their sizes. This ctor allows specification of a frame size different from the size of the DynamicGraphic's size.

GG::DynamicGraphic::DynamicGraphic (  )  [protected]

default ctor

Member Function Documentation

int GG::DynamicGraphic::Frames (  )  const

returns the total number of frames in all the Textures that make up the animated sequence

bool GG::DynamicGraphic::Playing (  )  const

returns true if the animation is running

bool GG::DynamicGraphic::Looping (  )  const

returns true if playback is looping instead of stopping when it reaches the end

double GG::DynamicGraphic::FPS (  )  const

returns the number of frames playing per second; may be positive, 0, or negative

int GG::DynamicGraphic::FrameIndex (  )  const

returns the index of the currently-shown frame; -1 if none

int GG::DynamicGraphic::TimeIndex (  )  const

returns the time in ms (measured from the time of the first frame); -1 if none

int GG::DynamicGraphic::StartFrame (  )  const

returns the index of the earliest frame to be shown during playback.

Note:
when playing backwards this will be the last frame shown.

int GG::DynamicGraphic::EndFrame (  )  const

returns the index of the latest frame to be shown during playback.

Note:
when playing backwards this will be the first frame shown.

int GG::DynamicGraphic::Margin (  )  const

returns the number of pixels placed between frames and between the frames and the Texture edges

int GG::DynamicGraphic::FrameWidth (  )  const

returns the original width of the control (and the width of the frame images)

int GG::DynamicGraphic::FrameHeight (  )  const

returns the original height of the control (and the height of the frame images)

Flags<GraphicStyle> GG::DynamicGraphic::Style (  )  const

returns the style of the DynamicGraphic

See also:
StaticGraphicStyle

virtual void GG::DynamicGraphic::Render (  )  [virtual]

draws this Wnd.

Note that Wnds being dragged for a drag-and-drop operation are rendered twice -- once in-place as normal, once in the location of the drag operation, attached to the cursor. Such Wnds may wish to render themselves differently in those two cases. To determine which render is being performed, they can call GUI::GetGUI()->RenderingDragDropWnds().

Implements GG::Control.

void GG::DynamicGraphic::AddFrames ( const Texture *  texture,
int  frames = -1 
)

adds a set of frames from Texture texture to the animation.

If frames == -1, the Texture is assumed to contain the maximum possible number of frames based on its size and the frame size.

Warning:
Calling code must not delete texture; texture becomes the property of a shared_ptr inside the DynamicGraphic.
Exceptions:
GG::DynamicGraphic::CannotAddFrame Throws if texture is not large enough to contain any frames.

void GG::DynamicGraphic::AddFrames ( const boost::shared_ptr< Texture > &  texture,
int  frames = -1 
)

adds a set of frames from Texture texture to the animation.

If frames == -1, the Texture is assumed to contain the maximum possible number of frames based on its size and the frame size.

Exceptions:
GG::DynamicGraphic::CannotAddFrame Throws if texture is not large enough to contain any frames.

void GG::DynamicGraphic::AddFrames ( const std::vector< boost::shared_ptr< Texture > > &  textures,
int  frames = -1 
)

adds a set of frames from Texture texture to the animation.

If frames == -1, the Textures are assumed to contain the maximum possible number of frames based on its size and the frame size. Regardless of the value of frames, all Textures but the last are assumed to have the maximum number of frames based on their sizes.

Exceptions:
GG::DynamicGraphic::CannotAddFrame Throws if no texture in textures is large enough to contain any frames.

void GG::DynamicGraphic::Play (  ) 

starts the animation of the image

void GG::DynamicGraphic::Pause (  ) 

stops playback without adjusting the frame index

void GG::DynamicGraphic::NextFrame (  ) 

increments the frame index by 1. If Looping() == true and the next frame would be be past the last, the first frame is shown. Pauses playback.

void GG::DynamicGraphic::PrevFrame (  ) 

decrements the frame index by 1. If Looping() == true and the next frame would be be past the first, the last frame is shown. Pauses playback.

void GG::DynamicGraphic::Stop (  ) 

stops playback and resets the frame index to 0

void GG::DynamicGraphic::Loop ( bool  b = true  ) 

turns looping of playback on or off

void GG::DynamicGraphic::SetFPS ( double  fps  ) 

sets the frames per second playback speed (default is 15.0 FPS).

Negative rates indicate reverse playback.

Note:
Calling SetFPS(0.0) is equivalent to calling Pause().

void GG::DynamicGraphic::SetFrameIndex ( int  idx  ) 

sets the frame index to idx ( value is locked to range [0, Frames()] )

void GG::DynamicGraphic::SetTimeIndex ( int  idx  ) 

sets the frame index to the frame nearest time index idx, where idx measures time in ms from the beginning of the animation ( value is locked to range [0, Frames() * FPS()) ).

Note:
If looping is enabled, the time index may be any value >= 0.0, and values will "wrap" around the length of a loop. If looping is disabled, any time index idx that is later than Frames() * FPS() is mapped to the last frame.

void GG::DynamicGraphic::SetStartFrame ( int  idx  ) 

sets the index of the first frame to be shown during playback ( value is locked to range [0, Frames()] ).

Note:
when playing backwards this will be the last frame shown.

void GG::DynamicGraphic::SetEndFrame ( int  idx  ) 

sets the index of the last frame to be shown during playback ( value is locked to range [0, Frames()] ).

Note:
when playing backwards this will be the first frame shown.

void GG::DynamicGraphic::SetStyle ( Flags< GraphicStyle >  style  ) 

sets the style flags, and perfroms sanity checking

See also:
StaticGraphicStyle

virtual void GG::DynamicGraphic::DefineAttributes ( WndEditor *  editor  )  [virtual]

provides the attributes of this object that are appropriate for a user to edit in a WndEditor; see WndEditor for details.

Reimplemented from GG::Control.

GG::DynamicGraphic::GG_ABSTRACT_EXCEPTION ( Exception   ) 

The base class for DynamicGraphic exceptions.

Reimplemented from GG::Wnd.

GG::DynamicGraphic::GG_CONCRETE_EXCEPTION ( CannotAddFrame  ,
GG::DynamicGraphic  ,
Exception   
)

Thrown when an attempt is made to add a frame to a DynamicGraphic which has no storage allocated for frames.

int GG::DynamicGraphic::FramesInTexture ( const Texture *  t  )  const [protected]

returns the maximum number of frames that could be stored in t given the size of the control and Margin()

const std::vector<FrameSet>& GG::DynamicGraphic::Textures (  )  const [protected]

returns the shared_ptrs to texture objects with all animation frames

int GG::DynamicGraphic::CurrentTexture (  )  const [protected]

returns the current Texture being shown (part of it, anyway); -1 if none

int GG::DynamicGraphic::CurrentSubTexture (  )  const [protected]

returns the current frame being shown within Texture number CurrTexture(); -1 if none

int GG::DynamicGraphic::FirstFrameTime (  )  const [protected]

returns the time index in ms that the first frame in the sequence was shown during the current playback; -1 if none

int GG::DynamicGraphic::LastFrameTime (  )  const [protected]

returns the time index in ms of the most recent frame shown (should be m_curr_frame); -1 if none

Member Data Documentation

StoppedSignalType GG::DynamicGraphic::StoppedSignal [mutable]

the stopped signal object for this DynamicGraphic

Definition at line 106 of file DynamicGraphic.h.

EndFrameSignalType GG::DynamicGraphic::EndFrameSignal [mutable]

the end-frame signal object for this DynamicGraphic

Definition at line 107 of file DynamicGraphic.h.

const int GG::DynamicGraphic::m_margin [protected]

the number of pixels placed between frames and between the frames and the Texture edges

Definition at line 199 of file DynamicGraphic.h.

const int GG::DynamicGraphic::m_frame_width [protected]

the width of each frame

Definition at line 200 of file DynamicGraphic.h.

const int GG::DynamicGraphic::m_frame_height [protected]

the height of each frame

Definition at line 201 of file DynamicGraphic.h.

The documentation for this class was generated from the following file:
Generated on Wed Mar 26 14:35:42 2008 for GG by  doxygen 1.5.2