Animation Controls

Animation Controls


An animation control is a window that displays an AVI clip (a series of bitmap frames, like a movie). Animation controls can only display AVI clips that do not contain audio.

arrowy.gifAbout Animation Controls

arrowy.gifUsing Animation Controls

arrowy.gifAnimation Control Reference

About Animation Controls

One common use for an animation control is to indicate system activity during a lengthy operation. This is possible because the operation thread continues executing while the AVI clip is displayed. For example, the Find dialog box of Microsoft® Windows® Explorer displays a moving magnifying glass as the system searches for a file.

An animation control can display an AVI clip originating from either an uncompressed AVI file or from an AVI file that was compressed using run-length encoding (RLE). You can add the AVI clip to your application as an AVI resource, or the clip can accompany your application as a separate AVI file.

The capabilities of the animation control are very limited and are subject to change. If you need a control to provide multimedia playback and recording capabilities for your application, you can use the MCIWnd control. For more information about the MCIWnd control, see the multimedia documentation in the Platform SDK.

Animation Control Creation

An animation control belongs to the ANIMATE_CLASS window class. You create an animation control by using the CreateWindow function or the Animate_Create macro. The macro positions the animation control in the upper-left corner of the parent window and, if the ACS_CENTER style is not specified, sets the width and height of the control based on the dimensions of a frame in the AVI clip. If ACS_CENTER is specified, Animate_Create sets the width and height of the control to zero. You can use the SetWindowPos function to set the position and size of the control.

If you create an animation control within a dialog box or from a dialog box resource, the control is automatically destroyed when the user closes the dialog box. If you create an animation control within a window, you must explicitly destroy the control.

About Animation Control Messages

An application sends messages to an animation control to open, play, stop, and close the corresponding AVI clip. Each message has one or more macros that you can use instead of sending the message explicitly.

After creating an animation control, an application sends the ACM_OPEN message to open an AVI clip and load it into memory. The message specifies either the path of an AVI file or the name of an AVI resource. The system loads the AVI resource from the module that created the animation control.

If the animation control has the ACS_AUTOPLAY style, the control begins playing the AVI clip immediately after the AVI file or AVI resource is opened. Otherwise, an application can use the ACM_PLAY message to start the AVI clip. An application can stop the clip at any time by sending the ACM_STOP message. The last frame played remains displayed when the control finishes playing the AVI clip or when ACM_STOP is sent.

An animation control can send two notification messages, ACN_START and ACN_STOP, to its parent window. Most applications do not handle either notification.

To close the AVI file or AVI resource and remove it from memory, an application can use the Animate_Close macro, which sends ACM_OPEN with the filename or resource name set to NULL.

Default Message Processing

This section describes the window messages handled by the window procedure for the ANIMATE_CLASS window class.
Message Processing performed
WM_CLOSE Frees the AVI file or AVI resource associated with the animation control.
WM_DESTROY Frees the AVI file or AVI resource, frees an internal data structure, and then calls the DefWindowProc function.
WM_ERASEBKGND Erases the window background using the current background color for static controls.
WM_NCCREATE Allocates and initializes an internal data structure and then calls DefWindowProc.
WM_NCHITTEST Returns the HTTRANSPARENT hit test value.
WM_PAINT Draws an AVI frame in the animation control.
WM_SIZE Checks if the control has the ACS_CENTER style. If the control does not, it calls DefWindowProc. Otherwise, it centers the animation in the control, invalidates the control, and then calls DefWindowProc.

Using Animation Controls

This section provides examples that demonstrate how to create an animation control and display an AVI clip in the control.

Creating an Animation Control

The following function creates an animation control in a dialog box. The animation control is positioned below the specified control, and the dimensions of the animation control are based on the dimensions of a frame in the AVI clip.

// CreateAnimationCtrl - creates an animation control, positions it 
//     below the specified control in a dialog box, and opens the AVI 
//     clip for the animation control. 
// Returns the handle to the animation control. 
// hwndDlg - handle to the dialog box. 
// nIDCtl - identifier of the control below which the animation control 
//     is to be positioned. 
// 
// Constants 
//     IDC_ANIMATE - identifier of the animation control. 
//     CX_FRAME, CY_FRAME - width and height of the frames 
//         in the AVI clip. 
HWND CreateAnimationCtrl(HWND hwndDlg, int nIDCtl) 
{ 
    HWND hwndAnim = NULL; 
    RECT rc; 
    POINT pt; 
 
    // Create the animation control. 
    hwndAnim = Animate_Create(hwndDlg, IDC_ANIMATE, 
        WS_BORDER | WS_CHILD, g_hinst); 
 
    // Get the screen coordinates of the specified control button. 
    GetWindowRect(GetDlgItem(hwndDlg, nIDCtl), &rc); 
 
    // Convert the coordinates of the lower-left corner to 
    // client coordinates. 
    pt.x = rc.left; 
    pt.y = rc.bottom; 
    ScreenToClient(hwndDlg, &pt); 
 
    // Position the animation control below the Stop button. 
    SetWindowPos(hwndAnim, 0, pt.x, pt.y + 20, 
        CX_FRAME, CY_FRAME, 
        SWP_NOZORDER | SWP_DRAWFRAME); 
 
    // Open the AVI clip, and show the animation control. 
    Animate_Open(hwndAnim, "SEARCH"); 
    ShowWindow(hwndAnim, SW_SHOW); 
 
    return hwndAnim; 
} 

Controlling the AVI Clip

The following function uses the animation control macros to control the display of the AVI clip in an animation control.

// DoAnimation - plays, stops, or closes an animation control's 
//     AVI clip, depending on the value of an action flag. 
// hwndAnim - handle to an animation control. 
// nAction - flag that determines whether to play, stop, or close 
//     the AVI clip. 
void DoAnimation(HWND hwndAnim, int nAction) 
{ 
    switch (nAction) { 
        case PLAYIT: 
 
            // Play the clip continuously starting with the 
            // first frame. 
            Animate_Play(hwndAnim, 0, -1, -1); 
            break; 
 
        case STOPIT: 
            Animate_Stop(hwndAnim); 
            break; 

        case CLOSEIT: 
            Animate_Close(hwndAnim); 
            break; 
 
        default: 
            break; 
    } 
    return; 
} 

Animation Control Reference

This section contains information about the programming elements used with animation controls.

Animation Control Styles

Messages
ACM_OPEN
ACM_PLAY
ACM_STOP

Macros
Animate_Create
Animate_Close
Animate_Open
Animate_OpenEx
Animate_Play
Animate_Seek
Animate_Stop

Notifications
ACN_START
ACN_STOP

Animation Control Styles

The following window styles are used with animation controls:

ACS_AUTOPLAY Starts playing the animation as soon as the AVI clip is opened.
ACS_CENTER Centers the animation in the animation control's window.
ACS_TIMER By default, the control creates a thread to play the AVI clip. If you set this flag, the control plays the clip without creating a thread; internally the control uses a Win32 timer to synchronize playback.
ACS_TRANSPARENT Draws the animation using a transparent background rather than the background color specified in the animation clip.

Animation Control Messages

Following are the messages that an application sends to an animation control.

ACM_OPEN
ACM_OPEN 
#if (_WIN32_IE >= 0x0400)
    wParam = (WPARAM)(HINSTANCE)hinst;
#else
    wParam = 0; 
#endif
    lParam = (LPARAM) (LPSTR) lpszName; 

Opens an AVI clip and displays its first frame in an animation control. You can send this message explicitly or use the Animate_Open or Animate_OpenEx macro.

hinst
Version 4.71. Instance handle to the module that the resource should be loaded from. If this value is NULL, the resource is loaded from the module that created the animation control.
lpszName
Address of a buffer that contains the path of the AVI file or the name of an AVI resource. Alternatively, this parameter can consist of the AVI resource identifier in the low-order word and zero in the high-order word. To create this value, use the MAKEINTRESOURCE macro. The control loads the AVI resource from the module specified by the instance handle passed to the CreateWindow function, the Animate_Create macro, or the dialog box creation function that created the control. In Version 4.71 and later, the resource is loaded from the module specified by hinst.

The AVI file or resource specified by lpszName must not contain audio.

If this parameter is NULL, the system closes the AVI file that was previously opened for the specified animation control, if any.

You can only open silent AVI clips. ACM_OPEN and Animate_Open fail if lpszSource specifies an AVI clip that contains sound.

You can use Animate_Close to close an AVI file or AVI resource that was previously opened for the specified animation control.

The Animate_Open and Animate_Close macros are defined in Commctrl.h.

ACM_PLAY
ACM_PLAY 
    wParam = (WPARAM) (UINT) cRepeat; 
    lParam = (LPARAM) MAKELONG(wFrom, wTo); 

Plays an AVI clip in an animation control. The control plays the clip in the background while the thread continues executing. You can send this message explicitly or by using the Animate_Play macro.

cRepeat
Number of times to replay the AVI clip. A value of -1 means replay the clip indefinitely.
wFrom
Zero-based index of the frame where playing begins. The value must be less than 65,536. A value of zero means begin with the first frame in the AVI clip.
wTo
Zero-based index of the frame where playing ends. The value must be less than 65,536. A value of -1 means end with the last frame in the AVI clip.

You can use Animate_Seek to direct the animation control to display a particular frame of the AVI clip.

The Animate_Play and Animate_Seek macros are defined in Commctrl.h.

ACM_STOP
ACM_STOP 
    wParam = 0; 
    lParam = 0; 

Stops playing an AVI clip in an animation control. You can send this message explicitly or by using the Animate_Stop macro.

Animation Control Macros

Following are the macros that an application can use with animation controls.

Animate_Close
BOOL Animate_Close(
    HWND hwnd
);

Closes an AVI clip and displays its first frame in an animation control. You can use this macro or send the ACM_OPEN message explicitly.

hwnd
Handle to the animation control.

You can use Animate_Close to close an AVI file or AVI resource that was previously opened for the specified animation control.

The Animate_Close macro is defined in Commctrl.h.

See also Animate_Open, MAKEINTRESOURCE

Animate_Create
HWND Animate_Create(
    HWND hwndP, 
    UINT id, 
    DWORD dwStyle, 
    HINSTANCE hInstance
);

Creates an animation control. Animate_Create calls the CreateWindow function to create the animation control.

hwndP
Handle to the parent window.
id
Child window identifier of the animation control.
dwStyle
Window styles. For a list of the animation control style values, see Animation Control Styles.
hInstance
Handle to the instance of the module that is creating the animation control.

The Animate_Create macro sets the width and height of the animation control to zero if the ACS_CENTER style is specified. If the ACS_CENTER style is not specified, Animate_Create sets the width and height based on the dimensions of a frame in the AVI clip.

Animate_Open
BOOL Animate_Open(
    HWND hwnd, 
    LPSTR lpszName
);

Opens an AVI clip and displays its first frame in an animation control. You can use this macro or send the ACM_OPEN message explicitly.

hwnd
Handle to the animation control.
lpszName
Address of a buffer that contains the path of the AVI file or the name of an AVI resource. Alternatively, this parameter can consist of the AVI resource identifier in the low-order word and zero in the high-order word. To create this value, use the MAKEINTRESOURCE macro. The control loads an AVI resource from the module specified by the instance handle passed to the CreateWindow function, the Animate_Create macro, or the dialog box creation function that created the control.

The AVI file or resource specified by lpszName must not contain audio.

If this parameter is NULL, the system closes the AVI file that was previously opened for the specified animation control, if any.

You can only open silent AVI clips. ACM_OPEN and Animate_Open will fail if lpszSource specifies an AVI clip that contains sound.

You can use Animate_Close to close an AVI file or AVI resource that was previously opened for the specified animation control.

The Animate_Open macro is defined in Commctrl.h.

Animate_OpenEx
BOOL Animate_OpenEx(
    HWND hwnd, 
    HINSTANCE hinst,
    LPSTR lpszName
);

Opens an AVI clip from a resource in a specified module and displays its first frame in an animation control. You can use this macro or send the ACM_OPEN message explicitly.

hwnd
Handle to the animation control.
hinst
Instance handle to the module that the resource should be loaded from. If this value is NULL, the resource is loaded from the module that created the animation control.
lpszName
Address of a buffer that contains the path of the AVI file or the name of an AVI resource. Alternatively, this parameter can consist of the AVI resource identifier in the low-order word and zero in the high-order word. To create this value, use the MAKEINTRESOURCE macro. The control loads the AVI resource from the module specified by hinst.

The AVI file or resource specified by lpszName must not contain audio.

If this parameter is NULL, the system closes the AVI file that was previously opened for the specified animation control, if any.

You can only open silent AVI clips. ACM_OPEN and Animate_Open will fail if lpszSource specifies an AVI clip that contains sound.

You can use Animate_Close to close an AVI file or AVI resource that was previously opened for the specified animation control.

The Animate_OpenEx macro is defined in Commctrl.h.

Version 4.71

Animate_Play
BOOL Animate_Play(
    HWND hwndAnim, 
    UINT wFrom, 
    UINT wTo, 
    UINT cRepeat
);

Plays an AVI clip in an animation control. The control plays the clip in the background while the thread continues executing. You can use this macro or send the ACM_PLAY message explicitly.

hwndAnim
Handle to the animation control in which to play the AVI clip.
wFrom
Zero-based index of the frame where playing begins. The value must be less than 65,536. A value of zero means begin with the first frame in the AVI clip.
wTo
Zero-based index of the frame where playing ends. The value must be less than 65,536. A value of -1 means end with the last frame in the AVI clip.
cRepeat
Number of times to replay the AVI clip. A value of -1 means replay the clip indefinitely.

You can use Animate_Seek to direct the animation control to display a particular frame of the AVI clip.

The Animate_Play macro is defined in Commctrl.h.

Animate_Seek
BOOL Animate_Seek(
    HWND hwndAnim, 
    UINT wFrame
);

Directs an animation control to display a particular frame of an AVI clip. The control displays the clip in the background while the thread continues executing. You can use this macro or send the ACM_PLAY message explicitly.

hwndAnim
Handle to the animation control in which to display the AVI frame.
wFrame
Zero-based index of the frame to display.

The Animate_Seek macro is defined in Commctrl.h.

See also Animate_Play

Animate_Stop
BOOL Animate_Stop(
    HWND hwnd
);

Stops playing an AVI clip in an animation control. You can use this macro or send the ACM_STOP message explicitly.

hwnd
Handle to the animation control.

The Animate_Stop macro is defined in Commctrl.h.

Animation Control Notifications

Following are the notification messages that the animation control sends to an application.

ACN_START
ACN_START 

Notifies an animation control's parent window that the associated AVI clip has started playing. This notification message is sent in the form of a WM_COMMAND message.

ACN_STOP
ACN_STOP 

Notifies an animation control's parent window that the associated AVI clip has stopped playing. This notification message is sent in the form of a WM_COMMAND message.

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.