Reference for the Mosaic class Effects::Fader

Effects::Fader
AddToOwner
AssignFocus
Enabled
Group
OnInitialize
Owner
RemoveIfHidden
RestackTopmost
UseCurrentState
Visible
Complete()
IsFinished()
OnEnd()
OnStart()

The class Effects::Fader provides the basic infrastructure, which can be enhanced in derived classes in order to implement sophisticated transitions for fading-in and/or fading-out GUI components. At the runtime, an instance of the fader class represents a transition you can simply apply on a GUI component by passing both, the fader instance and the affected GUI component as parameters in the invocation of the method Core::Group.FadeGroup(). The infrastructure consists of:

Being the basic class, Effects::Fader doesn't implement any particular transition effects. This class is intended to be overridden and enhanced accordingly.

property bool AddToOwner = false;

The property 'AddToOwner' controls, whether the fader should automatically add the affected Group to the Owner even if performing a fade-out animation. In case of the fade-in animation, the property has no effect since the fader implicitly takes care of adding the group to its owner.

Usually, this property should be evaluated in the derived classes in the implementation of the overridden method OnStart() or OnEnd().

property bool AssignFocus = true;

The property 'AssignFocus' controls, whether the fader should automatically focus the affected Group within the Owner when performing a fade-in animation. In case of the fade-out animation, the property has no effect.

Usually, this property should be evaluated in the derived classes in the implementation of the overridden method OnStart() or OnEnd().

method void Complete();

The method Complete() is intended to be called by the implementation of your adapted fader as soon as the animation effects used inside the fader has finalized their work. This is essential in order to ensure, that next faders waiting for execution can start with their animations.

property bool Enabled = true;

The property 'Enabled' determines, whether the affected GUI component Group is enabled or not after the fader has finalized the transition. If this property is 'true', the component will become enabled (or it will remain enabled) in context of the Owner GUI component. This corresponds to the fade-in transition. If this property is 'false', the component will become disabled (or it will remain disabled). This corresponds to the fade-out transition.

var Core::Group Group;

The variable 'Group' refers to the instance of a GUI component, the fader should fade-in or fade-out within the Owner component.

This variable is initialized automatically just in the moment the fader is scheduled for its execution. You never need to explicitly modify this variable. This variable is intended to be used in the implementation of overridden OnStart() and OnEnd() methods.

method bool IsFinished();

The method IsFinished() should return 'true' if the fader has finalized its fading animation and 'false' if the animation is not started or it is still in progress. This method should therefore be overridden in derived classes to evaluate the state of animation effects used inside the fader.

method void OnEnd();

The method OnEnd() is invoked automatically just in the moment, when this fader and all other faders belonging to the same fading task have signaled that they are finished with their animations. The default implementation of this method simply does nothing.

Derived classes can override this method and implement there the code to complete the animation (e.g. to remove the group from its owner after it has been faded-out, etc.). The implementation of the overridden OnEnd() method has to use the variables Group and Owner to determine on which group the fader has applied the animation. Depending on the kind of the implemented animation, the OnEnd() method can also evaluate the properties UseCurrentState, AssignFocus and RestackTopmost.

property slot OnInitialize = null;

The property 'OnInitialize' can optionally refer to a slot method to be signaled shortly before the method OnStart() of the fader is executed (thus just before the fader starts with its animation effects). In this manner the slot method can perform additional preparation or initialization steps on the fader, which are usually dynamically calculated values for the start and the end of the animation effects used within the fader.

method void OnStart();

The method OnStart() is invoked automatically just in the moment, when the fader is triggered to begin its animation. The default implementation of this method simply calls the Complete() method indicating so, that the fader is done with its work. Thereupon the next fader waiting for its execution can start.

Derived classes should override this method and implement there the code to prepare and start the desired fade-in/out animation effects. The implementation of the overridden OnStart() method has to use the variables Group and Owner to determine on which group the fader should apply the animation. Depending on the kind of the implemented animation, the OnStart() method can also evaluate the properties UseCurrentState, AssignFocus and RestackTopmost.

Please note, if there is a slot method associated to the property OnInitialize, this slot method is signaled shortly before the method OnStart() is executed given the slot method a possibility to apply more individual initialization steps on the fader just before the animation begins.

When the animation reaches its end (e.g. when the animation effects used inside the fader do terminate), your implementation of the fader should invoke the method Complete() otherwise the animation is considered as still being in progress causing other pending faders to wait.

var Core::Group Owner;

The variable 'Owner' refers to the instance of a GUI component, in context of which the fader should fade-in or fade-out the Group component.

This variable is initialized automatically just in the moment the fader is scheduled for its execution. You never need to explicitly modify this variable. This variable is intended to be used in the implementation of overridden OnStart() and OnEnd() methods.

property bool RemoveIfHidden = true;

The property 'RemoveIfHidden' controls, whether the fader should automatically remove the affected Group from its Owner at the end of a fade-out animation. In case of the fade-in animation, the property has no effect.

Usually, this property should be evaluated in the derived classes in the implementation of the overridden method OnStart() or OnEnd().

property bool RestackTopmost = true;

The property 'RestackTopmost' controls, whether the fader should automatically restack the affected Group to appear above all other sibling views within its Owner when performing a fade-in animation. In case of the fade-out animation, the property has no effect.

Usually, this property should be evaluated in the derived classes in the implementation of the overridden method OnStart() or OnEnd().

property bool UseCurrentState = true;

The property 'UseCurrentState' controls, whether the fader should determine the start condition for its animation effects from the state of the affected Group and/or Owner as they are just in the moment when the fader starts with the animation effects. In this manner, the state of the affected Group can change smoothly without experiencing any abrupt alternations.

Usually, this property should be evaluated in the derived classes in the implementation of the overridden method OnStart() or OnEnd().

property bool Visible = true;

The property 'Visible' determines, whether the affected GUI component Group is visible or not after the fader has finalized the transition. If this property is 'true', the component will be shown (or it will remain visible) in context of the Owner GUI component. This corresponds to the fade-in transition. If this property is 'false', the component will disappear from its actual owner (or it will remain invisible if it is already hidden). This corresponds to the fade-out transition.