Resource animations

by Kent Reisdorph

The VCL's TAnimate component provides an easy way of adding animations (AVIs) to your applications. Animations are normally played when some process is taking place in your application. With TAnimate it’s very easy to play an animation from a file on disk. You may, however, want to store your animations in your EXE file rather than lug around a number of animation files. This article will explain how to create and implement an AVI file as a resource.

Creating and playing an animation contained as a resource requires the following steps:

• Create a resource script (RC) file

• Add the RC file to your project

• Write code to play the AVI

I will explain these steps in turn.

Create a resource script file

The first step is to create a resource script file. A resource script file is nothing more than a text file with an extension of .RC. You can create the RC file with any text editor. The C++Builder text editor works fine for this purpose. Simply choose File|New from the C++Builder main menu to invoke the Object Repository and double-click on the Text icon. C++Builder will create a new text file in the Code Editor.

Now that you have a new text file, you need to enter the command that will take an AVI file on disk and turn it into a resource. This part is remarkably simple. Simply type a line similar to this in the blank text file:

MyAvi AVI "some.avi" 

The first parameter on this line is the name or numeric identifier of the resource. If you type a textual name, the parameter will be interpreted as a resource name. If you enter a numeric value, the parameter will be interpreted as a numeric identifier for the resource. For example:

100 AVI "some.avi" 

You will need to know whether the resource is identified by a resource name or a resource ID when you play the AVI (more on that later).

The second parameter of the resource statement is the type of resource. C++Builder’s built in resource compiler understands the type AVI as an AVI resource so that’s what you type for the second parameter.

The final parameter is the filename that contains the AVI itself. You must have an AVI file on disk before you can convert the AVI into a resource. You can enter the filename with or without double quotes.

That’s all there is to creating the resource script file. If you have more than one AVI resource, you should add a line for each AVI you want linked to the application. When you are done, save the file with an extension of .RC. Be sure you change the Save dialog’s file filter from “Text file” to “Any file” or you will end up with a filename like MYFILE.RC.TXT.

Note: You have several choices when it comes to creating animations. Corel Draw has an animation editor, as do other commercial drawing packages. Search the Web for other animation editing programs. Note that AVIs created for use with the TAnimate component must not contain audio and must be either uncompressed, or RLE compressed only. Any other format will cause the TAnimate component to raise an exception at runtime when you attempt to play the animation.

Add the RC file to the project

After you have created and saved the resource script file, you can add it to your project using Project | Add to Project on the main menu. The RC file will be compiled the next time you make or build the project.

The resource compiler will report any errors that occur during the compile. If you encounter errors go back and check your RC file for errors. If the resource compiler successfully compiles the resource script, you will end up with a binary resource file. The binary resource file has the same name as the resource script file but with an extension of .RES. This file will automatically be bound to the executable during the link phase of a make or build.

Writing code to play the AVI

Next you need to write code to play the AVI. When you play an AVI from a file, you simply set the FileName property to the name of an AVI file, and then set Active to True. When you play an animation contained as a resource, however, you need to use the ResHandle, ResName, and ResId properties.

The ResHandle property is used to specify the handle of the module that contains the AVI resource. If you have bound the AVI resource to your executable file, you should set ResHandle to 0. (In theory you should be able to set the ResHandle property to the global HInstance variable. For some inexplicable reason, this results in an exception at run time when you attempt to load the AVI resource.) If your animations were contained in a DLL, you would set ResHandle to the instance handle of the DLL (obtained with the Windows API function, LoadLibrary()).

Next, set either the ResName or ResId property to the name or resource ID of the AVI resource you wish to play. Use ResName if your AVI resource is specified as a text resource name. Use ResId if your resource is specified with a numeric value. By the way, the VCL help incorrectly lists this property as ResID where it is actually ResId (note that the upper case “D” is incorrect).

To play the resource, set the Active property to true. Alternatively, you can use the Play() method to play the animation. The Play() method gives you more control over animation playback although it’s slightly more complicated to use.

The following code snippet illustrates playing an AVI resource created with a resource name and bound the application’s executable file:

Animate->ResHandle = 0;
Animate->ResName = "TurboGuy";
Animate->Active = true;

To stop the animation, call the Stop() method.

Prove it!

Listing A contains the main unit of a program that plays an AVI video contained as a resource. Listing B contains the resource script file used to create the binary resource used in the example program. The program’s main form contains a TAnimate component, a Play button, and a Stop button. Figure A shows the application playing the TurboPower “TurboMan” AVI (TurboMan is the AVI that plays when TurboPower’s Memory Sleuth starts running an application). The example program can be downloaded from our Web site.

Figure A

The example program playing a resource AVI.

Listing A: AviRes.cpp

#include <vcl.h>
#pragma hdrstop

#include "MainU.h"

#pragma package(smart_init)
#pragma resource "*.dfm"
TForm1 *Form1;

__fastcall TForm1::TForm1(TComponent* Owner)
  : TForm(Owner)
{
}

void __fastcall TForm1::PlayBtnClick(
  TObject *Sender)
{
  Animate->ResHandle = 0;
  Animate->ResName = "TurboGuy";
  Animate->Active = true;
  PlayBtn->Enabled = false;
  StopBtn->Enabled = true;
}

void __fastcall TForm1::StopBtnClick(
  TObject *Sender)
{
  Animate->Stop();
  PlayBtn->Enabled = true;
  StopBtn->Enabled = false;
}

Listing B: AviResrc.rc

TurboGuy AVI "Start5c.avi"