libsswf: sswf::TagPlace Class Reference

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.

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.

Implements sswf::TagBase.

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.

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.

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.

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

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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

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

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

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

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

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

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

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

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

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

Referenced by Save(), and SetMatrix().

Reimplemented from sswf::TagBase.

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

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

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