libsswf: sswf::TagPlace Class Reference

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

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.

- No reference defined -- sswf::TagPlace::SetObjectID(sswf_id_t id)
- Replace any existing object at that depth -- sswf::TagPlace::Replace(void) and sswf::TagPlace::Place(void)
- Undefined depth (-1) -- sswf::TagPlace::SetDepth(int depth)
- No clipping -- sswf::TagPlace::SetClip(int depth)
- Unnamed -- sswf::TagPlace::SetName(const char *name)
- No morphing position -- sswf::TagPlace::SetMorphPosition(int position)
- No blending -- sswf::TagPlace::SetBlendMode(blend_mode_t blend_mode)
- No bitmap caching -- sswf::TagPlace::SetBitmapCaching(int bitmap_caching) and SetBlendModeName(const char *blend_mode_name)
- No transformation matrix -- sswf::TagPlace::SetMatrix(const Matrix& matrix)
- No color matrix -- sswf::TagPlace::SetColorTransform(const ColorTransform& color_transform)
- No events -- sswf::TagPlace::AddEvent(Event *event)

Parameters:

  `[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!)

Parameters:

  `[in]` | 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 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.

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)

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.

Returns:
  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::Place(void)

  sswf::TagPlace::SetObjectID(sswf_id_t id)

  sswf::TagRemove

References f_replace.

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:

  `[in,out]` | data | The Data buffer where the tag is saved

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

Implements sswf::TagBase.

References sswf::Event::Actions(), sswf::Data::Append(), sswf::Data::ByteSize(), sswf::Vectors::Count(), sswf::Data::Empty(), sswf::ErrorManager::ERROR_CODE_INVALID_DEPTH, sswf::ErrorManager::ERROR_CODE_NONE, sswf::Event::EVENT_KEY_PRESS, sswf::Event::Events(), f_bitmap_caching, f_blend_mode, f_clip_depth, f_color_transform, f_depth, f_events, f_events_all_flags, f_has_matrix, f_id, f_id_defined, f_matrix, f_name, f_position, f_replace, sswf::Vectors::Get(), sswf::BlendMode::HasBlendMode(), sswf::ColorTransform::IsNull(), sswf::ColorTransform::IsSolidCompatible(), sswf::Event::Key(), sswf::TagBase::OnError(), sswf::Data::PutByte(), sswf::Data::PutLong(), sswf::Data::PutShort(), sswf::BlendMode::Save(), sswf::ColorTransform::Save(), sswf::Matrix::Save(), sswf::Action::SaveList(), sswf::TagBase::SaveString(), sswf::TagBase::SaveTag(), sswf::TagBase::SWF_TAG_PLACE_OBJECT, sswf::TagBase::SWF_TAG_PLACE_OBJECT2, sswf::TagBase::SWF_TAG_PLACE_OBJECT3, sswf::TagBase::Version(), and sswf::Data::WriteBits().

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:

  `[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.

Parameters:

  `[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.

Bug:
  The depth and clipping depth are hard coded and thus this feature is not that practical to use.

Parameters:

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

Parameters:

  `[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!

Parameters:

  `[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.

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:

  `[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.

Parameters:

  `[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.

Note:
  Only sprites can be named in this manner. Other objects will ignore the name.

Bug:
  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...

Parameters:

  `[in]` | name | The name of the object

See also:
  TagPlace::Replace(void)

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.

Parameters:

  `[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.

Returns:
  The CONTROL, SCRIPT and REFERENCE bits

Implements sswf::TagBase.

References SWF_TYPE_CONTROL, SWF_TYPE_REFERENCE, and SWF_TYPE_SCRIPT.

## Member Data Documentation

int sswf::TagPlace::f_bitmap_caching`[private]`

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

BlendMode sswf::TagPlace::f_blend_mode`[private]`

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

int sswf::TagPlace::f_clip_depth`[private]`

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

ColorTransform sswf::TagPlace::f_color_transform`[private]`

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

int sswf::TagPlace::f_depth`[private]`

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

Vectors sswf::TagPlace::f_events`[private]`

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

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

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

bool sswf::TagPlace::f_has_matrix`[private]`

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

sswf_id_t sswf::TagPlace::f_id`[private]`

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

bool sswf::TagPlace::f_id_defined`[private]`

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

Matrix sswf::TagPlace::f_matrix`[private]`

Referenced by Save(), and SetMatrix().

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

Reimplemented from sswf::TagBase.

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

int sswf::TagPlace::f_position`[private]`

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

int sswf::TagPlace::f_replace`[private]`

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

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

- libsswf.h
- libsswf_tag_place.c++