GnomeAnimator widget

[Ettore Perazzoli <ettore comm2000 it>]

Hi!

As I announced a few mails ago, I have made a first attempt at a
`GnomeAnimator' widget.  I sent the widget to Federico for a comment,
and he asked me to send the API to the list, to see what people
think.

The widget allows any application to load a sequence of frames and
have them played automagically in the GTK event loop, without further
intervention.  Every frame is defined by the following parameters:

  - a pixmap;

  - and a bitmap mask, in case the shape is not rectangular;

  - x/y offset values, for placing the pixmap anywhere in the widget
    (having frame-specific x/y offset values makes it possible to
    create animations by moving a single pixmap around);;

  - an interval value in milliseconds.

Animations can be played forwards or backwards, in three ways, defined
by a `GnomeAnimatorLoopType' typedef:

  - `GNOME_ANIMATOR_LOOP_NONE': just play the sequence in the
    specified direction once;

  - `GNOME_ANIMATOR_LOOP_RESTART': restart from the first frame after
    playing the last frame of the sequence;

  - `GNOME_ANIMATOR_LOOP_PING_PONG': after reaching the last frame of
    the sequence, invert the playback direction.

The API is not completely decided yet, but this is what it can do so
far:

  - GtkWidget *gnome_animator_new_with_size (guint width, guint
    height)

    Create a new `GnomeAnimator' of the specified size;

  - void gnome_animator_set_loop_type (GnomeAnimator *animator,
      GnomeAnimatorLoopType loop_type)

    Set the loop type to `loop_type';

  - void gnome_animator_set_playback_direction (GnomeAnimator
      *animator, gint playback_direction)
  - gint gnome_animator_get_playback_direction (GnomeAnimator
      *animator)

    Set/get the playback direction (positive means "forwards",
    negative means "backwards").

  - void gnome_animator_set_loop_count (GnomeAnimator *animator,
      guint loop_count)
  - guint gnome_animator_get_loop_count (GnomeAnimator *animator)

    Set/get the loop count (number of times the animation is played
    when either `GNOME_ANIMATOR_LOOP_PING_PONG' or
    `GNOME_ANIMATOR_LOOP_RESTART' is the loop type).

  - gboolean gnome_animator_add_frame_from_file (GnomeAnimator
      *animator, const gchar *name, gint x_offset, gint y_offset,
      guint32 interval);

    Load pixmap named `name' via Imlib and add it to the sequence
    with the specified X/Y offsets and interval.  Return `TRUE' if
    successful.

  - gboolean gnome_animator_add_frames_from_file (GnomeAnimator
      *animator, const gchar *name, gint x_offset, gint y_offset,
      guint32 interval, gint x_unit)

    Load a pixmap named `name' via Imlib, split it vertically into
    frames of width `x_unit' and finally add the frames to the
    `GnomeAnimator' with the specified X/Y offset and interval (which
    are kept constant throughout the animation); return `TRUE' if
    successful.  This makes it easy to make simple animations out of a
    single, wide pixmap.

    (Maybe we should add support in Imlib to make it easier to handle
    such cases?)

  - void gnome_animator_start (GnomeAnimator *animator, guint
      frame_num, gint playback_direction)

    Start playing the `GnomeAnimator' from frame `frame_num' in the
    specified direction.

    (I don't like this, as it duplicates functionality.  It would
    probably be better to replace this with a simple
    `gnome_animator_start (GnomeAnimator *animator)'.)

  - void gnome_animator_stop (GnomeAnimator *animator)

    Stop playing the `GnomeAnimator'.

  - void gnome_animator_set_current_frame (GnomeAnimator *animator,
      guint num_frame)

    Make the `GnomeAnimator' jump to the specified frame.

  - guint gnome_animator_get_current_frame (GnomeAnimator *animator)

    Get the number of the current frame being displayed.

  - void_animator_get_status (GnomeAnimator *animator,
      GnomeAnimatorStatus status)
  - GnomeAnimatorStatus gnome_animator_get_status (GnomeAnimator
      *animator)

    Set/get the current status (`GnomeAnimatorStatus' is just an enum
    which can be either `GNOME_ANIMATOR_STATUS_STOPPED' or
    `GNOME_ANIMATOR_STATUS_RUNNING').

(Of course, some other `gnome_animator_add_frame_from*()' methods
should be added.)

With this API, it becomes quite easy to add an animation anywhere.
You just have to instantiate the widget like you would do with a
Pixmap, add some images to it, and then let it run with
`gnome_animator_start()'.  As the animation is done through the GTK
event loop, you can add as many independent animations as possible.

Any comments?  I would also like to know how this could be integrated
with `GnomePixmap' and `GnomeStock*'...

--
Ettore