Using timers and animation effects: Change bool

The Mosaic class Effects::BoolEffect implements an animation object specialized to toggle between two bool key values. This so-called Change bool Effect can be used to enrich your GUI component with animations, in particular to control the properties of views embedded within the GUI component. At the runtime, the Effect object modifies the property with values toggled between the specified key values. For example, you can flash an Image view by simply animating its property Visible.

If you don't intend to connect the Effect with a property, you can connect it with a slot method and implementing it control the views within your GUI component more flexibly. Additionally you can precisely configure the timing behavior of the animation, in particular its duration and the number of repetitions.

The following sections are intended to provide you an introduction and useful tips of how to work with the Change bool Effect object. For the complete reference please see the documentation of the Effects::BoolEffect class.

Please note, that this Effect object is optimized to handle with bool values only. Other data types are supported by the Effects Change int32, Change float, Pulse color, Move point and Move and resize rect.

Add new Animation Effect object

To add a new Animation Effect object just at the design time of a GUI component do following:

First ensure that the Templates window is visible.

In Templates window switch to the folder Effects.

In the folder locate the template Change bool.

Drag & Drop the template into the Composer window:

Eventually name the new added Effect object.

Inspect the Animation Effect object

As long as the Effect object is selected you can inspect and modify its properties conveniently in the Inspector window as demonstrated with the property Enabled in the screenshot below:

This is in so far worth mentioning as all following sections describe diverse features of the Effect object by explicitly referring to its corresponding properties. If you are not familiar with the concept of a property and the usage of Inspector window, please read first the preceding chapter Compositing component appearance.

Specify the key values for the transition

The Effect object describes the animation as a transition between two predetermined key values. For example, a simple effect to show a view could be configured as transition between the key value false and true. The following figure demonstrate the idea of key values. Please note, that being based on a bool data type, the Effect object can't interpolate between the key values. It can assume either false or true only:

To specify the key values the Effect object provides the properties Value1 and Value2. Under normal circumstances, the property Value1 determines the value at the begin of the transition. In turn, Value2 determines the value at its end. Accordingly, to implement the above mentioned simple example to show a view you have to initialize the property Value1 with false and Value2 with true.

Connect the Animation Effect with a property to animate

The Animation Effect implements an interface for easy coupling it with a property you want to animate at the runtime. In this manner the Effect object is able to access and directly modify the property without the need that you write a single line of code. This convenient approach, however, is limited to one property. If you want multiple properties being toggled, it would be recommended to use the Timer object for this purpose.

The connection is established by initializing the Effect's property Outlet with a reference to the property you in fact intend to animate. The reference is built by prefixing the name of the desired property with a reference operator ^. For example, if you want the Animation Effect to control the Visible property of a Text view named Message, you have to initialize Outlet with the expression ^Message.Visible as shown in the screenshot below. Please note, that using the Inspector Assistant you can conveniently select the right property:

Once initialized Outlet with a reference to the desired property and the Animation Effect is started, the affected property is modified every time the Effect toggles between the specified key values. You can imagine, in this manner using the reference the Effect object can control the property remotely.

IMPORTANT

The Change bool Effect can be connected only with a property declared with bool data type. Trying to initialize Outlet with a reference to a property of other data type will lead to Chora compilation errors.

The following example demonstrates how simple it is to connect the Change bool Effect with a property in order to flash a view:

DOWNLOAD EXAMPLE

Please note, the example presents eventually features available as of version 8.10

Start, stop and restart the animation

Per default, new added Effect objects are inactive. To start the Effect you have to set its property Enabled to the value true. Setting this property to the value false stops and resets an active Effect object again. When you have configured this property with the value true already at the design time in the Inspector window, the Effect will start immediately as soon as the GUI component, this Effect belongs to, is instantiated.

Sometimes it is necessary to reset and restart an already active Effect object. For this purpose you simply set its property Enabled to the value false and then again to the value true as demonstrated in the Chora code below:

// If the effect is already active, stop and reset it now.
// If the effect was inactive, nothing will happen.
Effect.Enabled = false;

// Then start the effect again.
Effect.Enabled = true;

You can start and stop the Effect object also by sending signals to its corresponding slot methods StartEffect and StopEffect. This results in the same operation as if the property Enabled were set true or false. The additional slot methods are convenient when you intend to chain several Effect objects together.

Specify the duration of the animation

The Effect class implements various properties permitting you to precisely configure the course of the animation. The first and most important is the property CycleDuration. With it you specify how long should the animation take for the transition between the start and the end key values. This property is expressed in milliseconds. For example, when you initialize CycleDuration with the value 250 and you start the animation, the transition will take 250 milliseconds.

With the property InitialDelay you can specify an additional delay to wait before the animation may begin with its first transition. This value is expressed again in milliseconds. Accordingly, initializing InitialDelay with 1000 will cause the Effect object just after it has been activated to pause for 1000 milliseconds before the transition begins.

Per default, as long as an Effect object is enabled, its transition is repeated endlessly. In other words, after the transition has reached the end value, the animation starts again with the start value. This can be controlled more exactly by modifying the property NoOfCycles. Initializing this property with the value 4 will cause the animation to repeat the transition four times. Afterwards the animation stops and deactivates itself. Accordingly, if you want to limit the animation to a single run, you have to initialize NoOfCycles with the value 1. Initializing NoOfCycles with 0 (zero) restores the default behavior of the transition being repeated endlessly.

Being based on a bool data type, the Effect object can assume only false and true without any values lying in between. Therefore, when the animation is configured to repeat the transition, it is appropriate to specify an additional delay to pause the animation after one transition is finished and the next following begins. For this purpose initialize the property InterCycleDelay with the desired delay expressed in milliseconds. For example, initializing InterCycleDelay with the value 100 will cause the animation to pause between two consecutive transitions for 100 milliseconds.

Although the properties CycleDuration, InitialDelay and InterCycleDelay accept values expressed in milliseconds, the actual precision of an Effect object depends on the resolution of the hardware available in the particular target device.

The following figure demonstrates the effect of the just described properties. Here the animation is configured to repeat the transition 3 times before it stops:

The following example contains an Effect object configured to repeat the transition three times in total as demonstrated in the figure above:

DOWNLOAD EXAMPLE

Please note, the example presents eventually features available as of version 8.10

Implement the OnFinished slot method

If your application requires to react to the end of the animation, you can implement a slot method and connect it with the Effect object by assigning the method to its property OnFinished. As soon as the animation has reached its end position, the Effect object will send a signal to this slot method. Thereupon, the method can complete the operation. The following steps describe how to do this:

First add a new slot method to your GUI component.

Assign the slot method to the property OnFinished of the Effect object.

Open the slot method for editing.

In the Code Editor implement your desired functionality to perform at the end of the animation.

For example, it is sometimes necessary to suppress user inputs when activating an animation in order to avoid eventual interferences. With the OnFinished slot method you can restore the event handling again as soon as the animation is done. The following example implements this approach:

DOWNLOAD EXAMPLE

Please note, the example presents eventually features available as of version 8.10

Please note, if the Effect object is configured to run an endless animation, the animation will never stop as long as it is active. In such case, the slot method associated to the property OnFinished will never receive a signal.

Chain several Animation Effects together

With the above described OnFinished property it is easy to combine several Animation Effects together so that the end of one animation causes another one to be activated automatically. In principle, you can chain as many Effect objects together as your application case requires, creating in this manner complex animation sequences.

To chain two Effect objects, you assign the StartEffect slot method of one Effect object to the OnFinished property of another object. The following example demonstrates this application case with six Effect objects, configured to mutually activate each other:

DOWNLOAD EXAMPLE

Please note, the example presents eventually features available as of version 8.10

Animation Effects and Garbage Collection

When a GUI component is discarded, all active Animation Effect objects existing inside it are automatically disabled. In other words, you don't need to worry about active effects. They never prevent the components from being reclaimed by the Garbage Collector.

Animation Effects and user interaction

Per default, while an Animation Effect is running, the application will continue processing all user inputs. This means in particular, that the user can unhamperedly interact with the application while e.g. an indicator GUI component is blinking or a list scrolls its contents.

This, however, is not always the desired behaviour. You can imagine the situation of an Effect object used to drive a transition between two GUI components (e.g. to fade-in a new screen while the old screen is faded-out). In the short time while the transition is active the both components are (partially) visible and their functionality is eventually accessible for the user.

Touching the screen or pressing a key on a real keyboard while such transition is in progress may cause the involved GUI components to unexpectedly start operations, which then can interfere with the just active transition. In worst case, the entire application can enter in an incoherent state preventing the user from being able to continue working with the application.

In order to protect your application from such critical situations, the application component provides two methods BeginAnimation and EndAnimation. Invoking the method BeginAnimation suppresses temporarily the entire application from being able to handle user inputs. Invoking EndAnimation restores this ability again.

In practice, you invoke the method BeginAnimation just in moment your implementation starts the Effect to drive a critical animation. From now, the application will ignore user inputs. Later at the end of the animation, you invoke the method EndAnimation, which on its part re-enables the event handling again. With the method GetRoot you can obtain access to the application component. For example:

// Just in the moment you start an animation ....
SomeEffect.Enabled = true;

// ... suppress the event handling
GetRoot().BeginAnimation();

[...]

// Later, when the animation is done you restore the event handling again
GetRoot().EndAnimation();

Internally the both methods do manage a counter, which is incremented with every BeginAnimation invocation and decremented with every invocation of EndAnimation. As long as the value of the counter is greater than 0 (zero) the event handling is suppressed. Thus, if you are starting several Animation Effects, you can invoke BeginAnimation for every started Effect and EndAnimation for every ended Effect. As soon as all Effects are done, the event handling is re-enabled.