About the Ui

As explained in getting started, Ui is an opaque abstraction over the GUI. The controls implementation (methods, callbacks, creation, destruction) are therefore hidden behind generic interfaces. Anything that touches the GUI must be done though the this object.

Usage

An ui is created using the new() -> Ui<ID> constructor.

About the IDs
Ui objects use a generic type ID to expose the created controls to the user. The type choice is left to the developer, but it must implement the Eq+Clone+Hash traits. It is a good idea to use a simple type that don't need to be instanced (ex: u32, &'static str, customs enums) to keep the code clean because the IDs will be used all over the place when interacting with the GUI.

Ids are used to identify controls and events callback. Every control ID defined in a UI must be unique This means that if your iterface has 100 controls, it must define 100 IDS.

Rules over callback IDS are much more lenient: Two events callback of the same type on the same control cannot have the same identifier. Duplicate are possible in any other combinations (ex: two different events on the same control can have a callback named "foo")

Freeing
Once the Ui goes out of scope, all its controls are removed (see 3.2. Control templates ). The removed callbacks are still called.

Failures
The constructor cannot fail.

Example:
let mut ui: Ui<u32> = Ui::new();

Special Behaviour


Multithreading
The object is single threaded. This is a system restriction, and it will not go away. Nothing stops you to to create a different UI on each thread though (NOT TESTED).

Single threaded limitation
For now, there can only be one Ui object per thread. Technically, it could be possible to have multiple UI with the same ID type on the same thread, but it's not offically supported yet (please don't do it).
Trying to create multiple Ui with different ID type per thread will most likely crash your application fast.

Support for multiple UI on the same thread is a feature I'd like to implement in the BETA release. NWG currently lacks encapsulation and this could resolve this issue.