=head1 NAME

Clutter::Cookbook - Examples of how to use Clutter

=head1 DESCRIPTION

This document tries to provide examples on how to perform some common tasks
when building an application or a toolkit using the Clutter Perl bindings.

The original version of this document can be found on the Clutter project
main site; the online version is aimed at the C API.

=head1 ACTORS

=head2 Maintaining the aspect ratio when loading a texture

L<Clutter::Texture> already provides a property that maintains the aspect
ratio of an image loaded on a texture:

  Clutter::Texture:keep-aspect-ratio
    type: boolean
    default: FALSE

Usually, you just need to set it to TRUE before setting the image data:

  $texture = Clutter::Texture->new();
  $texture->set(keep_aspect_ratio => TRUE);
  $texture->set_from_file($filename);
  $texture->set_width(100);

This will set up a texture with the contents of I<filename>, a width of
100 pixels and an height maintaining the same aspect ratio of the original
image.

L<Clutter::Texture>, like the rest of Clutter's actors, is a
I<height-for-width actor>. This means that the width will be queried first
and then the height set for the given width. If you need to set the height
of a texture and maintain the same aspect ratio, you will need to change
the texture to be a I<width-for-height> actor instead, by using this
property:

  Clutter::Actor:request-mode
    type: Clutter::RequestMode
    default: CLUTTER_REQUEST_HEIGHT_FOR_WIDTH

And then setting the height for the actor:

  $texture = Clutter::Texture->new();
  $texture->set(
      keep_aspect_ratio => TRUE,
      request_mode      => 'width-for-height',
  );
  $texture->set_from_file($filename);
  $texture->set_height(100);

This will set up a texture with the contents of I<filename>, a height
of 100 pixels and a width maintaining the same aspect ratio of the
original image.

=head1 ANIMATIONS

=head2 Inverting animations

If an animation is composed by two identical parts with the latter part
"flipping" the animation of the former one, e.g.:

                        / scale from 2.0 to 1.0
  begin                /
  +--------------------|--------------------+------> time
  \                                         end
   \ scale from 1.0 to 2.0

Instead of using two different effects or two different behaviours you might
simply use the

  Clutter::Timeline:direction
    type: Clutter::TimelineDirection
    default: CLUTTER_TIMELINE_FORWARD

Property of L<Clutter::Timeline>. Set up the I<timeline> duration to be the
exact half of the overall animation and connect a callback to the

  Clutter::Timeline::completed

Signal and change the I<direction> property; you will also need to rewind the
I<timeline> so that the state is reset at the right frame number:

  $timeline = Clutter::Timeline->new();
  $timeline->set_duration(250); # 250 msecs
  $timeline->signal_connect(completed => sub {
      $timeline->set_direction('backward');
      $timeline->rewind();
      $timeline->start();
  });

When the I<timeline> is complete it will be restarted from the end and go
backward to the start. Any L<Clutter::Behaviour> attached to the I<timeline>
will be reversed as well, giving you the desired effect.

=head1 AUTHOR

Emmanuele Bassi E<lt>ebassi@linux.intel.comE<gt>

=head1 COPYRIGHT

Copyright (C) 2008 Intel Corporation

=head1 SEE ALSO

L<perl>(1), L<Clutter>(3pm)

=cut