Skip to content

Commit 17449db

Browse files
NoraCodesNoraCodes
authored
Merge pull request #31 from LeoTindall/lt-fix-doc-readme-examples
Improve introductory documentation
2 parents 8413e1d + e2ef5d7 commit 17449db

File tree

2 files changed

+25
-85
lines changed

2 files changed

+25
-85
lines changed

‎README.md

Lines changed: 17 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -9,16 +9,9 @@ iui: [![iui crates.io version badge](https://img.shields.io/crates/v/iui.svg)](h
99
ui-sys: [![ui-sys crates.io version badge](https://img.shields.io/crates/v/ui-sys.svg)](https://crates.io/crates/ui-sys/)
1010
[![docs.rs for ui-sys](https://docs.rs/ui-sys/badge.svg)](https://docs.rs/ui)
1111

12-
`iui` is a simple, small, easy to distribute GUI library, a Rusty user interface library that binds to platform native APIs.
13-
These are work-in-progress bindings to the minimalistic native UI library [libui](https://github.com/andlabs/libui) via the `ui-sys` bindings crate.
12+
`iui` is a **simple** (about 4 kLOC of Rust), **small** (about 800kb, including `libui`), **easy to distribute** (one shared library) GUI library, providing a **Rusty** user interface library that binds to **native APIs** via the [libui](https://github.com/andlabs/libui) and the `ui-sys` bindings crate.
1413

15-
`libui` is a wrapper library for native(ish) GUI libraries:
16-
17-
* Win32API on Windows
18-
* Cocoa on Mac OS X
19-
* GTK+ on Linux and elsewhere
20-
21-
This library exposes a Rusty procedural interface to the "Least Common Denominator" of GUI widgets.
14+
`iui` wraps native retained mode GUI libraries, like Win32API on Windows, Cocoa on Mac OS X, and GTK+ on Linux and elsewhere. Thus all `iui` apps have a native look and feel and start from a highly performant base which is well integegrated with the native ecosystem on each platform. Because it implements only the least common subset of these platform APIs, your apps will work on all platforms and won't have significant behavioral inconsistencies, with no additional effort on your part.
2215

2316
## Using
2417

@@ -28,70 +21,27 @@ Add `iui` to your project with:
2821
iui = "0.3"
2922
```
3023

31-
We have documentation on [docs.rs](https://docs.rs/iui) for released versions and on [github](https://leotindall.github.io/libui-rs/iui/index.html) for master.
24+
Then, in your code, all you have to do is:
3225

26+
1. create a [`UI`](https://docs.rs/iui/*/iui/struct.UI.html#method.init) handle, initializing the UI library and guarding against memory unsafety
27+
1. make a [window](https://docs.rs/iui/*/iui/controls/struct.Window.html), or a few, with title and platform-native decorations, into which your app will be drawn
28+
1. add all your [controls](https://docs.rs/iui/*/iui/controls/index.html), like buttons and text inputs, laid out with both axial and grid layout options
29+
1. implement some [callbacks](https://docs.rs/iui/*/iui/controls/struct.Button.html#method.on_clicked) for user input, taking full advantage of Rust's concurrency protections
30+
1. call [`UI::main`](https://docs.rs/iui/*/iui/struct.UI.html#method.main), or take control over the event processing with an [`EventLoop`](https://docs.rs/iui/*/iui/struct.EventLoop.html), and voíla! A GUI!
3331

32+
Or, you can track the `master` branch, which may be broken and whose API often changes, with:
3433

35-
## Example
34+
```toml
35+
iui = { git = "https://github.com/leotindall/libui-rs/iui" }
36+
```
37+
38+
We have documentation on [docs.rs](https://docs.rs/iui) for released versions and on [github](https://leotindall.github.io/libui-rs/iui/index.html) for master.
39+
40+
## Examples
3641

3742
![Three example GUI applications running on Linux](themed.png)
3843

39-
```rust
40-
extern crate iui;
41-
use iui::prelude::*;
42-
use iui::controls::{Label, Button, VerticalBox, Group};
43-
44-
fn main() {
45-
// Initialize the UI library
46-
let ui = UI::init().expect("Couldn't initialize UI library");
47-
// Create a window into which controls can be placed
48-
let mut win = Window::new(&ui, "Test App", 200, 200, WindowType::NoMenubar);
49-
50-
// Create a vertical layout to hold the controls
51-
let mut vbox = VerticalBox::new(&ui);
52-
vbox.set_padded(&ui, true);
53-
54-
let mut group_vbox = VerticalBox::new(&ui);
55-
let mut group = Group::new(&ui, "Group");
56-
57-
// Create two buttons to place in the window
58-
let mut button = Button::new(&ui, "Button");
59-
button.on_clicked(&ui, {
60-
let ui = ui.clone();
61-
move |btn| {
62-
btn.set_text(&ui, "Clicked!");
63-
}
64-
});
65-
66-
let mut quit_button = Button::new(&ui, "Quit");
67-
quit_button.on_clicked(&ui, {
68-
let ui = ui.clone();
69-
move |_| {
70-
ui.quit();
71-
}
72-
});
73-
74-
// Create a new label. Note that labels don't auto-wrap!
75-
let mut label_text = String::new();
76-
label_text.push_str("There is a ton of text in this label.\n");
77-
label_text.push_str("Pretty much every unicode character is supported.\n");
78-
label_text.push_str("🎉 用户界面 사용자 인터페이스");
79-
let label = Label::new(&ui, &label_text);
80-
81-
vbox.append(&ui, label, LayoutStrategy::Stretchy);
82-
group_vbox.append(&ui, button, LayoutStrategy::Compact);
83-
group_vbox.append(&ui, quit_button, LayoutStrategy::Compact);
84-
group.set_child(&ui, group_vbox);
85-
vbox.append(&ui, group, LayoutStrategy::Compact);
86-
87-
// Actually put the button in the window
88-
win.set_child(&ui, vbox);
89-
// Show the window
90-
win.show(&ui);
91-
// Run the application
92-
ui.main();
93-
}
94-
```
44+
Check out the [`examples/`](https://github.com/LeoTindall/libui-rs/tree/0.3.0/iui/examples) directory from the latest release for these examples and more.
9545

9646
## Organization
9747

‎iui/src/lib.rs

Lines changed: 8 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -1,28 +1,18 @@
1-
//! `iui`, the `i`mproved `u`ser `i`nterface crate, provides Rust bindings to `libui`, a wrapper library for native(ish) GUI libraries:
2-
//!
3-
//! - Win32API on Windows
4-
//! - Cocoa on Mac OS X
5-
//! - GTK+ on Linux and elsewhere
6-
//!
7-
//! This library exposes a Rusty procedural interface to the
8-
//! "Least Common Denominator" of GUI widgets. They are all available on all supported platforms, though some functionality may not
9-
//! perform precisely the same on all platforms. These inconsistencies are marked.
1+
//! `iui`, the `i`mproved `u`ser `i`nterface crate, is a **simple** (about 4 kLOC of Rust), **small** (about 800kb, including `libui`), **easy to distribute** (one shared library) GUI library, providing a **Rusty** user interface library that binds to **native APIs** via the [libui](https://github.com/andlabs/libui) and the `ui-sys` bindings crate.
2+
//! `iui` wraps native retained mode GUI libraries, like Win32API on Windows, Cocoa on Mac OS X, and GTK+ on Linux and elsewhere. Thus all `iui` apps have a native look and feel and start from a highly performant base which is well integegrated with the native ecosystem on each platform. Because it implements only the least common subset of these platform APIs, your apps will work on all platforms and won't have significant behavioral inconsistencies, with no additional effort on your part.
103
//!
114
//! To use the library, add the following to your `Cargo.toml`:
125
//!
136
//! ```toml
147
//! "iui" = "0.3"
158
//! ```
169
//!
17-
//! Most of the functionality of the crate is exposed via the [UI](struct.UI.html) RAII guard, which handles all initialization and cleanup for the
18-
//! underlying library.
19-
//!
20-
//! After initialization, all the functionality used for creating actual UIs is in the [`controls`](controls/index.html) module.
21-
//!
22-
//! Fine-grained control of the event loop is avilable via the [`EventLoop`](struct.EventLoop.html) struct.
23-
//! Be aware the Cocoa (GUI toolkit on Mac OS) requires that the _first thread spawned_ controls
24-
//! the UI, so do _not_ spin off your UI interactions into an alternative thread. You're likely to
25-
//! have problems on Mac OS.
10+
//! To build a GUI app with `iui`, you must:
11+
//! 1. create a [`UI`](https://docs.rs/iui/*/iui/struct.UI.html#method.init) handle, initializing the UI library and guarding against memory unsafety
12+
//! 1. make a [window](https://docs.rs/iui/*/iui/controls/struct.Window.html), or a few, with title and platform-native decorations, into which your app will be drawn
13+
//! 1. add all your [controls](https://docs.rs/iui/*/iui/controls/index.html), like buttons and text inputs, laid out with both axial and grid layout options
14+
//! 1. implement some [callbacks](https://docs.rs/iui/*/iui/controls/struct.Button.html#method.on_clicked) for user input, taking full advantage of Rust's concurrency protections
15+
//! 1. call [`UI::main`](https://docs.rs/iui/*/iui/struct.UI.html#method.main), or take control over the event processing with an [`EventLoop`](https://docs.rs/iui/*/iui/struct.EventLoop.html), and voíla! A GUI!
2616
//!
2717
//! For code examples, see the [examples](https://github.com/LeoTindall/libui-rs/blob/master/iui/examples/)
2818
//! directory.

0 commit comments

Comments
 (0)