libsswf: sswf::State Class Reference

# sswf::State Class Reference

The state a button will react to. More...

`#include <libsswf.h>`

Inheritance diagram for sswf::State:

List of all members.

## Public Types
enum | state_flags_t { STATE_FLAG_UP = 0x01, STATE_FLAG_OVER = 0x02, STATE_FLAG_DOWN = 0x04, STATE_FLAG_HIT_TEST = 0x08, STATE_ALL_FLAGS = 0x0F }
| The states of the button. More...
## Public Member Functions
unsigned char | GetFlags (void) const
| Get the flags from this State.
bool | HasColorTransform (void) const
| Check whether this State has a color transformation defined.
ErrorManager::error_code_t | Parse (const Data &data, bool color_transform)
| Parse a Data buffer into a State.
void | Reset (void)
| Resets a State to default values.
ErrorManager::error_code_t | Save (Data &data, bool color_transform)
| Save a state in a Data buffer.
void | SetBlendMode (const BlendMode &blend_mode)
| Defines the blending mode of the object referenced by this state.
void | SetColorTransform (const ColorTransform &color_transform)
| Set the color transformation matrix.
bool | SetFlags (unsigned char flags)
| Set the flags this State represents.
void | SetLayer (unsigned short layer)
| Set the state layer (or depth).
void | SetMatrix (const Matrix &matrix)
| Defines the matrix of the object.
void | SetObjectID (sswf_id_t id)
| Set the identification of the shape used in the test.
| State (ErrorManager &error_manager)
| Initialize the state.
## Private Attributes
BlendMode | f_blend_mode
ColorTransform | f_color_transform
ErrorManager & | f_error_manager
unsigned char | f_flags
bool | f_has_color_transform
sswf_id_t | f_id
unsigned short | f_layer
Matrix | f_matrix

## Detailed Description

This object is used to define a state to put in a button along with actions.

## Member Enumeration Documentation

enum sswf::State::state_flags_t

These flags describe when a given button state is shown or used.

Enumerator:

  STATE_FLAG_UP | The flag representing the mouse button not being clicked. This flag is used to represent the state of the button when the mouse is not being clicked. See also: enum sswf::State::STATE_FLAG_DOWN
  STATE_FLAG_OVER | The flag representing the mouse button when over the hit test area. This flag is used to represent the state of the button when the mouse is over the button hit test area. Use this flag with the up or down flags to get the corresponding state. See also: enum sswf::State::STATE_FLAG_DOWN enum sswf::State::STATE_FLAG_UP
  STATE_FLAG_DOWN | The flag representing the mouse button when clicked. This flag is used to represent the state of the button when the mouse is clicked over the button hit test area. See also: enum sswf::State::STATE_FLAG_UP
  STATE_FLAG_HIT_TEST | The flag representing the hit test area. This flag is used to represent that special state of the button used to determine the hit test of the button. The hit test is used to know whether the end-user has his mouse pointer over the button or not and when clicking, whether the end-user really clicked on the button. The hit area is never drawn on the screen. You can put it in some other states if you want the shape to appear on the screen.
  STATE_ALL_FLAGS | A mask representing all the flags. This value is used to know whether all the flags and only the flags you need were defined.

## Constructor & Destructor Documentation

State::State | ( | ErrorManager & | error_manager | ) | `[explicit]`

This function calls the State::Reset(void) function.

See also:
  sswf::State::Reset(void)

References Reset().

## Member Function Documentation

unsigned char State::GetFlags | ( | void |  | ) | const

Use this function to retrieve the flags of a state.

See also:
  sswf::State::SetFlags(unsigned char flags)

References f_flags.

Referenced by sswf::TagButton::Save(), and sswf::TagButton::SetState().

bool State::HasColorTransform | ( | void |  | ) | const

This function can be used to query the State for a color transformation or not.

This function is used by the TagButton to check all the states you saved in said button. If any one has a color transformation matrix, then all the states will be saved with a color transformation matrix even one single state makes use of it (i.e. all the others are identity matrices.)

Note:
  If the color transformation has no effect, but it was defined that way, then the function still returns true.

Returns:
  true when the State has a color transformation.

References f_has_color_transform.

Referenced by sswf::TagButton::PreSave().

ErrorManager::error_code_t State::Parse | ( | const Data & | data,
|  | bool | color_transform |
| ) |  |  |

This function parses a data buffer that is expected to include one state.

Whenever the end of the list is found, the function returns ERROR_CODE_END_OF_STATES. Watch out! This happens only once. If you miss it, you will read the following data as if it were state data.

Also, whathever State was used to read the ERROR_CODE_END_OF_STATES will not be valid.

Note:
  It is very important to pass the correct `color_transform` flag. The State by itself cannot know whether there is a color transform or not and we have to know for sure that it is there.

Parameters:

  `[in]` | data | The data buffer where the State shall be saved
  `[in]` | color_transform | Whether the color transform matrix is to be saved

Returns:
  ERROR_CODE_NONE if no error occur, ERROR_CODE_END_OF_STATES when the special flags set of 0 is found, and another error code otherwise

References sswf::ErrorManager::ERROR_CODE_END_OF_STATES, sswf::ErrorManager::ERROR_CODE_NONE, f_blend_mode, f_color_transform, f_flags, f_has_color_transform, f_id, f_layer, f_matrix, sswf::Data::GetByte(), sswf::Data::GetShort(), sswf::BlendMode::Parse(), sswf::ColorTransform::Parse(), and sswf::Matrix::Parse().

Referenced by sswf::TagButton::ParseTag().

void State::Reset | ( | void |  | ) |

This function is used to reset a State object to its initial setup.

The referenced shape identifier is set to zero (no shape referenced).

The flags are set to zero which represents an invalid set of flags; you will have to initialize them with a call to sswf::State::SetFlags(unsigned char flags)

The layer is set to zero.

The matrix is reset to the identity.

The State is marked as not having a color transformation, color transform which is also reset to have no effect.

See also:
  sswf::State::State(void)

  sswf::State::HasColorTransform(void) const

  State::SetObjectID(sswf_id_t id)

  State::SetFlags(unsigned char flags)

  State::SetLayer(unsigned short layer)

  State::SetMatrix(const Matrix& matrix)

  State::SetColorTransform(const ColorTransform& color_transform)

References f_color_transform, f_flags, f_has_color_transform, f_id, f_layer, f_matrix, sswf::ColorTransform::Reset(), and sswf::Matrix::Reset().

Referenced by State().

ErrorManager::error_code_t State::Save | ( | Data & | data,
|  | bool | color_transform |
| ) |  |  |

This function can be used to save the State in a Data buffer.

The color_transform flag is used to know whether the color transform needs to be saved or not.

Parameters:

  `[in]` | data | The data buffer where the State shall be saved
  `[in]` | color_transform | Whether the color transform matrix is to be saved

Returns:
  ERROR_CODE_NONE if no error occur, another error code otherwise

References sswf::ErrorManager::ERROR_CODE_BAD_STATE_FLAGS, sswf::ErrorManager::ERROR_CODE_NONE, f_blend_mode, f_color_transform, f_error_manager, f_flags, f_id, f_layer, f_matrix, sswf::BlendMode::HasBlendMode(), sswf::ErrorManager::OnError(), sswf::Data::PutByte(), sswf::Data::PutShort(), sswf::BlendMode::Save(), sswf::ColorTransform::Save(), and sswf::Matrix::Save().

Referenced by sswf::TagButton::Save().

void State::SetBlendMode | ( | const BlendMode & | blend_mode | ) |

This function sets the blending mode to be used to render the object of this state. This is the same as the blending mode of the TagPlace object.

Parameters:

  `[in]` | blend_mode | The blending mode to use

References f_blend_mode.

void State::SetColorTransform | ( | const ColorTransform & | color_transform | ) |

This function is used to define a color transformation matrix. This function has the side effect to setting a flag to know whether the color transformation matrix was defined or not.

Parameters:

  `[in]` | color_transform | The color transformation matrix

See also:
  State::HasColorTransform(void) const

References f_color_transform, and f_has_color_transform.

bool State::SetFlags | ( | unsigned char | flags | ) |

This function is used to define how the button will react in regard to this State. One or more of the following flags can be defined:

STATE_FLAG_UP STATE_FLAG_OVER STATE_FLAG_DOWN STATE_FLAG_HIT_TEST

Use the or (|) operator to define multiple flags at the same time.

The Reset() function sets the flags to zero. Thus this function must be called before you try saving the corresponding button.

Note:
  At least one flag needs to be set or the Save() function will fail.

Bug:
  Flags are defined on the lower 4 bits of the char. Trying to define another bit will generate an assert() in DEBUG mode.

The state flags should not be an enumeration since these are flags which can be combined.

Parameters:

  `[in]` | flags | A set of STATE_FLAG_... flags

See also:
  sswf::State::Save(Data& data, bool color_transform)

References sswf::ErrorManager::ERROR_CODE_BAD_STATE_FLAGS, f_error_manager, f_flags, sswf::ErrorManager::OnError(), and STATE_ALL_FLAGS.

void State::SetLayer | ( | unsigned short | layer | ) |

Each state has a layer (or depth as in the display list) to define the z position of each shape within the button.

There is no known limits to the layer number. The objects with a smaller layer number appear behind the object with a larger layer number.

The layer number 0 shall not be used.

Parameters:

  `[in]` | layer | The layer at which the object is to be saved

See also:
  sswf::TagPlace::SetDepth(int depth)

References f_layer.

void State::SetMatrix | ( | const Matrix & | matrix | ) |

When placing an object on the screen, you can use a transformation matrix (to rotate, scale, skew and translate the object about.)

This is similar to the sswf::TagPlace::SetMatrix(const Matrix& matrix) function.

Parameters:

  `[in]` | matrix | The transformation Matrix

See also:
  sswf::TagPlace::SetMatrix(const Matrix& matrix)

References f_matrix.

void State::SetObjectID | ( | sswf_id_t | id | ) |

The object referenced is used for two purposes: one is to draw a different shape on a mouse movement and/or click event (this renders the button quite dynamic,) and the other is to select an area which is sensitive to mouse clicks.

In order for a click to be triggered, it is necessary to know where the user needs to place the mouse to trigger the said event. This is done using the hit test shape (the object identifier needs to be the identifier of a shape for the State to function properly. This has changed in version 8 of SWF [it seems, TBD] and a Sprite can also be specified now.)

Parameters:

  `[in]` | id | The identifier of the object referenced

References f_id.

## Member Data Documentation

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

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

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

Referenced by Parse(), Reset(), Save(), and SetColorTransform().

ErrorManager& sswf::State::f_error_manager`[private]`

Referenced by Save(), and SetFlags().

unsigned char sswf::State::f_flags`[private]`

Referenced by GetFlags(), Parse(), Reset(), Save(), and SetFlags().

bool sswf::State::f_has_color_transform`[private]`

Referenced by HasColorTransform(), Parse(), Reset(), and SetColorTransform().

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

Referenced by Parse(), Reset(), Save(), and SetObjectID().

unsigned short sswf::State::f_layer`[private]`

Referenced by Parse(), Reset(), Save(), and SetLayer().

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

Referenced by Parse(), Reset(), Save(), and SetMatrix().

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

- libsswf.h
- libsswf_tag_button.c++