Made to Order Software Corporation Logo

libsswf: 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:

:TagBase :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 ParseTag (swf_tag_t tag, const Data &data)
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.

[in] parent A pointer to the parent of the TagPlace (sprite or header)

References sswf::assert(), f_bitmap_caching, f_clip_depth, f_depth, f_events_all_flags, f_has_matrix, f_id, f_id_defined, f_name, f_position, and f_replace.

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 that 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!)

[in] event The event to add to this TagPlace object
This function returns true if the event is accepted as is. If the event has flags that are not compatible with the TagPlace tag, then the function returns false and the event is not added.

References sswf::Event::Events(), f_events, sswf::Vectors::Set(), SSWF_EVENT_V5, SSWF_EVENT_V6, and SSWF_EVENT_V7.

virtual ErrorManager::error_code_t sswf::TagPlace::ParseTag ( swf_tag_t  tag,
const Data data 
) [private, virtual]

Implements sswf::TagBase.

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.

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::SetObjectID(sswf_id_t id)

References f_replace.

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.

Zero when no error occurs, non-zero otherwise

Reimplemented from sswf::TagBase.

References sswf::Event::Actions(), sswf::Vectors::Count(), sswf::ErrorManager::ERROR_CODE_NONE, sswf::ErrorManager::ERROR_CODE_UNEXPECTED_EVENT_FLAG, f_bitmap_caching, f_blend_mode, f_clip_depth, f_color_transform, f_events, f_events_all_flags, f_id_defined, f_name, f_position, f_replace, sswf::Vectors::Get(), sswf::BlendMode::HasBlendMode(), sswf::ColorTransform::IsSolidCompatible(), sswf::Action::MinimumListVersion(), sswf::TagBase::MinimumVersion(), SSWF_EVENT_V5, SSWF_EVENT_V6, and SSWF_EVENT_V7.

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::SetObjectID(sswf_id_t id)


References f_replace.

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.

[in] bitmap_caching needs testing, use 0 or 1 to not set or set the bitmap caching

References f_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.

[in] blend_mode One of the valid blen mode
See also:
sswf::TagPlace::SetBlendModeName(const char *blend_mode_name)

References f_blend_mode.

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.

The depth and clipping depth are hard coded and thus this feature is not that practical to use.
[in] depth The top of the clipping range

References f_clip_depth.

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).

[in] color_transform The color matrix to save in this PlaceObject

References f_color_transform.

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!

[in] depth The new object depth

References f_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.

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.
[in] matrix The matrix to apply to the object

References f_has_matrix, and f_matrix.

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.

[in] position The morph position

References f_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.

Only sprites can be named in this manner. Other objects will ignore the name.
By default, setting a name will have the effect of hiding the sprite being named. You need to call the TagPlace::Replace() function to get the correct behavior. This is yet another trick in the Flash players...
[in] name The name of the object
See also:

References f_name, sswf::MemoryManager::MemFree(), and sswf::MemoryManager::StrDup().

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.

[in] id The identifier of the object to place

References f_id, and f_id_defined.

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.


Implements sswf::TagBase.


Member Data Documentation

Referenced by PreSave(), Save(), SetClip(), and TagPlace().

int sswf::TagPlace::f_depth [private]

Referenced by Save(), SetDepth(), and TagPlace().

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

Referenced by PreSave(), Save(), and TagPlace().

Referenced by Save(), SetMatrix(), and TagPlace().

Referenced by Save(), and SetMatrix().

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

Reimplemented from sswf::TagBase.

Referenced by PreSave(), Save(), SetName(), and TagPlace().

Referenced by Place(), PreSave(), Replace(), Save(), and TagPlace().

The documentation for this class was generated from the following files:

Generated on Wed Mar 18 15:13:59 2009 for libsswf by  doxygen 1.5.5