XDG desktop portal integrations for open and save file dialogs

Cargo.toml

@@ -8,17 +8,29 @@ name = "cosmic"
 
 [features]
 default = ["wayland", "tokio", "a11y"]
-debug = ["iced/debug"]
+# Accessibility support
 a11y = ["iced/a11y", "iced_accessibility"]
-wayland = ["iced/wayland", "iced_sctk", "sctk"]
-wgpu = ["iced/wgpu", "iced_wgpu"]
-tokio = ["dep:tokio", "iced/tokio"]
+# Builds support for animated images
+animated-image = ["image", "dep:async-fs", "tokio?/io-util", "tokio?/fs"]
+# Debug features
+debug = ["iced/debug"]
+# Enables pipewire support in ashpd, if ashpd is enabled
+pipewire = ["ashpd?/pipewire"]
+# smol async runtime
 smol = ["iced/smol"]
+# Tokio async runtime
+tokio = ["dep:tokio", "ashpd/tokio", "iced/tokio"]
+# Wayland window support
+wayland = ["ashpd?/wayland", "iced/wayland", "iced_sctk", "sctk"]
+# Render with wgpu
+wgpu = ["iced/wgpu", "iced_wgpu"]
+# X11 window support via winit
 winit = ["iced/winit", "iced_winit"]
-winit_tokio = ["iced/winit", "iced_winit", "tokio"]
 winit_debug = ["iced/winit", "iced_winit", "debug"]
+winit_tokio = ["iced/winit", "iced_winit", "tokio"]
 winit_wgpu = ["winit", "wgpu"]
-animated-image = ["image", "dep:async-fs", "tokio?/io-util", "tokio?/fs"]
+# Enables XDG portal integrations
+xdg-portal = ["ashpd"]
 
 [dependencies]
 apply = "0.3.0"
@@ -34,6 +46,8 @@ tracing = "0.1"
 image = { version = "0.24.6", optional = true }
 thiserror = "1.0.44"
 async-fs = { version = "1.6", optional = true }
+ashpd = { version = "0.5.0", default-features = false, optional = true }
+url = "2.4.0"
 
 [target.'cfg(unix)'.dependencies]
 freedesktop-icons = "0.2.2"

README.md

@@ -1,51 +1,90 @@
 # LIBCOSMIC
 
-Building blocks for COSMIC applications.
+A platform toolkit based on iced which provides the building blocks for developing the
+future COSMIC desktop environment. Applications and applets alike are equally supported
+targets of Libcosmic. Applets integrate directly with COSMIC's interface as shell
+components, which was made possible by the Layer Shell protocol of Wayland.
 
 ## Building
-Libcosmic is written in pure Rust, so `cargo` is all you need.
 
-```shell
-cargo build
-```
-
-## Usage
-There's examples in the `examples` directory.
+Libcosmic is written entirely in Rust, with minimal dependence on system libraries. On
+Pop!_OS, the following dependencies are all that's necessary compile the cosmic library:
 
-### Widget library
-```shell
-cargo run --release --example cosmic
+```sh
+sudo apt install cargo cmake just libexpat1-dev libfontconfig-dev libfreetype-dev pkg-config
 ```
 
-On Pop!_OS
-```shell
-sudo apt install cargo libexpat1-dev libfontconfig-dev libfreetype-dev pkg-config cmake
+Some examples are included in the [examples](./examples) directory to to kickstart your
+COSMIC adventure. To run them, you need to clone the repository with the following commands:
+
+```sh
 git clone https://github.com/pop-os/libcosmic
 cd libcosmic
-git submodule update --init
-cargo run --release -p cosmic
+git submodule update --init --recursive
 ```
 
-If already cloned
-```shell
-cd libcosmic
-git pull origin master
-cargo run --release -p cosmic
+If you have already cloned the repository, run these to sync with the latest updates:
+
+```sh
+git fetch origin
+git checkout master
+git reset --hard origin/master
+git submodule update --init --recursive
 ```
 
-### Text rendering
-```shell
-cargo run --release --example text
+To create a new COSMIC project, use `cargo new {{name_of_project}}` to create a new
+project workspace, edit the `Cargo.toml` contained within, and add this to begin.
+
+```toml
+[workspace.dependencies.libcosmic]
+git = "https://github.com/pop-os/libcosmic"
+default-features = false
+features = ["wayland", "tokio"]
 ```
 
+### Cargo Features
+
+Available cargo features to choose from:
+
+- `a11y`: Experimental accessibility support.
+- `animated-image`: Enables animated images from the image crate.
+- `debug`: Enables addtional debugging features.
+- `smol`: Uses smol as the preferred async runtime.
+    - Conflicts with `tokio`
+- `tokio`: Uses tokio as the preferred async runtime.
+    - If unset, the default executor defined by iced will be used.
+    - Conflicts with `smol`
+- `wayland`: Wayland-compatible client windows.
+    - Conflicts with `winit`
+- `winit`: Cross-platform and X11 client window support
+    - Conflicts with `wayland`
+- `wgpu`: GPU accelerated rendering with WGPU.
+    - By default, softbuffer is used for software rendering.
+- `xdg-portal`: Enables XDG portal dialog integrations.
+
+### Project Showcase
+
+- [COSMIC App Library](https://github.com/pop-os/cosmic-applibrary)
+- [COSMIC Applets](https://github.com/pop-os/cosmic-applets)
+- [COSMIC Launcher](https://github.com/pop-os/cosmic-launcher)
+- [COSMIC Notifications](https://github.com/pop-os/cosmic-notifications)
+- [COSMIC Panel](https://github.com/pop-os/cosmic-panel)
+- [COSMIC Text Editor](https://github.com/pop-os/cosmic-text-editor)
+- [COSMIC Settings](https://github.com/pop-os/cosmic-settings)
+
 ## Documentation
-The documentation can be found [here](https://pop-os.github.io/docs/).
+
+Documentation can be found [here](https://pop-os.github.io/docs/).
 
 ## Licence
-Libcosmic is licenced under the MPL-2.0
+
+Licensed under the [Mozilla Public License 2.0](https://choosealicense.com/licenses/mpl-2.0).
 
 ## Contact
+
 - [Mattermost](https://chat.pop-os.org/)
-- [Discord](https://chat.pop-os.org/)
+- [Lemmy](https://lemmy.world/c/pop_os)
+- [Mastodon](https://fosstodon.org/@pop_os_official)
+- [Reddit](https://www.reddit.com/r/pop_os/)
 - [Twitter](https://twitter.com/pop_os_official)
-- [Instagram](https://www.instagram.com/pop_os_official/)
+- [Instagram](https://www.instagram.com/pop_os_official)

examples/application/src/main.rs

@@ -1,27 +1,46 @@
 // Copyright 2023 System76 <info@system76.com>
 // SPDX-License-Identifier: MPL-2.0
 
-//! Testing ground for improving COSMIC application API ergonomics.
+//! Application API example
 
 use cosmic::app::{Command, Core, Settings};
 use cosmic::widget::nav_bar;
 use cosmic::{executor, iced, ApplicationExt, Element};
 
+#[derive(Clone, Copy)]
+pub enum Page {
+    Page1,
+    Page2,
+    Page3,
+    Page4,
+}
+
+impl Page {
+    const fn as_str(self) -> &'static str {
+        match self {
+            Page::Page1 => "Page 1",
+            Page::Page2 => "Page 2",
+            Page::Page3 => "Page 3",
+            Page::Page4 => "Page 4",
+        }
+    }
+}
+
 /// Runs application with these settings
 #[rustfmt::skip]
 fn main() -> Result<(), Box<dyn std::error::Error>> {
     let input = vec![
-        ("Page 1".into(), "🖖 Hello from libcosmic.".into()),
-        ("Page 2".into(), "🌟 This is an example application.".into()),
-        ("Page 3".into(), "🚧 The libcosmic API is not stable yet.".into()),
-        ("Page 4".into(), "🚀 Copy the source code and experiment today!".into()),
+        (Page::Page1, "🖖 Hello from libcosmic.".into()),
+        (Page::Page2, "🌟 This is an example application.".into()),
+        (Page::Page3, "🚧 The libcosmic API is not stable yet.".into()),
+        (Page::Page4, "🚀 Copy the source code and experiment today!".into()),
     ];
 
     let settings = Settings::default()
         .antialiasing(true)
         .client_decorations(true)
         .debug(false)
-        .default_icon_theme("Pop")
+        .default_icon_theme(Some("Pop".into()))
         .default_text_size(16.0)
         .scale_factor(1.0)
         .size((1024, 768))
@@ -48,7 +67,7 @@ impl cosmic::Application for App {
     type Executor = executor::Default;
 
     /// Argument received [`cosmic::Application::new`].
-    type Flags = Vec<(String, String)>;
+    type Flags = Vec<(Page, String)>;
 
     /// Message type specific to our [`App`].
     type Message = Message;
@@ -68,7 +87,7 @@ impl cosmic::Application for App {
         let mut nav_model = nav_bar::Model::default();
 
         for (title, content) in input {
-            nav_model.insert().text(title).data(content);
+            nav_model.insert().text(title.as_str()).data(content);
         }
 
         nav_model.activate_position(0);
@@ -91,10 +110,12 @@ impl cosmic::Application for App {
         self.update_title()
     }
 
+    /// Handle application events here.
     fn update(&mut self, _message: Self::Message) -> Command<Self::Message> {
         Command::none()
     }
 
+    /// Creates a view after each update.
     fn view(&self) -> Element<Self::Message> {
         let page_content = self
             .nav_model

examples/open-dialog/Cargo.toml

@@ -0,0 +1,16 @@
+[package]
+name = "open_dialog"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+apply = "0.3.0"
+tokio = { version = "1.31", features = ["full"] }
+tracing = "0.1.37"
+tracing-subscriber = "0.3.17"
+url = "2.4.0"
+
+[dependencies.libcosmic]
+path = "../../"
+default-features = false
+features = ["debug", "wayland", "tokio", "xdg-portal"]