doc: add book

book/.gitignore

@@ -0,0 +1 @@
+book

book/book.toml

@@ -0,0 +1,6 @@
+[book]
+authors = ["Michael Aaron Murphy"]
+language = "en"
+multilingual = false
+src = "src"
+title = "COSMIC Toolkit"

book/src/SUMMARY.md

@@ -0,0 +1,41 @@
+# Summary
+
+- [Introduction](./introduction.md)
+- [Model-View-Update (MVU)](./mvu.md)
+- [Commands](./commands.md)
+- [Subscriptions](./subscriptions.md)
+- [A Basic Application](./application.md)
+- [Nav Bar](./nav-bar.md)
+- [Menu Bar](./menu-bar.md)
+- [Context Drawer](./context-drawer.md)
+- [Widgets](./widgets.md)
+    - [Text](./text.md)
+    - [Container](./container.md)
+    - [Column](./column.md)
+    - [Row](./row.md)
+    - [Buttons](./buttons.md)
+    - [Icon](./icon.md)
+    - [Image](./image.md)
+    - [Svg](./svg.md)
+    - [Divider](./divider.md)
+    - [Space](./space.md)
+    - [Text Input](./text-input.md)
+    - [Toggler](./toggler.md)
+    - [Slider](./slider.md)
+    - [Radio](./radio.md)
+    - [Check Box](./check-box.md)
+    - [Dropdown](./dropdown.md)
+    - [Spin Button](./spin-button.md)
+    - [Color Picker](./color-picker.md)
+    - [Flex Row](./flex-row.md)
+    - [Grid](./grid.md)
+    - [Segmented Buttons](./segmented-buttons.md)
+    - [Tab Bar](./tab-bar.md)
+    - [Segmented Controls](./segmented-controls.md)
+    - [Context Menu](./context-menu.md)
+    - [Dialog](./dialog.md)
+    - [Pane Grid](./pane-grid.md)
+- [Creating a Widget](./creating-a-widget.md)
+- [Creating an Overlay](./creating-an-overlay.md)
+- [Examples](./examples.md)
+    - [Todo](./todo.md)

book/src/application.md

@@ -0,0 +1,2 @@
+# A Basic Application
+

book/src/buttons.md

@@ -0,0 +1 @@
+# Buttons

book/src/check-box.md

@@ -0,0 +1 @@
+# Check Box

book/src/color-picker.md

@@ -0,0 +1 @@
+# Color Picker

book/src/column.md

@@ -0,0 +1 @@
+# Column

book/src/commands.md

@@ -0,0 +1,83 @@
+# Commands
+
+[Commands][command] are short-lived async tasks that are spawned onto an async executor on a background thread. They must return a message back to the application upon completion, and cannot directly send messages back to the application until they return.
+
+> **NOTE**: While it is not possible for a command to directly send messages before completion, it is possible to create a subscription from a channel which passes its sender to the application, which may then pass that sender into its commands.
+
+## Future
+
+Commands may be created from futures using [cosmic::command::future](future).
+
+```rs
+fn update(&mut self, message: Self::Message) -> Command<Self::Message> {
+    match message {
+        Message::Clicked => {
+            self.counter += 1;
+            self.counter_text = format!("Clicked {} times", self.counter);
+            
+            // Await for 3 seconds in the background, and then request to decrease the counter.
+            return cosmic::command::future(async move {
+                tokio::time::sleep(Duration::from_millis(3000)).await;
+                Message::Decrease
+            });
+        }
+        
+        Message::Decrease =>  {
+            self.counter -= 1;
+            self.counter_text = format!("Clicked {} times", self.counter);
+        }
+    }
+    
+    Command::none()
+}
+```
+
+## Batches
+
+They can also be [batched][batch] for concurrent execution, where messages will be received in the order of completion.
+
+```rs
+fn update(&mut self, message: Self::Message) -> Command<Self::Message> {
+    match message {
+        Message::BatchStarted => {
+            eprintln!("started handling batch");
+        }
+
+        Message::Clicked => {
+            self.counter += 1;
+            self.counter_text = format!("Clicked {} times", self.counter);
+            
+            // Run two async tasks concurrently.
+            return cosmic::command::batch(vec![
+                // Await for 3 seconds in the background, and then request to decrease the counter.
+                cosmic::command::future(async move {
+                    tokio::time::sleep(Duration::from_millis(3000)).await;
+                    Message::Decrease
+                }),
+                // Immediately returns a message without waiting.
+                cosmic::command::message(Message::BatchStarted)
+            ]);
+        }
+        
+        Message::Decrease =>  {
+            self.counter -= 1;
+            self.counter_text = format!("Clicked {} times", self.counter);
+        }
+    }
+    
+    Command::none()
+}
+```
+
+## Widget Operations
+
+They can also be used to perform an operation onto a widget, such as focusing a button or text input.
+
+```rs
+return cosmic::widget::button::focus(self.BUTTON_ID);
+```
+
+[batch]: https://pop-os.github.io/libcosmic/cosmic/command/fn.batch.html
+[command]: https://pop-os.github.io/libcosmic/cosmic/iced_winit/runtime/struct.Command.html
+[cosmic-commands]: https://pop-os.github.io/libcosmic/cosmic/app/command/index.html#functions
+[future]: https://pop-os.github.io/libcosmic/cosmic/command/fn.future.html

book/src/container.md

@@ -0,0 +1 @@
+# Container

book/src/context-drawer.md

@@ -0,0 +1 @@
+# Context Drawer

book/src/context-menu.md

@@ -0,0 +1 @@
+# Context Menu

book/src/creating-a-widget.md

@@ -0,0 +1 @@
+# Creating a Widget

book/src/creating-an-overlay.md

@@ -0,0 +1 @@
+# Creating an Overlay

book/src/dialog.md

@@ -0,0 +1 @@
+# Dialog

book/src/divider.md

@@ -0,0 +1 @@
+# Divider

book/src/dropdown.md

@@ -0,0 +1 @@
+# Dropdown

book/src/examples.md

@@ -0,0 +1 @@
+# Examples

book/src/flex-row.md

@@ -0,0 +1 @@
+# Flex Row

book/src/grid.md

@@ -0,0 +1 @@
+# Grid

book/src/icon.md

@@ -0,0 +1 @@
+# Icon

book/src/image.md

@@ -0,0 +1 @@
+# Image

book/src/introduction.md

@@ -0,0 +1,18 @@
+# Introduction
+
+[libcosmic][toolkit] is the platform toolkit for [COSMIC](cosmic)—a GUI toolkit which empowers everyone to build COSMIC-themed applets and applications with ease. Based on the cross-platform [iced][iced] GUI library—which it utilizes for its runtime and rendering primitives—the COSMIC toolkit features personalizable desktop theming, a responsive widget library, a configuration system, platform integrations, and its own interface guidelines for building consistent and responsive applications.
+
+As a Rust-based GUI toolkit, experience with [Rust](rust) is required. Rust's rich type system and language features are key to what makes the COSMIC toolkit a much friendlier developer experience—enabling secure, reliable, and efficient applications to be developed at a faster pace than would be possible otherwise. For those interested in learning Rust, there are a lot of good resources available: [Learn Rust in a Month of Lunches][month-of-lunches], [Rust in Action][rust-in-action], [Rust by Example][rust-by-example], the official [Rust Book][rust-book], and [Rustlings][rustlings].
+
+Although the toolkit was created for the COSMIC desktop environment, it is also cross-platform, and thus it can be used to build COSMIC-themed applications for Linux (X11 & Wayland), [Redox OS](redox-os), Windows, and Mac. Even mobile platforms could be a possibility someday. One of the goals of libcosmic is to enable the creation of a cross-platform ecosystem of applications that are easy to port from one OS to another. We would also welcome any that would like to build their own OS experiences with the COSMIC toolkit.
+
+[cosmic]: https://github.com/pop-os/cosmic-epoch
+[iced]: https://iced.rs/
+[month-of-lunches]: https://www.manning.com/books/learn-rust-in-a-month-of-lunches
+[redox-os]: https://redox-os.org/
+[rust]: https://www.rust-lang.org/
+[rust-book]: https://doc.rust-lang.org/stable/book/
+[rust-by-example]: https://doc.rust-lang.org/rust-by-example/
+[rust-in-action]: https://www.manning.com/books/rust-in-action
+[rustlings]: https://github.com/rust-lang/rustlings
+[toolkit]: https://github.com/pop-os/libcosmic

book/src/menu-bar.md

@@ -0,0 +1 @@
+# MenuBar

book/src/mvu.md

@@ -0,0 +1,71 @@
+# Model-View-Update (MVU)
+
+Iced, and thereby COSMIC, uses a model-view-update approach to GUI development; also known as TEA—[The Elm Architecture][tea]. Similar to Elm, this architecture also emerged naturally in the Rust ecosystem as programmers searched for ways to model applications and services which adhere to Rust's [aliasing XOR mutability rule][aliasing-xor-mutability].
+
+<p align="center">
+    <figure>
+    <img src="https://book.iced.rs/resources/the-runtime.svg"/>
+    <figcaption><a href="https://book.iced.rs/the-runtime.html">The Runtime</a>—from the iced-rs book</figcaption>
+    </figure>
+</p>
+
+By structuring an application around an event loop which has ownership of a model, each iteration of the loop can immutably borrow the model to create a view, and mutably borrow the model to update the model with received messages. This eliminates the need for shared references, interior mutability, and runtime borrow checking.
+
+> **BACKGROUND**: Before working on COSMIC, the [Pop!_OS][pop-os] team at [System76][system76] was modeling each of their GTK applications with TEA. This would be eventually be formalized into [Relm4][Relm4], which is now the best way to build GTK4 applications in Rust. Event loops are spawned onto the glib runtime for the application and its components. These event loops await messages from a channel, whose senders would be attached to GTK widgets to enable them to publish messages when triggered.
+
+## Model
+
+Every application begins with a struct that implements the [cosmic::Application][app-trait] trait—which will serve as the application's model. All application state will be stored in this model, and it will be wise to cache data that will be needed by your application's widgets.
+
+```rs
+struct AppModel {
+    counter: u32,
+    counter_text: String,
+}
+
+impl cosmic::Application for AppModel {}
+```
+
+## View
+
+Whenever application or UI state changes; such as the movement of a mouse; the [view method][view-method] will be called to create a view which describes the current state of the UI. The view defines the layout of the interface, how it is to be drawn, and what messages widgets will emit when triggered. The runtime will pass UI events through the view and react upon messages that are emitted.
+
+```rs
+fn view(&self) -> Element<Self::Message> {
+    let button = widget::button(&self.counter_text)
+        .on_press(Message::Clicked);
+        
+    widget::container(button)
+        .width(iced::Length::Fill)
+        .height(iced::Length::Shrink)
+        .center_x()
+        .center_y()
+        .into()
+}
+```
+
+## Update
+
+Messages emitted by the view will later be passed through the application's [update method][update-method]. This will use Rust's pattern matching to choose a branch to execute, make any changes necessary to the application's model, and may optionally return one or more commands.
+
+```rs
+fn update(&mut self, message: Self::Message) -> Command<Self::Message> {
+    match message {
+        Message::Clicked => {
+            self.counter += 1;
+            self.counter_text = format!("Clicked {} times", self.counter);
+        }
+    }
+    
+    Command::none()
+}
+```
+
+[aliasing-xor-mutability]: https://cmpt-479-982.github.io/week1/safety_features_of_rust.html#the-borrow-checker-and-the-aliasing-xor-mutability-principle
+[app-trait]: https://pop-os.github.io/libcosmic/cosmic/app/trait.Application.html
+[pop-os]: https://system76.com/pop
+[relm4]: https://github.com/Relm4/relm4
+[system76]: https://system76.com/
+[tea]: https://guide.elm-lang.org/architecture/
+[update-method]: https://pop-os.github.io/libcosmic/cosmic/app/trait.Application.html#method.update
+[view-method]: https://pop-os.github.io/libcosmic/cosmic/app/trait.Application.html#tymethod.view

book/src/nav-bar.md

@@ -0,0 +1 @@
+# Nav Bar

book/src/pane-grid.md

@@ -0,0 +1 @@
+# Pane Grid

book/src/radio.md

@@ -0,0 +1 @@
+# Radio

book/src/row.md

@@ -0,0 +1 @@
+# Row

book/src/segmented-buttons.md

@@ -0,0 +1 @@
+# Segmented Buttons

book/src/segmented-controls.md

@@ -0,0 +1 @@
+# Segmented Controls

book/src/slider.md

@@ -0,0 +1 @@
+# Slider

book/src/space.md

@@ -0,0 +1 @@
+# Space

book/src/spin-button.md

@@ -0,0 +1 @@
+# Spin Button

book/src/subscriptions.md

@@ -0,0 +1 @@
+# Subscriptions

book/src/svg.md

@@ -0,0 +1 @@
+# Svg

book/src/tab-bar.md

@@ -0,0 +1 @@
+# Tab Bar

book/src/text-input.md

@@ -0,0 +1 @@
+# Text Input

book/src/text.md

@@ -0,0 +1,9 @@
+# Text
+
+The [text module][text-module] provides a variety of standard typography presets to use in your applications.
+
+## Body
+
+
+
+[text-module]: https://pop-os.github.io/libcosmic/cosmic/widget/text/index.html

book/src/todo.md

@@ -0,0 +1 @@
+# Todo

book/src/toggler.md

@@ -0,0 +1 @@
+# Toggler

book/src/widgets.md

@@ -0,0 +1 @@
+# Widgets