Fading Gui Controls

01 Oct 2016 . category: tech .Comments

Subtle fading effects go a long way in improving the aesthetics of a gui and we wanted to take advantage of this effect in Torque for image and button guis. As of this writing, about the only way to manipulate fading using stock Torque is to set up schedules in script to adjust alpha values. It works but is prone to performance issues, especially with multiple schedules being called simultaneously - in addition to any other game code or scripts that may be running.

To alleviate this, it was decided that some research into implementing a C++ solution was in order. I found a resource from 2005 by Jeff “Ddraig Goch” Parry. Just wanted to give reference to Jeff’s work, although the garagegames.com site reports not safe as of late. I’m not certain what the issue is with the site’s certificate, but the original resource was at the old GarageGames forums posted as “Fading Transparent Bitmap Control”.

Although this resource works, we needed support for some other types of gui controls to fade as well. Also any visible child controls would not fade with the parent control. This would lead to things like a background image disappearing but the text inside still being there.

The timing and core fading implementation was good, so we kept that aspect of the resource intact. The wakeTime, fadeinTime, and fadeoutTime fields and usage were left as they were. Just about everything else was replaced. Functions were implemented that internally update the states of the controls and support for child controls was added.

I originally updated this resource to work with Torque around the version 3.5-ish era. As the needs of our prototypes grew, I ended up expanding the resource to create a new ‘fading’ subset of gui controls. This gave birth to the 'guiFadingControls.h' file. This file is just a shared header file that sets up the includes and initializes a shared enumerator. This enum is used to facilitate ‘states’ for the new fading gui controls. These states are handled internally and aren’t directly manipulated from script.


Standalone : One main advantage of the update is it leaves the existing GuiBitmapCtrl class untouched. This enabled us to just add a new '\fading' directory, drop in the new 'guiFadingControls.h' file, and build new fading gui controls that would all call to #include the new header file.

Includes Children : The rendering code for each control has been extended to support the fading out of child gui controls.

States : We added 3 states for each new control: idle, fadingIn, and fadingOut. These are used internally and aren’t really directly called by script. They are, however, indirectly called by the new script functions if the right conditions are met. All of this ends up making the fading of the controls easier to initialize and use from script than before. Prior to this extension, I would find myself having to supplement a lot of my scripts with additional calls to setVisible(), etc. in order to get the desired results.

New Classes: Currently we have added 3 classes that support fading using custom rendering code. Each class required minor adjustments to the rendering code and, while the option of expanding the core ‘guiControl’ class was explored, ultimately we found it simpler to just write each custom rendering function per class. Altering the core guiControl class was just too messy, creating additional fields for all gui controls edited or saved in the Gui Editor.

Additional Fields : 6 fields were added to each fading gui control to facilitate the fading operation: wakeTime, fadeinTime, fadeOutTime, alpha, mode, and fadeInOnWake. The GuiFadingButtonCtrl has one additional field: fill. This optional variable enables or disables the filling of the background and border.

Console Methods : Each class supports fading in/out of the control on the canvas via 2 added console methods: fadeIn() and fadeOut().

New Classes

• GuiFadingBitmapButtonCtrl : Gui button control with an image that will fade in and out.

• GuiFadingBitmapCtrl : Gui control with an image that will fade in and out. Includes child controls.

• GuiFadingButtonCtrl : Gui button control that will fade in and out. Only for buttons with no image, using profiles to ‘fill’ the color and borders.


The Fading Gui Controls on GitHub:

Fading Gui Controls


Source Code:

1 - Create a new directory "source\gui\fading\".
2 - Copy the provided source files into the new directory.
3 - Open your project and add the new 'fading' filter under "torque3d\gui\" to mirror the new directory.
4 - Right-click the new 'fading' filter and choose ‘Add Existing Item’ from the dropdown. Go ahead and add each of the 4 new source files.
5 - Recompile. A successful install will allow the new classes to be used and their fadeIn() and fadeOut() functions called from script.


To use this resource from script you just need to understand how the added fields work. The fadeinTime and fadeoutTime are pretty self-explanatory - just tinker with these to get the transition time right ( ms ).

The alpha field can be set to a value from 0 to 255 ( 0 = transparent ).

The mode field can be set to a value from 0 to 2 ( 0 = idle, 1 = fadingIn, 2 = fadingOut ). This is manipulated internally and isn’t exposed to script.

The fadeInOnWake field is a bool value of whether or not the control should fade in when the control’s onWake() is called.

Fading on Wake

When used together, these fields can cater to quite a few different scenarios. By default, the controls behave like the gui control from which they are inherited. i.e. The guiFadingBitmapCtrl acts just like the guiBitmapCtrl unless it is told to do otherwise. The most common use of the fading controls is to have the control fade in automatically, as soon as it is added to the canvas. For this behavior the fields could be set as follows:

alpha = 0; // Transparent to start.
fadeInOnWake = 1; // Anytime the control wakes, call fadeIn().

Fading Out

Once a control is faded in, you might want to fade it back out at some point. To do this, you would leave the fields alone since they are for initialization and waking of the control. Instead you could call the script function:

MyFadingControl.fadeOut(); // Call the console command.


If you want a button that doesn’t use any image but still want the button to support fading, use this class. This class adds one extra field: fill. This field will enable/disable the filling of the profile’s background color. This is useful if you wanted to make a button that is only text with a transparent background. For a text-only button like this to fade in automatically, the fields would look like this on the control:

fill = 0; // Don't fill the background color.
alpha = 0; // Transparent to start.
fadeInOnWake = 1; // Anytime the control wakes, call fadeIn().