Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: add useDuration helper #226

Merged
merged 2 commits into from
Feb 7, 2023
Merged

feat: add useDuration helper #226

merged 2 commits into from
Feb 7, 2023

Conversation

Tandashi
Copy link
Contributor

@Tandashi Tandashi commented Feb 6, 2023

What has changed?

This Pull Request adds a new helper / utility function that allows for easier creation and usage of TimeEvents for animations.

Furthermore, the documentation has been extended and now features a subsection ("Controlling animation duration with Time Events") under the Time Events chapter.

Closes: #171


Example

Let's look at the following example where we want to animate the scale of a circle:

import {makeScene2D} from '@motion-canvas/2d';
import {Circle} from '@motion-canvas/2d/lib/components';
import {createRef, useScene} from '@motion-canvas/core/lib/utils';

export default makeScene2D(function* (view) {
  const circle = createRef<Circle>();

  view.add(
    <Circle ref={circle} width={320} height={320} fill={'lightseagreen'} />,
  );

  useScene().timeEvents.register('event');
  const duration = useScene().timeEvents.get('event').offset;
  yield* circle().scale(2, duration);
});

In the example a TimeEvent called event is registered and its duration gets used to control
the duration of the circle's scale animation.

With the new useDuration function, this can be reduced to a single line of code as follows:

yield* circle().scale(2, useDuration('event'));

packages/core/src/utils/useDuration.ts Show resolved Hide resolved
Comment on lines 60 to 75
```ts
useScene().timeEvents.register('event')
```

This registers a Time Event called `event`.
Then we can grab the duration of said event as follows:

```ts
const duration = useScene().timeEvents.get('event').offset;
```

And finally we can use this `duration` to animate the circle:

```ts
yield* circle().scale(2, duration);
```
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is an internal implementation detail, I don't think we should include it in the docs.
I'd simply say:

Aside from specifying _when_ something should happen, time events can be used to 
control _how long_ something should last. You can use the 
[`useDuration`](/api/core/utils#useDuration) function to retrieve the duration of an event
and use it in your animation:

```ts
yield* circle().scale(2, useDuration('event'));
```

@@ -48,3 +48,36 @@ it. This is useful when you want to extend or shorten a pause in your voiceover
because correcting the first time event after the pause will also fix all events
after it. You can hold `SHIFT` when editing an event to prevent this from
happening.

## Controlling animation duration with Time Events
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The entire section is about time events so I think it could be just:

Suggested change
## Controlling animation duration with Time Events
## Controlling animation duration

Adding a `useDuration` helper function to easily
create a `TimeEvent` and use it to control an
animation.

Issue: #171
Added a sub-section for the new `useDuration`
function in the `Time Events` chapter.

Issue: #171
@aarthificial aarthificial merged commit fa97d6c into motion-canvas:main Feb 7, 2023
@aarthificial
Copy link
Contributor

Thanks for the PR!

@Tandashi Tandashi deleted the feature/#171/useDuration branch February 7, 2023 11:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Use time events for duration
2 participants