Gnome User Interface Library Reference Manual
<<< Previous Page | Home | Up | Next Page >>>

# GnomeAnimator

## Name

GnomeAnimator -- A widget for adding simple animations to GNOME applications.

## Synopsis

    #include <gnome.h>

    struct      GnomeAnimator;
    enum        GnomeAnimatorStatus;
    enum        GnomeAnimatorLoopType;
    struct      GnomeAnimatorFrame;
    struct      GnomeAnimatorPrivate;
    GtkWidget*  gnome_animator_new_with_size    (guint width,
                                                 guint height);
    void        gnome_animator_set_loop_type    (GnomeAnimator *animator,
                                                 GnomeAnimatorLoopType loop_type);
    GnomeAnimatorLoopType gnome_animator_get_loop_type
                                                (GnomeAnimator *animator);
    void        gnome_animator_set_playback_direction
                                                (GnomeAnimator *animator,
                                                 gint playback_direction);
    gint        gnome_animator_get_playback_direction
                                                (GnomeAnimator *animator);
    gboolean    gnome_animator_append_frame_from_imlib_at_size
                                                (GnomeAnimator *animator,
                                                 GdkImlibImage *image,
                                                 gint x_offset,
                                                 gint y_offset,
                                                 guint32 interval,
                                                 guint width,
                                                 guint height);
    gboolean    gnome_animator_append_frame_from_imlib
                                                (GnomeAnimator *animator,
                                                 GdkImlibImage *image,
                                                 gint x_offset,
                                                 gint y_offset,
                                                 guint32 interval);
    gboolean    gnome_animator_append_frame_from_file_at_size
                                                (GnomeAnimator *animator,
                                                 const gchar *name,
                                                 gint x_offset,
                                                 gint y_offset,
                                                 guint32 interval,
                                                 guint width,
                                                 guint height);
    gboolean    gnome_animator_append_frame_from_file
                                                (GnomeAnimator *animator,
                                                 const gchar *name,
                                                 gint x_offset,
                                                 gint y_offset,
                                                 guint32 interval);
    gboolean    gnome_animator_append_frames_from_imlib_at_size
                                                (GnomeAnimator *animator,
                                                 GdkImlibImage *image,
                                                 gint x_offset,
                                                 gint y_offset,
                                                 guint32 interval,
                                                 gint x_unit,
                                                 guint width,
                                                 guint height);
    gboolean    gnome_animator_append_frames_from_imlib
                                                (GnomeAnimator *animator,
                                                 GdkImlibImage *image,
                                                 gint x_offset,
                                                 gint y_offset,
                                                 guint32 interval,
                                                 gint x_unit);
    gboolean    gnome_animator_append_frames_from_file_at_size
                                                (GnomeAnimator *animator,
                                                 const gchar *name,
                                                 gint x_offset,
                                                 gint y_offset,
                                                 guint32 interval,
                                                 gint x_unit,
                                                 guint width,
                                                 guint height);
    gboolean    gnome_animator_append_frames_from_file
                                                (GnomeAnimator *animator,
                                                 const gchar *name,
                                                 gint x_offset,
                                                 gint y_offset,
                                                 guint32 interval,
                                                 gint x_unit);
    gboolean    gnome_animator_append_frame_from_gnome_pixmap
                                                (GnomeAnimator *animator,
                                                 GnomePixmap *pixmap,
                                                 gint x_offset,
                                                 gint y_offset,
                                                 guint32 interval);
    void        gnome_animator_start            (GnomeAnimator *animator);
    void        gnome_animator_stop             (GnomeAnimator *animator);
    gboolean    gnome_animator_advance          (GnomeAnimator *animator,
                                                 gint num);
    void        gnome_animator_goto_frame       (GnomeAnimator *animator,
                                                 guint frame_number);
    guint       gnome_animator_get_current_frame_number
                                                (GnomeAnimator *animator);
    GnomeAnimatorStatus gnome_animator_get_status
                                                (GnomeAnimator *animator);
    void        gnome_animator_set_playback_speed
                                                (GnomeAnimator *animator,
                                                 gdouble speed);
    gdouble     gnome_animator_get_playback_speed
                                                (GnomeAnimator *animator);

## Object Hierarchy

      GtkObject
       +----GtkWidget
             +----GnomeAnimator

## Description

GnomeAnimator is a widget that is able to play simple animations in the GTK+ event loop.

## Details

### struct GnomeAnimator

    struct GnomeAnimator;

### enum GnomeAnimatorStatus

    typedef enum
    {
        GNOME_ANIMATOR_STATUS_STOPPED,
        GNOME_ANIMATOR_STATUS_RUNNING
    } GnomeAnimatorStatus;

This enumeration is used to determine if the animator object is running or not. Use `gnome_animator_get_status()` to retrieve it.

- `GNOME_ANIMATOR_STATUS_STOPPED`: The value used when the GnomeAnimator object is not running.

- `GNOME_ANIMATOR_STATUS_RUNNING`: The value used when the GnomeAnimator object is running.

### enum GnomeAnimatorLoopType

    typedef enum
    {
        /* No loop: after the last (first) frame is played, the animation
           is stopped.  */
        GNOME_ANIMATOR_LOOP_NONE,

        /* After the last (first) frame is played, restart from the first
           (last) frame.  */
        GNOME_ANIMATOR_LOOP_RESTART,

        /* After the last (first) frame is played, the playback direction
           is reversed.  */
        GNOME_ANIMATOR_LOOP_PING_PONG
    } GnomeAnimatorLoopType;

This enumeration is used to set the type of animation loop desired in the GnomeAnimator object.

- `GNOME_ANIMATOR_LOOP_NONE`: Do not use a loop in the animation. When the animation is played, it will not repeat when it is completed.

- `GNOME_ANIMATOR_LOOP_RESTART`: After the animation is played, loop back to the beginning of the animation and replay it. If the animation is playing forward, the loop will return to the first frame; if it is being played backward, the loop will return to the last frame in the sequence.

- `GNOME_ANIMATOR_LOOP_PING_PONG`: When the animation sequence is completed, the playback direction is reversed.

### struct GnomeAnimatorFrame

    struct GnomeAnimatorFrame;

### struct GnomeAnimatorPrivate

    struct GnomeAnimatorPrivate;

### gnome_animator_new_with_size ()

    GtkWidget*  gnome_animator_new_with_size    (guint width,
                                                 guint height);

Creates a new animator widget of the specified size.

Create a GnomeAnimator object of the specified size.

`width` : | pixel width of animator widget
`height` : | pixel height of animator widget
Returns : | Pointer to new animator widget.

### gnome_animator_set_loop_type ()

    void        gnome_animator_set_loop_type    (GnomeAnimator *animator,
                                                 GnomeAnimatorLoopType loop_type);

Sets desired animation loop type. Available loop types are `GNOME_ANIMATOR_LOOP_NONE` (play animation once only), `GNOME_ANIMATOR_LOOP_RESTART` (play animation over and over again), and `GNOME_ANIMATOR_LOOP_PING_PONG` (play animation over and over again, reversing the playing direction every time.)

Sets the type of loop the animator will use.

`animator` : | Animator widget to be updated
`loop_type` : | Type of animation loop desired

### gnome_animator_get_loop_type ()

    GnomeAnimatorLoopType gnome_animator_get_loop_type
                                                (GnomeAnimator *animator);

Obtains current animator loop type. Available loop types are `GNOME_ANIMATOR_LOOP_NONE` (play animation once only), `GNOME_ANIMATOR_LOOP_RESTART` (play animation over and over again), and `GNOME_ANIMATOR_LOOP_PING_PONG` (play animation over and over again, reversing the playing direction every time.)

Determine the type of loop being used on the animator object.

`animator` : | Animator widget to be queried
Returns : | Loop type.

### gnome_animator_set_playback_direction ()

    void        gnome_animator_set_playback_direction
                                                (GnomeAnimator *animator,
                                                 gint playback_direction);

Sets direction (forwards or backwards) to play the animation. If `playback_direction` is a positive number, the animation is played from the first to the last frame. If `playback_direction` is negative, the animation is played from the last to the first frame.

Set the direction the animation should be played back. Setting a positive value will cause the animator to play forward; a negative value will cause it to play backward.

`animator` : | Animator widget to be updated
`playback_direction` : | Direction animation should be played.

### gnome_animator_get_playback_direction ()

    gint        gnome_animator_get_playback_direction
                                                (GnomeAnimator *animator);

Returns the current playing direction (forwards or backwards) for the animation. If the returned value is a positive number, the animation is played from the first to the last frame. If it is negative, the animation is played from the last to the first frame.

Determines the direction of playback.

`animator` : | Animator widget to be updated
Returns : | Positive or negative number indicating direction.

### gnome_animator_append_frame_from_imlib_at_size ()

    gboolean    gnome_animator_append_frame_from_imlib_at_size
                                                (GnomeAnimator *animator,
                                                 GdkImlibImage *image,
                                                 gint x_offset,
                                                 gint y_offset,
                                                 guint32 interval,
                                                 guint width,
                                                 guint height);

Adds frame contained within a &GdkImlibImage image at the end of the current animation. If `width` and `height` are different from the actual `image` size, the image is scaled proportionally. The frame display interval is `interval` is divided by the playback speed.

Append a frame from a GdkImlibImage to the GnomeAnimator object and render it.

`animator` : | Animator widget to be updated
`image` : | Image to be added to animator
`x_offset` : | horizontal offset of frame within animator widget
`y_offset` : | vertical offset of frame within animator widget
`interval` : | Number of milliseconds to delay before showing next frame
`width` : | pixel width of frame
`height` : | pixel height of frame
Returns : | `TRUE` if append succeeded.

### gnome_animator_append_frame_from_imlib ()

    gboolean    gnome_animator_append_frame_from_imlib
                                                (GnomeAnimator *animator,
                                                 GdkImlibImage *image,
                                                 gint x_offset,
                                                 gint y_offset,
                                                 guint32 interval);

Adds frame contained within a &GdkImlibImage image at the end of the current animation. The frame display interval is `interval` is divided by the playback speed.

Adds frame contained within a GdkImlibImage image at the end of the current animation. The frame display interval is divided by the playback speed.

`animator` : | Animator widget to be updated
`image` : | Image to be added to animator
`x_offset` : | horizontal offset of frame within animator widget
`y_offset` : | vertical offset of frame within animator widget
`interval` : | Number of milliseconds to delay before showing next frame
Returns : | `TRUE` if append succeeded.

### gnome_animator_append_frame_from_file_at_size ()

    gboolean    gnome_animator_append_frame_from_file_at_size
                                                (GnomeAnimator *animator,
                                                 const gchar *name,
                                                 gint x_offset,
                                                 gint y_offset,
                                                 guint32 interval,
                                                 guint width,
                                                 guint height);

Adds frame from the given file to the end of the current animation. If `width` and `height` are different from the actual `image` size, the image is scaled proportionally. The frame display interval is `interval` divided by the playback speed.

Appends a frame from a file to a GnomeAnimator widget. If the specified width and height variables are different from the actual size of the image, it is scaled proportionally. The frame display interval is `interval` divided by the playback speed.

`animator` : | Animator widget to be updated
`name` : | File path of image to be added to animator
`x_offset` : | horizontal offset of frame within animator widget
`y_offset` : | vertical offset of frame within animator widget
`interval` : | Number of milliseconds to delay before showing next frame
`width` : | pixel width of frame
`height` : | pixel height of frame
Returns : | `TRUE` if append succeeded.

### gnome_animator_append_frame_from_file ()

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

Adds frame from the given file to the end of the current animation. The frame display interval is `interval` divided by the playback speed.

Append a frame from a given file to a GnomeAnimator widget. The frame display interval is `interval` divided by the playback speed.

`animator` : | Animator widget to be updated
`name` : | File path of image to be added to animator
`x_offset` : | horizontal offset of frame within animator widget
`y_offset` : | vertical offset of frame within animator widget
`interval` : | Number of milliseconds to delay before showing next frame
Returns : | `TRUE` if append succeeded.

### gnome_animator_append_frames_from_imlib_at_size ()

    gboolean    gnome_animator_append_frames_from_imlib_at_size
                                                (GnomeAnimator *animator,
                                                 GdkImlibImage *image,
                                                 gint x_offset,
                                                 gint y_offset,
                                                 guint32 interval,
                                                 gint x_unit,
                                                 guint width,
                                                 guint height);

Adds multiple frames contained within a &GdkImlibImage image at the end of the current animation. Each frame within the image should be next to one another in a single, horizontal row. If `width` and `height` are different from the actual frame size, the image is scaled proportionally. The frame display interval is `interval` divided by the playback speed.

Appends multiple frames contained within a GdkImlibImage image to a GnomeAnimator widget. Each frame within the image should be next to one another in a single, horizontal row. If `width` and/or `height` are different from the actual size of the frame, the image will be scaled proportionally. The frame display interval is `interval` divided by the playback speed.

`animator` : | Animator widget to be updated
`image` : | Image containing frames to be added to animator
`x_offset` : | horizontal offset of a frame within animator widget
`y_offset` : | vertical offset of a frame within animator widget
`interval` : | Number of milliseconds to delay before showing next frame
`x_unit` : | pixel width of a single frame
`width` : | pixel width of frame
`height` : | pixel height of frame
Returns : | `TRUE` if append succeeded.

### gnome_animator_append_frames_from_imlib ()

    gboolean    gnome_animator_append_frames_from_imlib
                                                (GnomeAnimator *animator,
                                                 GdkImlibImage *image,
                                                 gint x_offset,
                                                 gint y_offset,
                                                 guint32 interval,
                                                 gint x_unit);

Adds multiple frames contained within a &GdkImlibImage image to the end of the current animation. Each frame within the image should be next to one another in a single, horizontal row. The frame display interval is `interval` divided by the playbackspeed.

Append multiple frames contained within a GdkImlibImage image to the end of a GnomeAnimator widget. Each frame within the image should be next to one another in a single, horizontal row. The frame display interval is `interval` divided by the playback speed.

`animator` : | Animator widget to be updated
`image` : | Image containing frames to be added to animator
`x_offset` : | horizontal offset of a frame within animator widget
`y_offset` : | vertical offset of a frame within animator widget
`interval` : | Number of milliseconds to delay before showing next frame
`x_unit` : | pixel width of a single frame
Returns : | `TRUE` if append succeeded.

### gnome_animator_append_frames_from_file_at_size ()

    gboolean    gnome_animator_append_frames_from_file_at_size
                                                (GnomeAnimator *animator,
                                                 const gchar *name,
                                                 gint x_offset,
                                                 gint y_offset,
                                                 guint32 interval,
                                                 gint x_unit,
                                                 guint width,
                                                 guint height);

Adds multiple frames contained within a single image file to the end of the current animation. Each frame within the image should be next to one another in a single, horizontal row. If `width` and `height` are different from the actual frame size, the image is scaled proportionally. The frame display interval is `interval` divided by the playback speed.

Load and render an image containing multiple frames, and append those frames to the animator widget. Each frame within the image should be next to one another in a single, horizontal row. If `width` and/or `height` are different from the actual frame size, the image is scaled proportionally. The frame display interval is `interval` divided by the playback speed.

`animator` : | Animator widget to be updated
`name` : | File path to image containing frames to be added to animator
`x_offset` : | horizontal offset of a frame within animator widget
`y_offset` : | vertical offset of a frame within animator widget
`interval` : | Number of milliseconds to delay before showing next frame
`x_unit` : | pixel width of a single frame
`width` : | pixel width of frame
`height` : | pixel height of frame
Returns : | `TRUE` if append succeeded.

### gnome_animator_append_frames_from_file ()

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

Adds multiple frames contained within a single image file to the end of the current animation. Each frame within the image should be next to one another in a single, horizontal row. The frame display interval is `interval` divided by the playback_speed.

Load and render an image containing multiple frames, and append those frames to the animator widget. Each frame within the image should be next to one another in a single, horizontal row. The frame display interval is `interval` divided by the playback speed.

`animator` : | Animator widget to be updated
`name` : | File path to image containing frames to be added to animator
`x_offset` : | horizontal offset of a frame within animator widget
`y_offset` : | vertical offset of a frame within animator widget
`interval` : | Number of milliseconds to delay before showing next frame
`x_unit` : | pixel width of a single frame
Returns : | `TRUE` if append succeeded.

### gnome_animator_append_frame_from_gnome_pixmap ()

    gboolean    gnome_animator_append_frame_from_gnome_pixmap
                                                (GnomeAnimator *animator,
                                                 GnomePixmap *pixmap,
                                                 gint x_offset,
                                                 gint y_offset,
                                                 guint32 interval);

Adds frame contained within a &GnomePixmap image to the end of the current animation. The frame display interval is `interval` divided by the playback speed.

Appends a frame from a GnomePixmap image to the animator widget. The frame display interval is `interval` divided by the playback speed.

`animator` : | Animator widget to be updated
`pixmap` : | GNOME pixmap to be added to animator
`x_offset` : | horizontal offset of frame within animator widget
`y_offset` : | vertical offset of frame within animator widget
`interval` : | Number of milliseconds to delay before showing next frame
Returns : | `TRUE` if append succeeded.

### gnome_animator_start ()

    void        gnome_animator_start            (GnomeAnimator *animator);

Initiate display of animated frames.

Begin animating the widget.

`animator` : | Animator widget to be started

### gnome_animator_stop ()

    void        gnome_animator_stop             (GnomeAnimator *animator);

Halts display of animated frames. The current frame in the animation will remain in the animator widget.

Stop an animator that is running.

`animator` : | Animator widget to be stopped

### gnome_animator_advance ()

    gboolean    gnome_animator_advance          (GnomeAnimator *animator,
                                                 gint num);

Advance the animator `num` frames. If `num` is positive, use the specified `playback_direction`; if it is negative, go in the opposite direction. After the call, the animator is in the same state it would be if it had actually executed the specified number of iterations.

Advance the animator widget `num` frames. If `num` is positive, use the specified `playback_direction`; if it is negative, go in the opposite direction. After the call, the animator is in the same state it would be if it had actually executed the sppecified number of iterations.

`animator` : | Animator widget to be updated
`num` : | Number of frames to advance by
Returns : | `TRUE` if the animator is now stopped.

### gnome_animator_goto_frame ()

    void        gnome_animator_goto_frame       (GnomeAnimator *animator,
                                                 guint frame_number);

Jump to the specified `frame_number` and display it.

Jump to the specified frame. If `num_frame` is greater than the total number of frames, no action is taken.

`animator` : | Animator widget to be updated
`num_frame` : | Frame number to be made current.

### gnome_animator_get_current_frame_number ()

    guint       gnome_animator_get_current_frame_number
                                                (GnomeAnimator *animator);

Obtains current frame number from animator widget.

Determine the current frame number of the animator widget.

`animator` : | Animator widget to be queried
Returns : | Current frame number.

### gnome_animator_get_status ()

    GnomeAnimatorStatus gnome_animator_get_status
                                                (GnomeAnimator *animator);

Obtains current status from animator widget. Possible return values include `GNOME_ANIMATOR_STATUS_STOPPED` and `GNOME_ANIMATOR_STATUS_RUNNING`.

Obtain the current status from the animator widget.

`animator` : | Animator widget to be queried
Returns : | Status constant.

### gnome_animator_set_playback_speed ()

    void        gnome_animator_set_playback_speed
                                                (GnomeAnimator *animator,
                                                 gdouble speed);

Sets the playback speed. The delay between every frame is divided by this value before being used. As a consequence, higher values give higher playback speeds.

Sets the playback speed. The delay between every frame is divided by this value before being used. As a consequence, higher values give higher playback speeds.

`animator` : | Animator widget to be updated
`speed` : | Rate multiplier for playback speed

### gnome_animator_get_playback_speed ()

    gdouble     gnome_animator_get_playback_speed
                                                (GnomeAnimator *animator);

Returns the current playback speed.

Obtain the current playback speed.

`animator` : | Animator widget to be queried
Returns : | &double indicating the playback speed.

<<< Previous Page | Home | Up | Next Page >>>
GnomeAbout | GnomeApp