Unbound optional parameters

TGUI 0.7 is no longer supported, use a newer TGUI version instead.

In the introduction to signals you have seen how to bind parameters to the functions. However, sometimes you want your function to have parameters which are filled with information about the widget (e.g. on which coordinate the click occured). You can do this with what I call the "optional parameter system".

How this system works is explained below, but it has one big downside that you should first know about: only compilers with good c++11/14 support can use it. Only the following compilers are supported:

So if you are using an older version of these compilers, then you must use the alternative connectEx function. This connectEx function will use the Callback class like the old callback system did and will work on all compilers that TGUI supports. It is however slightly limited compared to the optional parameter system.

The optional parameter system

In the introduction you have seen the following code:

void function();
button->connect("pressed", function);

If your compiler supports this optional parameter system, the function can actually have a parameter. The "pressed" signal also sends the text of the button with it. The 'function' could actually be defined as any of the following, while the call to the 'connect' function remains identical.

void function();
void function(std::string);
void function(const std::string&);
void function(sf::String);
void function(const sf::String&);

As you can see there is some variety of what type this string parameter has. The signal sends a "const sf::String&", but you can use any type to which this can be converted.

Lets look at another example. The "checked" and "unchecked" signals from Checkbox will pass a boolean as parameter. This parameter is always true for the "checked" signal and always false for the "unchecked" signal, but that allows this code:

void function(bool checked)
{
    std::cout << "Checked? " << std::boolalpha << checked << std::endl;
}
checkbox->connect("checked unchecked", function);

What about the bound parameters?
This system is all about unbound parameters. If your function takes one parameter, and you provide one extra parameter to the connect function, then that parameter is bound like shown in the introduction. However, if your function takes two parameters then one parameter is unbound and the system will try to bind it with information about the signal. Here the function will be called with a reference to the Gui object that you provided and the coordinate of the mouse click which the system provided.

void function(tgui::Gui& gui, sf::Vector2f mousePos);
picture->connect("clicked", function, std::ref(gui));

If you are wondering which optional parameters the system can provide for the signal, you should check the documentation of the widget.