Crate droom_ui

IUP

IUP is a multi-platform toolkit for building graphical user interfaces.

IUP's purpose is to allow a program to run in different systems without changes - the toolkit provides the application portability. Supported systems include: GTK+, Motif and Windows.

IUP has some advantages over other interface toolkits available:

• Simplicity: due to the small number of functions and to its attribute mechanism, the learning curve for a new user is often faster.
• Portability: the same functions are implemented in each one of the platforms, thus assuring the interface system's portability.
• Customization: the dialog specification language (LED) is a mechanisms in which it is possible to customize an application for a specific user with a simple-syntax text file.
• Flexibility: its abstract layout mechanism provides flexibility to dialog creation.
• Extensibility: the programmer can create new interface elements as needed.

The Rust Binding

The Rust binding provides a way to do things in a more Rustic way but without moving out of IUP base nameclatures and philosophy in such a way that one can program on this binding by reading the original IUP documentation.

Everything created by IUP is so called a element which imeplements the Element trait. Each of those objects can also be encapsulated in a Handle element which contains the common functionalities and allow downcasting back to the original element type.

The library is divided in a few submodules in a way that it matches the IUP documentation division of elements:

• The controls submodule contains the user interface controls.
• The layout submodule contains the abstract layout composition controls.
• The dialogs submodule contains the dialog definitions, such as windows, message boxes, file selection, color selection between others.

Each of those elements communicates with the programmer by the means of callbacks and attributes. Callbacks are closures that gets called when something happens with the control such as a button click and attributes are the way to set and get specific properties of the element such as it's design or value.

Currently attributes are not individual methods specific to each element but that may be a thing in the future.

The binding is built in a way one can build controls or even the entire window of the application in a single expression in a very expressive way, for example:

Dialog::new(
    Radio::new(
        VBox::new(elements![
            Toggle::with_title("Option 1")
                    .set_attrib("TIP", "I am a tip!")
                    .set_attrib("VALUE", "ON")
                    .set_action(|(_, state)| println!("Option 1 = {}", state)),
            Toggle::with_title("Option 2")
                    .set_action(|(_, state)| println!("Option 2 = {}", state))
                    .set_valuechanged_cb(|_| println!("Option 2 changed!!!")),
        ])
    )
).set_attrib("TITLE", "Hello IUP!")
 .show();

This is just a example of one of the many ways one could build the GUI creation code, this model opens a lot of possibilities on this matter. There's also the possibility to use the LED file format and allow users to easily modify the user interface with no programming experience.

Ownership

IUP have a few ownership restrictions, the library owns most of the elements it creates. That unfortunately means the Rust ownership semantics are a bit useless on IUP and thus all elements are Copyable.

The following elements are automatically destroyed when IUP closes:

• All the dialogs and all of it's children widgets.
• Any element associated with a handle name (as set by LED, Element::add_handle_name, or implicitly by Element::set_attrib_handle).

The user is also able to destroy elements manually by calling Element::destroy, one should make sure such element does not have other references to it wandering in the code.

From looking on the above auto-destroy rules, the following are the cases of elements that must be destroyed manually:

• Dettached widgets with no handle name.
• Images not associated with any widget and thus no handle name.
• Resources with no handle name — usually timers, clipboards, popup menus, config and user elements.

To help on the task of destroying those mentioned cases, the Guard type is available to provide some kind of RAII to them. This type wrapper automatically destroys the wrapped element when it gets out of scope. Please refer to its documentation for more details.

UTF-8

By default in C, IUP uses strings in the current locale, IUP-Rust enables the UTF-8 mode of IUP to conform with Rust string standards, thus both UTF8MODE and UTF8MODE_FILE attributes are enabled by default in IUP-Rust.

Reexports

pub use element::Element;

pub use element::Handle;

pub use element::Guard;

Modules

callback	Event-driven communication.
clipboard	Access to the system clipboard.
control	See IUP Controls.
dialog	See IUP Dialogs.
element	Common operations between objects.
image	Image elements to be embedded in other controls.
layout	See the Layout Composion Guide and the Layout Guide.
led	LED (Dialog-specification language) functionalities.
prelude	The IUP-Rust Prelude.
timer	Timer to periodically execute an action.

Macros

elements	Makes a Vec of Element trait objects.
pixels	This macro is meant to represent expressively pixels of a image.

Enums

InitError
Orientation

Functions

version	Returns a string with the IUP version number.
version_number	Returns a number indicating the IUP version.
with_iup	Initializes IUP toolkit, calls f for user initialization and runs the application.