Add documentation and examples

Author: NoraCodes

ui/examples/basic.rs

@@ -0,0 +1,57 @@
+extern crate ui;
+use std::rc::Rc;
+use ui::{Window, BoxControl, Button};
+
+fn main() {
+    // Start up the UI toolkit
+    ui::init(ui::InitOptions);
+
+    // Create a new window, 200x100, titled "Test Window"
+    // and put it in an Rc so it can be passed into callback functions.
+    let main_window = Rc::new(Window::new("Test App", 200, 100, true));
+
+    // Add margins around the edge of the window, making it look much nicer.
+    main_window.set_margined(true);
+
+    // Adding this callback means that when this window closes, the `ui::main` function returns.
+    // This should be added to the primary window of any application.
+    main_window.on_closing(Box::new(|_| {
+        ui::quit();
+        false
+    }));
+
+    // Create a button that opens a dialog box.
+    let button = Button::new("Button");
+    {
+        // Make a new Rc reference to the main window for this closure.
+        let main_window = main_window.clone();
+        // on_clicked runs the given closure when the button is clicked.
+        // A lot of widgets provide this event, or others like it.
+        button.on_clicked(Box::new(move |_| {
+            // msg_box creates a modal dialog with the given title and text
+            ui::msg_box(&main_window, "Button", "You clicked the button!");
+        }));
+    }
+
+    // Create a button that quits the app.
+    let mut quit_button = Button::new("Quit");
+    quit_button.on_clicked(Box::new(|_| { ui::quit(); }));
+
+    // Add a box to lay out controls vertically.
+    let vbox = BoxControl::new_vertical();
+    vbox.set_padded(true);
+    // Put the buttons into the vertical layout.
+    vbox.append(button.into(), false);
+    vbox.append(quit_button.into(), false);
+    // Put the vertical layout into the window.
+    main_window.set_child(vbox.clone().into());
+
+    // Set the main window (and all its widgets) to visible.
+    main_window.show();
+
+    // Run the app.
+    ui::main();
+
+    // Clean up.
+    ui::uninit();
+}

ui/examples/controlgallery.rs

@@ -10,6 +10,8 @@ fn run() {
     let menu = Menu::new("File");
     menu.append_item("Open").on_clicked(Box::new(open_clicked));
     menu.append_item("Save").on_clicked(Box::new(save_clicked));
+    menu.append_separator();
+    menu.append_quit_item();
 
     let menu = Menu::new("Edit");
     menu.append_check_item("Checkable Item");

ui/src/lib.rs

@@ -3,6 +3,65 @@
 //! Main C source repository: https://github.com/andlabs/libui
 //!
 //! Copyright © 2016 Mozilla Foundation
+//!
+//! # Example
+//! 
+//! ```
+//! extern crate ui;
+//! use std::rc::Rc;
+//! use ui::{Window, BoxControl, Button};
+//! 
+//! fn main() {
+//!     // Start up the UI toolkit
+//!     ui::init(ui::InitOptions);
+//! 
+//!     // Create a new window, 200x100, titled "Test Window"
+//!     // and put it in an Rc so it can be passed into callback functions.
+//!     let main_window = Rc::new(Window::new("Test App", 200, 100, true));
+//! 
+//!     // Add margins around the edge of the window, making it look much nicer.
+//!     main_window.set_margined(true);
+//! 
+//!     // Adding this callback means that when this window closes, 
+//!     // the `ui::main` function returns. This should be added to the 
+//!     // primary window of any application.
+//!     main_window.on_closing(Box::new(|_| {
+//!         ui::quit();
+//!         false
+//!     }));
+//! 
+//!     // Create a button that opens a dialog box.
+//!     let button = Button::new("Button");
+//!     // on_clicked runs the given closure when the button is clicked.
+//!     // A lot of widgets provide this event, or others like it.
+//!     button.on_clicked(Box::new(|_| { println!("Clicked!"); }));
+//! 
+//!     // Create a button that quits the app.
+//!     let mut quit_button = Button::new("Quit");
+//!     quit_button.on_clicked(Box::new(|_| { ui::quit(); }));
+//! 
+//!     // Add a box to lay out controls vertically.
+//!     let vbox = BoxControl::new_vertical();
+//!     vbox.set_padded(true);
+//!     // Put the buttons into the vertical layout.
+//!     vbox.append(button.into(), false);
+//!     vbox.append(quit_button.into(), false);
+//!     // Put the vertical layout into the window.
+//!     main_window.set_child(vbox.clone().into());
+//! 
+//!     // Set the main window (and all its widgets) to visible.
+//!     main_window.show();
+//! 
+//!     // ONLY for testing, quit the app as soon as it starts.
+//!     ui::quit();
+//! 
+//!     // Run the app.
+//!     ui::main();
+//! 
+//!     // Clean up.
+//!     ui::uninit();
+//! }
+//! ```
 
 #[macro_use]
 extern crate bitflags;

ui/src/menus.rs

@@ -8,27 +8,31 @@ use windows::Window;
 
 // NB: If there ever becomes a way to destroy menus and/or menu items, we'll need to reference
 // count these for memory safety.
+/// An item that goes in a [`Menu`](struct.Menu.html).
 #[derive(Clone)]
 pub struct MenuItem {
     ui_menu_item: *mut uiMenuItem,
 }
 
 impl MenuItem {
     #[inline]
+    /// Enables the item, allowing it to be selected. This is the default state of a menu item.
     pub fn enable(&self) {
         unsafe {
             ui_sys::uiMenuItemEnable(self.ui_menu_item)
         }
     }
 
     #[inline]
+    /// Disables the item, preventing it from being selected and providing a visual cue to the user that it cannot be selected.
     pub fn disable(&self) {
         unsafe {
             ui_sys::uiMenuItemDisable(self.ui_menu_item)
         }
     }
 
     #[inline]
+    /// Sets the function to be executed when the item is clicked/selected.
     pub fn on_clicked(&self, callback: Box<FnMut(&MenuItem, &Window)>) {
         unsafe {
             let mut data: Box<Box<FnMut(&MenuItem, &Window)>> = Box::new(callback);
@@ -55,13 +59,17 @@ impl MenuItem {
     }
 
     #[inline]
+    /// Returns `true` if the menu item is checked, and false if it is not checked (or not checkable).
     pub fn checked(&self) -> bool {
         unsafe {
             ui_sys::uiMenuItemChecked(self.ui_menu_item) != 0
         }
     }
 
     #[inline]
+    /// Sets the menu item to either checked or unchecked based on the given value.
+    /// 
+    /// Setting the checked value of a non-checkable menu item has no effect.
     pub fn set_checked(&self, checked: bool) {
         unsafe {
             ui_sys::uiMenuItemSetChecked(self.ui_menu_item, checked as c_int)
@@ -71,13 +79,15 @@ impl MenuItem {
 
 // NB: If there ever becomes a way to destroy menus, we'll need to reference count these for memory
 // safety.
+/// A named menu, to be displayed at the top of the application window or in the titlebar.
 #[derive(Clone)]
 pub struct Menu {
     ui_menu: *mut uiMenu,
 }
 
 impl Menu {
     #[inline]
+    /// Adds a new item with the given name to the menu.
     pub fn append_item(&self, name: &str) -> MenuItem {
         unsafe {
             let c_string = CString::new(name.as_bytes().to_vec()).unwrap();
@@ -87,6 +97,7 @@ impl Menu {
         }
     }
 
+    /// Adds a new togglable (checkbox) item with the given name to the menu.
     #[inline]
     pub fn append_check_item(&self, name: &str) -> MenuItem {
         unsafe {
@@ -98,6 +109,7 @@ impl Menu {
     }
 
     #[inline]
+    /// Adds a new item to the menu with the lable "Quit".
     pub fn append_quit_item(&self) -> MenuItem {
         unsafe {
             MenuItem {
@@ -107,6 +119,7 @@ impl Menu {
     }
 
     #[inline]
+    /// Adds a new item to the menu with the label "Preferences...".
     pub fn append_preferences_item(&self) -> MenuItem {
         unsafe {
             MenuItem {
@@ -116,6 +129,7 @@ impl Menu {
     }
 
     #[inline]
+    /// Adds a new item to the menu with the label "About".
     pub fn append_about_item(&self) -> MenuItem {
         unsafe {
             MenuItem {
@@ -125,13 +139,15 @@ impl Menu {
     }
 
     #[inline]
+    /// Adds a seperator to the menu, which will create a line in the menu.
     pub fn append_separator(&self) {
         unsafe {
             ui_sys::uiMenuAppendSeparator(self.ui_menu)
         }
     }
 
     #[inline]
+    /// Creates a new menu with the given name to be displayed in the menubar at the top of the window.
     pub fn new(name: &str) -> Menu {
         unsafe {
             let c_string = CString::new(name.as_bytes().to_vec()).unwrap();

ui/src/ui.rs

@@ -13,6 +13,7 @@ use windows::Window;
 pub struct InitOptions;
 
 #[inline]
+/// Sets up the `libui` environment. Run this prior to constructing your UI.
 pub fn init(_: InitOptions) -> Result<(),InitError> {
     unsafe {
         let mut init_options = uiInitOptions {
@@ -31,6 +32,7 @@ pub fn init(_: InitOptions) -> Result<(),InitError> {
 }
 
 #[inline]
+/// Undoes the work of [init](fn.init.html). Calling this will free all the memory used by the UI toolkit.
 pub fn uninit() {
     unsafe {
         ffi_utils::unset_initialized();
@@ -40,13 +42,15 @@ pub fn uninit() {
 }
 
 #[inline]
+/// Hands control of this thread to the UI toolkit, allowing it to display the UI and respond to events. Does not return until the UI [quit](fn.quit.html)s.
 pub fn main() {
     unsafe {
         ui_sys::uiMain()
     }
 }
 
 #[inline]
+/// Running this function causes the UI to quit, exiting from [main](fn.main.html) and no longer showing any widgets.
 pub fn quit() {
     unsafe {
         ui_sys::uiQuit()
@@ -91,6 +95,7 @@ pub fn queue_main(callback: Box<FnMut()>) {
 }
 
 #[inline]
+/// Set a callback to be run when the application quits.
 pub fn on_should_quit(callback: Box<FnMut()>) {
     unsafe {
         let mut data: Box<Box<FnMut()>> = Box::new(callback);
@@ -101,20 +106,23 @@ pub fn on_should_quit(callback: Box<FnMut()>) {
 }
 
 #[inline]
+/// Allow the user to select an existing file.
 pub fn open_file(parent: &Window) -> Option<Text> {
     unsafe {
         Text::optional(ui_sys::uiOpenFile(parent.as_ui_window()))
     }
 }
 
 #[inline]
+/// Allow the user to select a new or existing file.
 pub fn save_file(parent: &Window) -> Option<Text> {
     unsafe {
         Text::optional(ui_sys::uiSaveFile(parent.as_ui_window()))
     }
 }
 
 #[inline]
+/// Open a generic message box to show a message to the user.
 pub fn msg_box(parent: &Window, title: &str, description: &str) {
     unsafe {
         let c_title = CString::new(title.as_bytes().to_vec()).unwrap();
@@ -124,6 +132,7 @@ pub fn msg_box(parent: &Window, title: &str, description: &str) {
 }
 
 #[inline]
+/// Open an error-themed message box to show a message to the user.
 pub fn msg_box_error(parent: &Window, title: &str, description: &str) {
     unsafe {
         let c_title = CString::new(title.as_bytes().to_vec()).unwrap();