sswf::TagPlace

sswf::TagPlace Class Reference

Tag used to place (or remove) an object in the display list. More...

#include <libsswf.h>

Inheritance diagram for sswf::TagPlace:

sswf::TagBase sswf::MemoryManager List of all members.

Public Member Functions

bool AddEvent (Event *event)
 Add the specified event to the place tag.
void Place (void)
 Mark the TagPlace as an additional placement.
void Replace (void)
 Mark the TagPlace as a replacement.
virtual ErrorManager::error_code_t Save (Data &data)
 Save the TagPlace in the specified Data buffer.
void SetBitmapCaching (int bitmap_caching)
 Determine whether bitmap caching can be done.
void SetBlendMode (const BlendMode &blend_mode)
 Defines a blending filter.
void SetClip (int depth)
 Insert a mask in the display list, not a shape.
void SetColorTransform (const ColorTransform &color_transform)
 Set the color transformation matrix.
void SetDepth (int depth)
 The depth at which the object is placed.
void SetMatrix (const Matrix &matrix)
 Set the geometric transformation matrix.
void SetMorphPosition (int position)
 Set the morphing position.
void SetName (const char *name)
 Defines the name of a TagPlace object.
void SetObjectID (sswf_id_t id)
 Change the identifier of the object to place.
 TagPlace (TagBase *parent)
 Initialize a TagPlace object.
virtual swf_type_t TypeFlags (void) const
 This function returns the flags representing the type of the TagPlace tag.

Private Member Functions

virtual ErrorManager::error_code_t PreSave (void)
 Prepare the object to be saved.

Private Attributes

int f_bitmap_caching
BlendMode f_blend_mode
int f_clip_depth
ColorTransform f_color_transform
int f_depth
Vectors f_events
unsigned long f_events_all_flags
bool f_has_matrix
sswf_id_t f_id
bool f_id_defined
Matrix f_matrix
char * f_name
int f_position
int f_replace

Detailed Description

This tag can be used to place or remove an object in the display list.

The default behavior is to replace the object at the specified depth.

See also:
SWF Alexis' Reference—Place Object

SWF Alexis' Reference—Place Object 2 & 3

SWF Alexis' Reference—swf_tag

Constructor & Destructor Documentation

TagPlace::TagPlace ( TagBase *  parent  ) 

The constructor initializes the TagPlace to defaults. The following gives you the default value and the function to use to change the default value.

Member Function Documentation

bool TagPlace::AddEvent ( Event *  event  ) 

This function adds the specified event to the TagPlace object.

An event is a set of flags which determine when the event is triggered and a set of actions to execute then.

As many events as you need can be added. However, the first event matching has its ActionScript executed and then the process stops (to be confirmed!)

Parameters:
event The event to add to this TagPlace object
Returns:
This function returns true if the event is accepted as is. If the event has flags which are not compatible with the TagPlace tag, then the function returns false and the event is not added.

void TagPlace::Place ( void   ) 

This function marks this TagPlace as an 'add' function. The object referenced will be added to the display list whether there is already an object at the same depth.

Note:
When you add new objects at the same depth, the first ones stay on top and the last go below the other objects. This was true in older versions and is likely working the same way.
See also:
sswf::TagPlace::Replace(void)

sswf::TagPlace::SetObjectID(sswf_id_t id)

ErrorManager::error_code_t TagPlace::PreSave ( void   )  [private, virtual]

This function checks all the parameters to determine the minimum version required to save this TagPlace object.

By default, the minimum is considered to be 1.

The use of events forces the version to be 5, 6 or 7 depending on the actions and flags used.

The use of a name, no identifier, a color transform with an alpha channel, a clip depth forces the version to a minimum of 3.

Returns:
Zero when no error occurs, non-zero otherwise

Reimplemented from sswf::TagBase.

void TagPlace::Replace ( void   ) 

The tag is used to replace another object at the specified depth.

If no object reference is defined, then this becomes a "remove" instead (in other words, it always removes, and may insert)

See also:
sswf::TagPlace::Place(void)

sswf::TagPlace::SetObjectID(sswf_id_t id)

sswf::TagRemove

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

This function saves the TagPlace in the specified Data buffer.

The tag is saved only if the depth is correct.

Parameters:
data The Data buffer where the tag is saved
Returns:
Zero when no error occurs, non-zero otherwise

Implements sswf::TagBase.

void TagPlace::SetBitmapCaching ( int  bitmap_caching  ) 

This function sets the flag bitmap caching to true or false.

Newer versions of SWF can save the bitmaps in buffers and not re-render everything on each frame. This is particularly useful if you create a complex but inanimated sprite which can therefore be drawn once in a buffer and any number of time from that buffer to the final display screen.

Parameters:
bitmap_caching needs testing, use 0 or 1 to not set or set the bitmap caching

void TagPlace::SetBlendMode ( const BlendMode &  blend_mode  ) 

This function defines the filter to use with this TagPlace object. It determines how the object is rendered on the screen.

By specifying a blend mode, TagPlace generates one of the SWF_TAG_PLACE_OBJECT2 or SWF_TAG_PLACE_OBJECT3.

See also:
sswf::TagPlace::SetBlendModeName(const char *blend_mode_name)

void TagPlace::SetClip ( int  depth  ) 

When defining a clipping, this TagPlace must reference either a shape or a text. Other objects will not work (at least up to version 6 of SWF). The referenced object defines a mask to use as a clipping mask.

The sswf::TagPlace::SetDepth(int depth) and sswf::TagPlace::SetClip(int depth) functions must both be called to define the range of depths affected by the clipping. All the objects placed in that range will be affected by this clipping mask. The depths defined in the Depth and Clip are inclusive.

Bug:
The depth and clipping depth are hard coded and thus this feature is not that practical to use.
Parameters:
depth The top of the clipping range

void TagPlace::SetColorTransform ( const ColorTransform &  color_transform  ) 

This function sets the transformation matrix to apply on the color.

This matrix can affect the alpha channel. It can be used to transform the colors by scaling the components and adding a bias to each component. It is not a full matrix. To tweak the full matrix, you need to use the color matrix filter instead (which requires version 8 of SWF also).

Parameters:
color_transform The color matrix to save in this PlaceObject

void TagPlace::SetDepth ( int  depth  ) 

The sswf::TagPlace object is used to place an object in the display list. The display list is organized as an array of objects sorted by depth. Each object should have a distinct depth (though older versions of the Flash player would accept multiple objects at the same depth, it may not last forever!)

The depth 0 should not be used for your objects.

Bit 15 (0x8000) of the depth is used in a special way (thought I cannot find the docs about that right now...). So you really only can use depth 1 to 32767 which is likely to be enough anyway!

Parameters:
depth The new object depth

void TagPlace::SetMatrix ( const Matrix &  matrix  ) 

This function defines the transformation matrix used to move, scale, rotate and skew the referenced object on the screen.

Note:
A flag is used to know whether the matrix was changed. Unfortunately this means setting an identity matrix will result in incorporating the matrix in the result even thought it is useless. But it seemed also that without incorporating the matrix in the TagPlace, you could not tweak it with an ActionScript. This may have been fixed since I checked (or maybe my test was bogus...). So it could be useful to have a matrix even if it is the identity.
Parameters:
matrix The matrix to apply to the object

void TagPlace::SetMorphPosition ( int  position  ) 

This function is used to change the position of the morph.

This is a static setup in a TagPlace object.

The position of 0 represents the first object and a position of 65535 represents the last object.

By default the position is set to -1 meaning that you are not referencing a morph object.

Placing a morph object without a position is similar to placing that object with a position of 0, thought, for forward compatibility, it is a good idea to always use a corresponding place.

Parameters:
position The morph position

void TagPlace::SetName ( const char *  name  ) 

This function is used to define the name of the TagPlace object.

The name can later be used to reference the object from an ActionScript.

By default, an object being placed has no name.

You can set the name to NULL or "" to remove the name.

Parameters:
name The name of the object

void TagPlace::SetObjectID ( sswf_id_t  id  ) 

This function defines the object that this TagPlace inserts in the display list.

Note that in newer SWF versions it is possible to not define any object identifier to use the TagPlace to remove an object at the specified depth. Thus calling this function is not mandatory. Also, if you do call this function, you lose that other functionality.

Parameters:
id The identifier of the object to place

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

This function returns the flag CONTROL, this tag is used to control the display list.

This function returns the flag SCRIPT, it can include a script executed when responding to events.

This function returns the flag REFERENCE, it references one object which it places in the display list.

Returns:
The CONTROL, SCRIPT and REFERENCE bits

Implements sswf::TagBase.

Member Data Documentation

int sswf::TagPlace::f_bitmap_caching [private]

BlendMode sswf::TagPlace::f_blend_mode [private]

int sswf::TagPlace::f_clip_depth [private]

ColorTransform sswf::TagPlace::f_color_transform [private]

int sswf::TagPlace::f_depth [private]

Vectors sswf::TagPlace::f_events [private]

unsigned long sswf::TagPlace::f_events_all_flags [private]

bool sswf::TagPlace::f_has_matrix [private]

sswf_id_t sswf::TagPlace::f_id [private]

bool sswf::TagPlace::f_id_defined [private]

Matrix sswf::TagPlace::f_matrix [private]

char* sswf::TagPlace::f_name [private]

Reimplemented from sswf::TagBase.

int sswf::TagPlace::f_position [private]

int sswf::TagPlace::f_replace [private]

The documentation for this class was generated from the following files:
Generated on Tue Jun 26 02:36:45 2007 for libsswf by  doxygen 1.4.7