Animation for UI Elements (wxAnimation)

[Bogdan Chiciu Gabriel]

Greetings everyone,

My name is Gabriel and this summer I will be working on bringing UI
animation to wxWidgets.

There are still a lot of aspects to discuss but for now the main
target is to allow the writing of animations like this

using code that looks
something like this:

wxStoryboard storyboard = new Storyboard();
wxPointAnimation* slide_animation = new wxPointAnimation();

slide_animation->SetDuration(0.5);
slide_animation->SetInitialValue(button1->GetPosition());
slide_animation->SetFinalValue(wxPoint(500,500));

storyboard->AddAnimation(slide_animation);
storyboard->SetTarget(button1);
storyboard->Play();

And it will be available on both Windows and Mac and it will be built
upon Windows Animation and Core Animation. Posting the list of planned
features and proposed (simple and easy to use) API* will be the next
step in the project.
* (the code above is used to make the animation in the video but i
have to see it work with Core Animation as well)

For anyone interested in this project I will be posting here (and
probably on some Twitter or blog) whenever any kind of interesting
progress is made.

This is will be it for today so best regards,

Gabriel

[Bogdan Chiciu Gabriel]

Greetings again,

The blueprint for the UI Animation is now relatively complete and can
be found at this link: https://docs.google.com/document/d/17FXskM4frkC0lngcuBdSEskIAnYw3nYWrPW8VME4Yvc/edit?hl=en_US

If anyone has any comments, questions or suggestions please feel free
to post.

Regards,

Gabriel

[Vadim Zeitlin]

On Mon, 30 May 2011 12:28:50 -0700 (PDT) Bogdan Chiciu Gabriel <chiciu.bogdan-***@public.gmane.org> wrote:

BCG> The blueprint for the UI Animation is now relatively complete and can
BCG> be found at this link: https://docs.google.com/document/d/17FXskM4frkC0lngcuBdSEskIAnYw3nYWrPW8VME4Yvc/edit?hl=en_US

Hello,

Thanks for the write up! The first part was definitely useful as a
reminder and also to define the terminology used and the main conclusion
from it that I see is that we should provide mostly OS X-like animation API
as it is higher level than the Windows one and should be both implementable
in terms of the latter and be simpler to use. I also agree with the
approach you propose for supporting layer animations but, as you say, this
will be discussed in more details later so let's not speak about it for
now.


My comments/questions are mostly about the second part. First, there is
the usual naming issue or even two of them:

1(a) wxAnimationBase is an existing class representing an image-animation
loaded from file and while it's relatively close to your class, it's
not really the same thing and I don't think it can be reused. So we
need a different name for this one, unfortunately.

(b) More generally I wonder if we should use some common prefix for the
new classes or some other naming convention to emphasize their
relationship. Starting all of them with "wxAnimation" could be a way
to do it but this would result in some rather long names. OTOH is it
really that difficult to write^H^H^H^H^H auto-complete
wxAnimationinterpolationFunction?


The second and more important group of questions concerns the API itself.

2(a) What is wxAnimationGroup (returned by wxStoryboard method of the same
name)? It doesn't seem to be mentioned anywhere else.

(b) Why does wxStoryboard derive from wxAnimationObject and what does the
latter actually do? Is it just a mix-in/interface providing the single
BeginAnimation() (pure virtual) method? Is wxWindow meant to derive
from it? If so, I don't see how is this compatible with separating the
animation classes in an independent library.

FWIW I don't know how useful is it to animate a single window, I've
never really used animations in my programs (yet) so I'm not sure how
often can you avoid using wxStoryboard and use this simplified API.
But if we do want to have it, I think we should rather provide a
function (or static method) in the animation library doing this rather
than adding a method to wxWindow itself.

(c) Will wx[Type]Animation be really differently named classes or can we
have just a single wxAnimatedProperty<T> template class? Which would
be simpler to implement? Could it be useful to have specializations of
such a template in user code and, if so, would this be possible to
implement?

(d) Maybe related to above, the relationship between wx[Type]Animation and
wxAnimationTargetProperty is not really clear to me. Should we really
have wxPointAnimation and then use it only with
wx_ANIMATION_TARGET_PROPERTY_POSITION (BTW, we use "wx" prefix for the
constants, not "wx_") or should we have wxAnimatedPositionProperty
instead?

(e) Should wxKeyframe really derive from wxAnimationBase? I understand
that they share some of the same properties but a key frame is not an
animation, is it? Maybe we should rather specify the start time and
duration of a key frame when adding it to wxKeyframeAnimation?

(f) Should wxInterpolationFunction be public? AFAIU it can't be
implemented under OS X so maybe it would be better to only use it in
MSW implementation? Of course, if you decide to make it public and
just document that it's MSW-only, it would be perfectly fine too but
I'm just not sure if it's necessary to do it.

(g) I think we need events for each transition in key frame animation in
addition to the animation end (which is a kind of special transition).


Finally, the last group is about the ownership rules for all the various
objects. To be precise:

3(a) Who is responsible for wxStoryboard deallocation? Is it done by the
user only or will wxWidgets itself delete it when the animation ends
or at some other time?

(b) What about wxAnimationBase=derived objects passed to AddAnimation()?
Will they be deleted by the animation itself? And what happens when
RemoveAnimation() is called (BTW, do we really need this one at all?).

(c) Same question about key frames: I guess the animation takes ownership
of them when they're added to it?

(d) Why is wxAnimationDuration passed to/returned by wxAnimationBase by
pointer? I think it should be simply passed by value if it's really
just a wxTimeSpan basically.


That's all for now, looking forward to your thoughts about all this!
VZ

[Bogdan Chiciu Gabriel]

Small updates have been brought to the document.

Post by Vadim Zeitlin
1(a) wxAnimationBase is an existing class representing an image-animation
     loaded from file and while it's relatively close to your class, it's
     not really the same thing and I don't think it can be reused. So we
     need a different name for this one, unfortunately.
 (b) More generally I wonder if we should use some common prefix for the
     new classes or some other naming convention to emphasize their
     relationship. Starting all of them with "wxAnimation" could be a way
     to do it but this would result in some rather long names. OTOH is it
     really that difficult to write^H^H^H^H^H auto-complete
     wxAnimationinterpolationFunction?

Yes i was aware of both wxAnimationBase and wxAnimation existing. The
name was picked just to better depict the idea that that is the base
class. It will be renamed to something else (I have no idea what at
this point as I'm usually picky with names, probably wxBaseAnimation).
And there should be no reason not to prefix the classes in the library
with wxAnimation (to a certain extent of course
wxAnimationKeyframeAnimation sound a bit silly).

Post by Vadim Zeitlin
2(a) What is wxAnimationGroup (returned by wxStoryboard method of the same
     name)? It doesn't seem to be mentioned anywhere else.

Since we were adding animation to the storyboard I figured that having
a way to return them all could not hurt. It was not really defined so
I left it out but it could something similar to wxWindowList or
something of sorts.

Post by Vadim Zeitlin
 (b) Why does wxStoryboard derive from wxAnimationObject and what does the
     latter actually do? Is it just a mix-in/interface providing the single
     BeginAnimation() (pure virtual) method? Is wxWindow meant to derive
     from it? If so, I don't see how is this compatible with separating the
     animation classes in an independent library.
     FWIW I don't know how useful is it to animate a single window, I've
     never really used animations in my programs (yet) so I'm not sure how
     often can you avoid using wxStoryboard and use this simplified API.
     But if we do want to have it, I think we should rather provide a
     function (or static method) in the animation library doing this rather
     than adding a method to wxWindow itself.

Removed the base class. Moved wxAnimationObject to a special mentions
section and added a static method that can play an animation for a
specific target as you suggested.

Post by Vadim Zeitlin
 (c) Will wx[Type]Animation be really differently named classes or can we
     have just a single wxAnimatedProperty<T> template class? Which would
     be simpler to implement? Could it be useful to have specializations of
     such a template in user code and, if so, would this be possible to
     implement?
 (d) Maybe related to above, the relationship between wx[Type]Animation and
     wxAnimationTargetProperty is not really clear to me. Should we really
     have wxPointAnimation and then use it only with
     wx_ANIMATION_TARGET_PROPERTY_POSITION (BTW, we use "wx" prefix for the
     constants, not "wx_") or should we have wxAnimatedPositionProperty
     instead?

Both of these are great questions so I need further opinions on this.
All are absolutely valid propositions and could be implemented without
sacrificing ease of implementation too much.

Off the top of my head for wxAnimatedProperty<T>/
wxAnimatedPositionProperty/wxPointAnimation I would have been inclined
to pick wxTypeAnimation/wxAnimatedProperty<T> if there were many
properties to animate with that animation type and if specifying the
property of that type animation would have been easy (implementation
wise). However wxAnimated[PropertyName]Property is again a rather
great idea since there are not that many standard properties to
animate (for wxPoint I can only think of one) so you don't end up with
a multitude of classes. Moreover wxAnimated[PropertyName]Property
could be built on top of wxAnimatedProperty<T>/wx[Type]Animation.

My initial idea was to have type animations paired with a good way of
specifying a target property (it was specified in the document that it
still needs debating; more on this at the end of this post).

Post by Vadim Zeitlin
 (e) Should wxKeyframe really derive from wxAnimationBase? I understand
     that they share some of the same properties but a key frame is not an
     animation, is it? Maybe we should rather specify the start time and
     duration of a key frame when adding it to wxKeyframeAnimation?

Modified key frames to better reflect their purpose and relation to
Core Animation key frames

Post by Vadim Zeitlin
 (f) Should wxInterpolationFunction be public? AFAIU it can't be
     implemented under OS X so maybe it would be better to only use it in
     MSW implementation? Of course, if you decide to make it public and
     just document that it's MSW-only, it would be perfectly fine too but
     I'm just not sure if it's necessary to do it.

This will be provided as MSW only. wxMediaTimerFunction enum has been
added to select the interpolation function (Core Animation calls them
CAMediaTimerFunctions) used by the transition on both platforms (Core
Animation has 3/4 and Windows Animation has about 10 or so)

Post by Vadim Zeitlin
3(a) Who is responsible for wxStoryboard deallocation? Is it done by the
     user only or will wxWidgets itself delete it when the animation ends
     or at some other time?
 (b) What about wxAnimationBase=derived objects passed to AddAnimation()?
     Will they be deleted by the animation itself? And what happens when
     RemoveAnimation() is called (BTW, do we really need this one at all?).
 (c) Same question about key frames: I guess the animation takes ownership
     of them when they're added to it?

I think the user should be responsible for releasing the storyboard.
The idea is that a storyboard can be used throughout the life-time of
the application (create it once, call Begin whenever you want).
Releasing animation objects is again not so simple, a developer might
have used the same animation for a different storyboard(valid case I'd
assume) and it would be unwise to delete his animations simply because
one storyboard was no longer used. We could simply pass animations by
value since they're really simple objects with the sole purpose of
passing data to storyboards and they also hold no reference to
external objects.

(b RemoveAnimation) This was added simply with the idea that it might
be useful to someone and given the fact that we're storing the
animations added to the storyboard (so it was easy to provide a remove
animation method).

Post by Vadim Zeitlin
 (d) Why is wxAnimationDuration passed to/returned by wxAnimationBase by
     pointer? I think it should be simply passed by value if it's really
     just a wxTimeSpan basically.

Changed. Slight mistake on my part of leaving it there (I was passing
it by value in the examples as well)

Thank you for the comments. I'm really interested to hearing more on
the points mentioned in 2(c/d) and 3(a/b/c) in relation to passing
animations by value.

Regards and looking forward to comments,

Gabriel

[Vadim Zeitlin]

On Wed, 1 Jun 2011 04:28:05 -0700 (PDT) Bogdan Chiciu Gabriel <***@gmail.com> wrote:

BCG> Yes i was aware of both wxAnimationBase and wxAnimation existing. The
BCG> name was picked just to better depict the idea that that is the base
BCG> class. It will be renamed to something else (I have no idea what at
BCG> this point as I'm usually picky with names, probably wxBaseAnimation).
BCG> And there should be no reason not to prefix the classes in the library
BCG> with wxAnimation (to a certain extent of course
BCG> wxAnimationKeyframeAnimation sound a bit silly).

Thinking more about the naming conventions, what about using
"wxUIAnimation" prefix for all these classes? It would be better to use
just "wxAnimation", of course, but I think the potential of confusion with
the existing (different) animation classes is too high. Also, "UI
animation" seems to describe the purpose of these classes quite nicely.
Granted, wxUIAnimationStoryboard is a bit long but OTOH this name is as
clear as possible.

FWIW another possibility would be to use wxUIAnimation namespace (in C++
sense) and call the class just Storyboard. However I am not sure if this
really would be so much better as these classes probably wouldn't be used
often enough to warrant doing "using namespace wxUIAnimation;" and without
it you'd still have to write "wxUIAnimation::Storyboard" which is 2
characters longer. And, of course, this would be rather inconsistent with
the rest of wx API. So all in all it's probably not a good idea, I'm just
leaving this paragraph here for completeness.

BCG> > 2(a) What is wxAnimationGroup (returned by wxStoryboard method of the same
BCG> >      name)? It doesn't seem to be mentioned anywhere else.
BCG>
BCG> Since we were adding animation to the storyboard I figured that having
BCG> a way to return them all could not hurt. It was not really defined so
BCG> I left it out but it could something similar to wxWindowList or
BCG> something of sorts.

I see that it's now just a list. Nothing wrong with this but personally I
always use vectors by default -- and in this particular case it looks like
a vector is a better match than a list as it seems unlikely that you'd
often need to insert elements in the middle of the animations collection.
So I'd return wxUIAnimationsVector (== wxVector<wxUIAnimationBase *>) from
here. BTW, in any case the method should be called just GetAnimations() and
neither GetAnimationList() nor GetAnimationVector(), the type of the
container returned is not important enough to include it in its name.


BCG> >  (b) Why does wxStoryboard derive from wxAnimationObject and what does the
BCG> >      latter actually do? Is it just a mix-in/interface providing the single
BCG> >      BeginAnimation() (pure virtual) method? Is wxWindow meant to derive
BCG> >      from it? If so, I don't see how is this compatible with separating the
BCG> >      animation classes in an independent library.
BCG> >
BCG> >      FWIW I don't know how useful is it to animate a single window, I've
BCG> >      never really used animations in my programs (yet) so I'm not sure how
BCG> >      often can you avoid using wxStoryboard and use this simplified API.
BCG> >      But if we do want to have it, I think we should rather provide a
BCG> >      function (or static method) in the animation library doing this rather
BCG> >      than adding a method to wxWindow itself.
BCG>
BCG> Removed the base class. Moved wxAnimationObject to a special mentions
BCG> section and added a static method that can play an animation for a
BCG> specific target as you suggested.

I'm not sure if I'm somehow viewing a wrong version but I still see the
original wxAnimationObject description. OTOH I do see the static
BeginAnimation in wxStoryboard. Anyhow, the contents of this document is
not that important, as long as we agree about the eventual contents of the
actual wx headers there is no problem.


BCG> >  (c) Will wx[Type]Animation be really differently named classes or can we
BCG> >      have just a single wxAnimatedProperty<T> template class? Which would
BCG> >      be simpler to implement? Could it be useful to have specializations of
BCG> >      such a template in user code and, if so, would this be possible to
BCG> >      implement?
BCG> >
BCG> >  (d) Maybe related to above, the relationship between wx[Type]Animation and
BCG> >      wxAnimationTargetProperty is not really clear to me. Should we really
BCG> >      have wxPointAnimation and then use it only with
BCG> >      wx_ANIMATION_TARGET_PROPERTY_POSITION (BTW, we use "wx" prefix for the
BCG> >      constants, not "wx_") or should we have wxAnimatedPositionProperty
BCG> >      instead?
BCG>
BCG> Both of these are great questions so I need further opinions on this.
BCG> All are absolutely valid propositions and could be implemented without
BCG> sacrificing ease of implementation too much.
BCG>
BCG> Off the top of my head for wxAnimatedProperty<T>/
BCG> wxAnimatedPositionProperty/wxPointAnimation I would have been inclined
BCG> to pick wxTypeAnimation/wxAnimatedProperty<T> if there were many
BCG> properties to animate with that animation type and if specifying the
BCG> property of that type animation would have been easy (implementation
BCG> wise). However wxAnimated[PropertyName]Property is again a rather
BCG> great idea since there are not that many standard properties to
BCG> animate (for wxPoint I can only think of one) so you don't end up with
BCG> a multitude of classes. Moreover wxAnimated[PropertyName]Property
BCG> could be built on top of wxAnimatedProperty<T>/wx[Type]Animation.
BCG>
BCG> My initial idea was to have type animations paired with a good way of
BCG> specifying a target property (it was specified in the document that it
BCG> still needs debating; more on this at the end of this post).

I'm not sure if you meant to write something else about it as I didn't
really find anything else in this post?

Anyhow, it looks like MSW and OSX are very different in this aspect.
Please correct me if I'm wrong but it looks like MSW only supports
animation variables of type double and it's up to you to actually do
anything with their values while OS X supports predefined layer properties
of different types and handles them automatically?

If this is correct, then it seems that we need to emulate OS X API on MSW
if only because it looks much simpler to use. And then it seems more or
less necessary to have separate classes for each (high level) animation
variable, e.g. wxUIAnimationRect, wxUIAnimationBorderColour and so on. The
templates would probably be useful in the MSW implementation though as it
could be nice to have a specialization for e.g. int variables which could
be used for both window positions and colours.



BCG> I think the user should be responsible for releasing the storyboard.

Yes, I agree, it just would need to be mentioned in the documentation of
this class (again, not necessarily in this document).

BCG> The idea is that a storyboard can be used throughout the life-time of
BCG> the application (create it once, call Begin whenever you want).
BCG> Releasing animation objects is again not so simple, a developer might
BCG> have used the same animation for a different storyboard(valid case I'd
BCG> assume)

I think it would be ok to limit any animation for the use in at most one
storyboard at the same time so don't hesitate to impose this restriction if
it's needed by the native API.

BCG> and it would be unwise to delete his animations simply because
BCG> one storyboard was no longer used. We could simply pass animations by
BCG> value since they're really simple objects with the sole purpose of
BCG> passing data to storyboards and they also hold no reference to
BCG> external objects.

They're polymorphic so passing them by value wouldn't really work (nor
storing them by value in wxStoryboard).


To summarize: the most important remaining question is that of how to deal
with the animation variables but if my description above is correct, it
seems like we don't have that much liberty here in any case. I'm also not
completely sure about how Mac implementation of this would work (MSW would
probably require more code but at least seems pretty straightforward).

In any case it would be great if you could write some relatively simple
but complete example of the proposed API (that would become the uianimation
sample in the future) to understand even better how all this would work.
And the next step would then be to start implementing it.

Regards,
VZ