The Ui
As seen in getting started, the Ui is a HashMap-like container that manages a set of control, resources and user values. Any action that touch a GUI pass through the Ui object
A Ui object is created using the
Ui::new
. If, for any reason, the library fails to allocate the system resources required to the Ui object, a
nwg::constants::Error
will be raised. Also, the Ui requires a type
ID
for its keys.
let ui: Ui<usize> = Ui::new().expect("Ui creation failed");
In a Ui object, components are identified by a
unique ID. The type of the ID is defined by the user when the Ui is first defined. The ID type must implement the
Hash+Clone
traits. Chances are, the ids will be referenced
alot in the UI code (for borrowing controls for example), as such small types that can be hidden
behind a
const
are preferred (example:
&'static str
,
u64
, or maybe enums).
Ids are only required to be unique within the UI. For example, two Uis can have a control identified by
"foo"
.
Some NWG ui commands (such as
pack_control
and
bind
) wont be executed right away. Many of these commands are used when initializing a UI and, under these conditions,
they should never fail. Validating each of them individually would be annoying so the validation is executed when
commit
is called.
When
commit
is called, only NWG custom messages are touched. Any other messages ( ex:
WM_KEYPRESS
) will be ignored.
If a nwg command fails in a commit, commit will
immediatly return the error that was raised and will stop the execution of any other waiting command.
Finally, because NWG custom commands are just like any other Windows message, they will be executed normally in the event loop. If a command fails under these circumstances,
the errors will be ignored (might be a good idea to log them somewhere though).
The Ui has some functions to probe its resources and controls.
Can be used to check whether the Ui has an object identified by a key.
let found: bool = ui.has_id(&"AButton");
Can be used to retrieve the low level handle (ex:
HWND
) of a control. Will return an error if the ID do not exists in the UI, if the ID identify a user value
or if the control is borrowed.
While the function is
not marked as unsafe, anything done to the handle will most likely be. The handle is returned in a
nwg::custom::AnyHandle
enum.
if let Ok(AnyHandle::HWND(handle)) = ui::handle_of(&"MyButton") {
...
}