Events
Whenever a user interacts with a control, an event might be triggered (ex: when a someone clicks on a button). Events
can have associated callbacks which will be executed when the event is triggered.
The callback signatures must match the
EventCallack
type. Because of this, a single callback can
be bound to multiple events or controls.
The api documentation list the supported events of each control under their template documentation.
Unstable warning: currently, events are listed in a enum. This method is a bit too restrictive so the enum will likely become a module. Most of the changes
will happen under the hood and won't affect the events interface in any major way.
Binding a callback to a control event is done using the
bind
method. Here's its signature:
bind(&Control_ID, &Event_ID, Event, Callback)
where
•
Control_ID
Is an ID identifying the control
•
Event_ID
Is an ID to indentify the callback
•
Event
Is a NWG event
•
Callback
Can be a function or a closure.
There are no limits to the number of callbacks bound to a control events.
The command is not executed right away. Use
commit
to force the execution. The command can fail due to
many reasons. See the api documentation of the method for the details.
ui.bind(&"HelloButton", &"SaySomething", Event::Click, |ui,_,_,_| {
if let Ok(your_name) = ui.get::<nwg::TextInput>(&"YourName") {
simple_message("Hello", &format!("Hello {}!", your_name.get_text()) );
} else {
panic!()
}
});
In order to remove a callback from an event, the
unbind
method must be used. Here's its signature:
unbind(&Control_ID, &Event_ID, Event)
where
•
Control_ID
Is an ID identifying the control
•
Event_ID
Is an ID identifying the callback
•
Event
Is a NWG event
The command is not executed right away. Use
commit
to force the execution. The command can fail due to
many reasons. See the api documentation of the method for the details.
ui.unbind(&"HelloButton", &"SaySomething", Event::Click);
Once the Ui initialization is done, the threads needs to listen to the system events. In order to do that the
dispatch_events
function must be used. The method will dispatch the events to
every instanced UI. As soon as a main window is closed (
exit_on_close
set to true) or if
nwg::exit
is called, the function will return.
It is possible to manually trigger a control event using the
trigger(&ControlID, Event, EventArg)
method. The primary purpose of this function is to test the application callbacks.
The action is not executed right away;
commit
must be used to force the execution.
Note that using this method allows the programmer to send ANY kind of event arguments. NWG will never panic
because of this, but the programmer callbacks can.
ui.trigger(&"MyWindow", Event::MouseDown, EventArgs::None);