sswf::TagHeader Class Reference

The header or root of the SWF movie. More...

#include <libsswf.h>

Inheritance diagram for sswf::TagHeader:


Public Member Functions
ErrorManager::error_code_t	DefineMinimumVersion (int &min_version)
	Define the minimum SWF version required for a successful Save().
const SRectangle &	Frame (void) const
	Retrieve the current frame sizes.
virtual void	MinimumVersion (unsigned char version)
	Defines what the minimum version shall be to save this movie.
sswf_id_t	NextID (void)
	Get the next unique identifier.
virtual ErrorManager::error_code_t	OnError (ErrorManager::error_code_t errcode, const char *message,...) const
	Call the error manager OnError() function.
virtual ErrorManager::error_code_t	OnError (ErrorManager::error_code_t errcode, const char *message, va_list ap) const
	Call the error manager OnError() function.
float	Rate (void) const
	Set the speed at which the frames are to be played.
void	RemoveID (sswf_id_t id)
	Release an identifier previously allocated with NextID.
virtual ErrorManager::error_code_t	Save (Data &data)
	Save the movie in a Data buffer.
ErrorManager::error_code_t	SaveEncodedString (Data &data, const char *string)
	Save a string in a movie with the proper encoding.
void	SetAutoOrder (bool auto_order=true)
	Let the library re-order the objects.
void	SetCompress (bool compress=true)
	Set whether the movie should be compressed or not.
void	SetFrame (const SRectangle &rect)
	Defines the size of the output.
void	SetMaximumVersion (unsigned char version)
	Set the maximum version for the output movie.
void	SetMinimumVersion (unsigned char version)
	Set the minimum version for the output movie.
void	SetOutputEncoding (const char *encoding)
	Defines the encoding of the entire movie.
void	SetRate (float rate)
	Set the speed at which the frames are to be played.
void	SetUseNetwork (bool use_network=true)
	Whether a locally played movie can use the network.
void	SetVersion (unsigned char version)
	Set the version of the output movie.
	TagHeader (void)
	Initialize the TagHeader object.
virtual swf_type_t	TypeFlags (void) const
	Return the type flags as defined in TagBase.
virtual unsigned char	Version (void) const
	Read the current output movie version.
virtual	~TagHeader ()
	Destroy a TagHeader object.
Protected Member Functions
virtual ErrorManager::error_code_t	OnNewChild (const char *child_name) const
	Check that the child is not a TagHeader.
virtual ErrorManager::error_code_t	PreSave (void)
	Prepare the children objects to be saved.
Private Attributes
bool	f_auto_order
bool	f_compress
SRectangle	f_frame
bool	f_has_jpegtables
bool	f_has_metadata
iconv_t	f_iconvertor
bool	f_iconvertor_open
unsigned char	f_maximum_version
unsigned char	f_min_version
unsigned char	f_minimum_version
sswf_id_t	f_next_id
char *	f_output_encoding
float	f_rate
bool	f_use_network
unsigned char	f_version

Detailed Description

The TagHeader class is used as the root of an SWF movie. In order to create a movie you must first create a TagHeader. This is the parent tag of most of the other tags (the exception, at this time, are the objects put in a Sprite; but Sprites are defined in a TagHeader)

Use the SetCompress(), SetUseNetwork(), SetVersion(), SetMaximumVersion() SetAutoOrder(), SetFrame(), SetOutputEncoding(), SetRate() to initialize the movie.

Call Save() once all the tags have been saved in the movie.

See also:: SWF Alexis' Reference—The File Header

Constructor & Destructor Documentation

TagHeader::TagHeader ( void )

The TagHeader create a movie with a frame set to 0, 100, 0, 100 by default.

The rate is set to 30.0 frames a second.

There is no minimum, maximum or specific version required.

By default, the use of the network by a movie played locally is turned off. Yet, this is not fully enforced since it does not force the library into creating a version 8 movie. Use SetVersion() to force a version 8 movie.

TagHeader::~TagHeader ( ) [virtual]

In particular, the destructor ensures that if an iconv(3) handle has been created, it gets closed.

The TagHeader derives from the TagBase which itself derives from the MemoryManager. This one is used to manage all the memory allocation and the destructor will release any buffer the TagHeader has allocated.

See also:: TagBase::~TagBase(), MemoryManager::~MemoryManager()

Member Function Documentation

ErrorManager::error_code_t TagHeader::DefineMinimumVersion ( int & min_version )

This function is used to determine the minimum SWF version required to save the current movie. It is automatically called by the Save() function before the movie is created in a Data buffer to know whether it will be possible to create that movie.

This funtion goes through all the TagHeader childrens recursively and each one determine what minimum SWF version the it requires to properly be saved in a movie. Note that the TagDoAction, and other tags supporting actions, checks every single action.

By default, the minimum version is set to 1 unless you requested a compressed movie in which case it starts at 6. You can start with a different minimum version by calling the SetMinimumVersion() function. Note however that if you set the minimum version to 5 and request a compressed movie, the result will be that the minimum starts at 6 anyway.

If you called SetVersion(), which fixes the version of the output movie, the minimum is set to that version directly. If any tag cannot be saved with that specific version, then the Save() function fails and no movie is created.

If you want to make sure that a movie is not created with too large a version, then use the SetMaximumVersion() function. The Save() will fail if the minimum required is larger than the maximum you defined.

Parameters:

[out] min_version The minimum version

Returns:: An error code number

See also:: Save(), SetVersion(), SetMinimumVersion(), SetMaximumVersion()

const SRectangle & TagHeader::Frame ( void ) const

This function returns a constant reference to the current frame object defined in the header.

This can, for instance, be used to create the necessary HTML code to play back the movie.

Returns:: A rectangle with the frame sizes.

See also:: SetFrame(const SRectangle& rect)

void TagHeader::MinimumVersion ( unsigned char version ) [virtual]

Whenever you create a movie, you may want to use a minimum version to make sure that certain options are properly taken in account.

For instance, if you want to make use of the Use Network flag, you need a minimum version of 8. If you want to be sure that your movie works all over the world, in regard to text, then you need to use a version of 6 as a minimum.

The version defined with this function is the one used to start defining the minimum version necessary by calling the DefineMinimumVersion() function.

Parameters:

version

The minimum version.

Reimplemented from sswf::TagBase.

unsigned short TagHeader::NextID ( void )

All the definition tags require an identifier. In order to generate only unique identifier, one can use this function.

Notice that there is a maximum of 32766 identifiers. Values larger than 32767 have special meanings and 0 cannot legally be used as an object identifier.

Returns:: A unique identifier.

See also:: RemoveID(sswf_id_t id)

ErrorManager::error_code_t TagHeader::OnError	(	ErrorManager::error_code_t	errcode,
		const char *	message,
			...
	)			const `[virtual]`

This function calls the sswf::ErrorManager::OnError(error_code_t errcode, const char *message, va_list ap) const.

Parameters:

	errcode	The code of this error
	message	The message for this error
	...	Arguments for the message

Returns:: Usually the input error code; the user may change it

Reimplemented from sswf::ErrorManager.

ErrorManager::error_code_t TagHeader::OnError	(	ErrorManager::error_code_t	errcode,
		const char *	message,
		va_list	ap
	)			const `[virtual]`

This function calls the sswf::ErrorManager::OnError(error_code_t errcode, const char *message, va_list ap) const.

Parameters:

	errcode	The code of this error
	message	The message for this error
	ap	Arguments for the message

Returns:: Usually the input error code; the user may change it

Reimplemented from sswf::ErrorManager.

ErrorManager::error_code_t TagHeader::OnNewChild ( const char * child_name ) const [protected, virtual]

A sswf::TagHeader cannot be a child of any other tag. Any other tag can be a child of a TagHeader so far.

This function returns an error whenever the child is a tag header.

See also:: sswf::TagBase::OnNewChild(const char *child)
sswf::TagSprite::OnNewChild(const char *child)

Reimplemented from sswf::TagBase.

ErrorManager::error_code_t TagHeader::PreSave ( void ) [protected, virtual]

This function calls all the children PreSave() function. It is used for the children to have a chance to prepare themselves before being saved. This is necessary for the few tags which need forward look ups. Also some special structures need preparation. For the fonts, it is also necessary to have a PreSave2ndPass()

The TagHeader object overwrites this TagBase function in order to search for a TagMetadata and TagJPEGTables. It ensures unicity of these tags, and in a version 8 animation, it needs to set a flag in the FileAttributes tags when there is a TagMetadata in the file.

Returns:: 0 when it worked; some other non-zero value when it fails

Reimplemented from sswf::TagBase.

float TagHeader::Rate ( void ) const

This function returns the rate you set with SetRate().

Returns:: The frame rate in a floating point.

See also:: SetRate(float rate)

void TagHeader::RemoveID ( sswf_id_t id )

At times, an object foresees the necessity to have its own identifier. Then later it may either be merged with another object or jointly used with another object. In that case, it is possible to release an identifier.

At this time, if you release the very last identifier which was allocated, it is made available again, otherwise the function does nothing.

Parameters:

The identifier which is not needed anymore.

See also:: NextID(void)

ErrorManager::error_code_t TagHeader::Save ( Data & data ) [virtual]

The Save() function first calls the DefineMinimumVersion() function. Even if you do not specify a minimum, maximum or specific version, it is necessary to know the version before starting the save process since certain tags can either be optimized or are required to be used instead of others depending on the version (for instance, a version 5 can make use of SWF_TAG_PROTECT_DEBUG, but other versions will use SWF_TAG_PROTECT or SWF_TAG_PROTECT_DEBUG2).

Once it determined it could save the movie, it recursively saves all the objects in the data parameter.

If everything works as expected, it returns zero meaning that the data buffer holds the resulting movie.

Parameters:

data

The buffer where the movie is to be saved

Returns:: 0 when the Save() succeeded; a non-zero value otherwise

Implements sswf::TagBase.

ErrorManager::error_code_t TagHeader::SaveEncodedString	(	Data &	data,
		const char *	string
	)

All the strings giving to any tag in an SWF movie must be UTF-8. This function will ensure that the encoding of the string in the resulting SWF movie is set according to the user specification (when the version is 5 or less) or left alone (when the version is 6 or more.)

This function is used by the tags to save strings in the data buffer. It should not otherwise be called directly.

For movies with version 5 or less, you should use the SetOutputEncoding() to ensure that it is saved with the correct caracters. By default, ISO-8859-1 is used.

Parameters:

	data	The buffer where the string is to be saved
	string	The string to save in the buffer

Returns:: The number of bytes saved in the buffer

See also:: TagBase::PutString(const char *string)

void TagHeader::SetAutoOrder ( bool auto_order = true )

Note: this is currently ignored

The ultimate would be to have the library sort out the definitions of objects so they happen only when necessary. This is very problematic now that you can write complex ActionScripts which can reference an object (and the library could not really know... unless it is told.)

So at this time I did not work on this functionality.

Parameters:

auto_order

Whether you want the library to re-order the definition tags for you.

void TagHeader::SetCompress ( bool compress = true )

Since version 6, it is possible to create SWF files which are compressed with zlib. This flag is false by default. Setting the flag to true forces the library to save at least a version 6 movie.

Parameters:

compress

Set to whether true or false

void TagHeader::SetFrame ( const SRectangle & rect )

This function defines the size of the output frame.

By default, the TagHeader sets the frame to (0, 100, 0, 100).

The frame must have x and y positions set to (0, 0).

Parameters:

rect

Rhe rectangle used to define the frame sizes.

See also:: Frame(void)

void TagHeader::SetMaximumVersion ( unsigned char version )

This function is used to ensure that the output movie will not be more than that version. If a tag requires a higher versions then it won't be possible to save the movie.

This is useful if you want to create a movie for Linux which at this time (Oct 2006) still does not support version 8 of the Macromedia player.

This is used by the Save() function to verify that the movie can indeed be saved before to proceed.

Parameters:

version

The maximum version the output movie should use

See also:: DefineMinimumVersion(), Save(), SetVersion(), SetMinimumVersion()

void TagHeader::SetMinimumVersion ( unsigned char version )

This function is used to ensure that the output movie will be at least of that version. Lower versions will not be considered.

This is useful if you want to create a version 6 movie but you don't want to be prevented from creating a version 7 or 8.

This is used by the DefineMinimumVersion() function.

Parameters:

version

The minimum version the output movie should use

See also:: DefineMinimumVersion(), Save(), SetVersion(), SetMaximumVersion()

void TagHeader::SetOutputEncoding ( const char * encoding )

Whenever you are using a version 6 or better movie, you endup using UTF-8 strings.

When creating an older version, you may need to convert your input in a specific encoding so it works for your viewers. This function can be used to set the encoding used in the movie.

Parameters:

encoding

The name of the encoding as support by your iconv

void TagHeader::SetRate ( float rate )

This function sets the speed at which the frames in the movie needs to be played back.

By default, the frame rate is set to 30.0 (i.e. close to the NTSC refresh rate).

A smaller value makes the movie play slower. A larger value makes the movie play faster.

PAL uses 25 frames a second. Older movies can have as few as 15 images a second.

Parameters:

rate

The frame rate (saved in a short float in the movie, the range is 1.0 to nearly 256.0, thought over 60 it tends to be way too fast)

See also:: Rate(void)

void TagHeader::SetUseNetwork ( bool use_network = true )

When you use a local player to run an SWF animation, this flag determines whether that movie can make use of the network or not.

Movies played via a browser connected to the Internet ignore this flag.

Note that only movies of version 8 or more can use this flag.

void TagHeader::SetVersion ( unsigned char version )

This function can be used to force the output movie to use a specific version.

It is not recommanded to use this function.

If any tag cannot be represented in the specified version, then the Save() function will fail.

This is used by the DefineMinimumVersion() function and the Save() function.

Parameters:

version

The exact version the output movie should use

See also:: DefineMinimumVersion(), Save(), SetMinimumVersion(), SetMaximumVersion()

TagBase::swf_type_t TagHeader::TypeFlags ( void ) const [virtual]

This function returns the flags representing the TagHeader.

At this time it includes: HEADER, UNIQUE and START.

Implements sswf::TagBase.

unsigned char TagHeader::Version ( void ) const [virtual]

This function retrieves the version in which the movie will be saved.

Unless you called the SetVersion() function, this is the minimum version as defined by the DefineMinimumVersion() function.

This function can be overloaded in order to control what it shall return. For instance, you may always prevent a version of 1 or 2 to appear. Then your Version() function would look like this:

        unsigned char MyObject::Version(void) const
        {
                unsigned char version;

                version = TagHeader::Version();

                if(version < 3) {
                        version = 3;
                }

                return version;
        }