Reference for the Mosaic class Effects::WarpFader

Effects::WarpFader
Matrix
OpacityEffect
Position1
Position2
WarpEffect
Effects::Fader
AddToOwner
AssignFocus
Enabled
Group
OnInitialize
Owner
RemoveIfHidden
RestackTopmost
UseCurrentState
Visible
Complete()
IsFinished()
OnEnd()
OnStart()

SEE ALSO

Implement your own Dialog transition animation.

The class Effects::WarpFader provides functionality for the fade-in and fade-out transitions affecting the shape and eventually the opacity of a given GUI component. This fader is thus ideal wherever one GUI component should smoothly appear or disappear by 2D/3D rotating, scaling and translating its image within another component.

The parameters for the desired 2D/3D transformation are determined by the embedded object Matrix. In case of the fade-in transition (property Visible is 'true'), Matrix specifies the 2D/3D transformation valid just at the beginning of the transition. In case of the fade-out transition (property Visible is 'false'), Matrix determines the transformation at the end of the transition. The duration and the timing of the animation are configured in the embedded object WarpEffect. During the transition, the fader interpolates the coefficients stored within Matrix against an identity matrix (or vice versa).

The both properties Position1 and Position2 specify the positions, where to map the center of the warped GUI component image just at the beginning and at the end of the transition. Both are expressed relative to the top-left corner of the Owner component. If the property UseCurrentState is 'true', the position where to start the animation is automatically taken over from the center position of the affected GUI component as it is just in the moment the fader starts the transition.

The parameters for the opacity transition (their start and the end values, the duration of the transition, the timing, etc.) are configured in the embedded object OpacityEffect. If the property UseCurrentState is 'true', the opacity to start the animation is automatically taken over from the affected GUI component as it is just in the moment the fader starts the transition.

Whether the fader is considered as performing a fade-in or fade-out transition is determined by value of the property Visible. Set this property to the value 'true' if you want the component to appear or remain visible after the transition is done. Set this property to the value 'false' if your intention is to hide or keep invisible the component.

The fader automatically takes care of adding the GUI component to the intended owner, when the component should appear and it is not yet a member within the owner. Moreover, when fading-in the component, the fader automatically focuses it and restacks it to appear above all other sibling views existing already within the owner component. This behavior can be configured by modifying the properties AssignFocus and RestackTopmost.

The fader automatically removes the GUI component from its owner, when the component disappears (after fade-out). This behavior can be changed by modifying the property RemoveIfHidden.

Applying the fade-out transition on a GUI component, which is already invisible has no effect. Similarly, the fade-in transition has no effect if the GUI component is already visible and has the opacity and position equal to the specified in OpacityEffect object and the property Position2. In both cases the affected component retains its actual state and the fader finishes its work immediately without driving the effect objects and waiting for their completion.

In practice, you create an instance of the fader class, configure its properties (in particular the property Visible and Position2), the both objects WarpEffect and OpacityEffect as well as the Matrix object according to the desired kind of transition and pass both, the fader instance and the affected GUI component as parameters in the invocation of the method Core::Group.FadeGroup().

object Graphics::WarpMatrix Matrix;

The embedded object 'Matrix' determines the desired 2D or 3D warp transformation to apply on the image of the affected GUI component Group while the fader performs the animation.

If the fader is configured to fade-in the GUI component (the property Visible is 'true), the 2D/3D transformation resulting from the 'Matrix' object is assumed to be valid just at the beginning of the transition. During this transition, the coefficients stored in the 'Matrix' are interpolated agains an identity matrix causing the GUI component to appear at the end of the animation without any warp effects. In turn, if the fader is configured to fade-out the GUI component (property Visible is 'false'), the 'Matrix' object is assumed to be valid just at the end of the transition also interpolated against the identity matrix.

Usually, you configure this 'Matrix' object shortly before you pass the fader in parameter to the Core::Group.FadeGroup() method. For more details, how to configure 2D/3D warp transformations, see the description of the class Graphics::WarpMatrix.

object Effects::Int32Effect OpacityEffect;

The embedded object 'OpacityEffect' determines the parameters to use for the opacity animation. In particular, its properties 'Value1' and 'Value2' are intended to specify the desired opacity at the beginning and at the end of the transition. How long the transition should take, has to be specified in the property 'CycleDuration'. During the transition, the 'OpacityEffect' object interpolates between the both values and adjusts accordingly the opacity of the affected GUI component. For more details, how to configure an effect, see the description of the class Effects::Int32Effect.

Please note, if the property UseCurrentState is 'true', the fader will automatically adapt the property 'Value1' of the 'OpacityEffect' object to the opacity value of the affected GUI component as it is just in the moment when the fader starts the transition. Moreover, whether the fader operation is considered as performing the fade-in or fade-out operation, depends exclusively on the value you specify in the property Visible.

Usually, you configure this 'OpacityEffect' object shortly before you pass the fader in parameter to the Core::Group.FadeGroup() method.

property point Position1 = <0,0>;

The property 'Position1' determines the origin of the 3D coordinate system for the intended warp operation just at the beginning of the animation. In other words this is the position where the fader assumes the center of the animated GUI component to be when the transition begins. The position is expressed relative to the top-left corner of the Owner component.

During the transition, the fader interpolates between the value 'Position1' and Position2 causing the origin of the 3D coordinate system (and thus the image of the animated GUI component) to be moved between the both positions. Please note, initializing this property has an effect only when the fader is configured to not use the actual state of the affected GUI component (the property UseCurrentState is 'false'). If the property UseCurrentState is 'true', 'Position1' is automatically initialized with actual center position of the GUI component as it is just at beginning of the transition.

property point Position2 = <0,0>;

The property 'Position2' determines the origin of the 3D coordinate system for the intended warp operation just at the end of the animation. In other words this is the position where the fader assumes the center of the animated GUI component to be when the transition terminates. The position is expressed relative to the top-left corner of the Owner component.

During the transition, the fader interpolates between the value Position1 and 'Position2' causing the origin of the 3D coordinate system (and thus the image of the animated GUI component) to be moved between the both positions.

object Effects::FloatEffect WarpEffect;

The embedded object 'WarpEffect' determines the parameters to drive the warp animation. In particular, with its property 'CycleDuration' you specify how long the transition should take. During the transition, the 'WarpEffect' object is used to interpolate the coefficients stored in the transformation matrix Matrix and to calculate from the resulting values the shape of the 2D/3D warped image of the affected GUI component. For more details, how to configure an effect, see the description of the class Effects::FloatEffect.

Usually, you configure this 'WarpEffect' object shortly before you pass the fader in parameter to the Core::Group.FadeGroup() method. Whether the fader operation is considered as performing the fade-in or fade-out operation, depends exclusively on the value you specify in the property Visible.