feat(app): add context view method for creating About views

Cargo.toml

@@ -40,6 +40,7 @@ desktop = [
     "process",
     "dep:freedesktop-desktop-entry",
     "dep:mime",
+    "dep:open",
     "dep:shlex",
     "tokio?/io-util",
     "tokio?/net",
@@ -97,6 +98,7 @@ image = { version = "0.25.1", optional = true }
 lazy_static = "1.4.0"
 libc = { version = "0.2.155", optional = true }
 mime = { version = "0.3.17", optional = true }
+open = { version = "5.3.0", optional = true }
 palette = "0.7.3"
 rfd = { version = "0.14.0", optional = true }
 rustix = { version = "0.38.34", features = [

examples/about/Cargo.toml

@@ -0,0 +1,26 @@
+[package]
+name = "about"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+tracing = "0.1.37"
+tracing-subscriber = "0.3.17"
+tracing-log = "0.2.0"
+
+[dependencies.libcosmic]
+path = "../../"
+default-features = false
+features = [
+    "debug",
+    "winit",
+    "tokio",
+    "xdg-portal",
+    "dbus-config",
+    "desktop",
+    "a11y",
+    "wayland",
+    "wgpu",
+    "single-instance",
+    "multi-window",
+]

examples/about/src/main.rs

@@ -0,0 +1,165 @@
+// Copyright 2023 System76 <info@system76.com>
+// SPDX-License-Identifier: MPL-2.0
+
+//! Application API example
+
+use cosmic::app::{about::About, Core, Settings, Task};
+use cosmic::iced::widget::column;
+use cosmic::iced_core::Size;
+use cosmic::widget::{self, nav_bar};
+use cosmic::{executor, iced, ApplicationExt, Element};
+
+/// Runs application with these settings
+#[rustfmt::skip]
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    tracing_subscriber::fmt::init();
+    let _ = tracing_log::LogTracer::init();
+
+    let settings = Settings::default()
+        .size(Size::new(1024., 768.));
+
+    cosmic::app::run::<App>(settings, ())?;
+
+    Ok(())
+}
+
+/// Messages that are used specifically by our [`App`].
+#[derive(Clone, Debug)]
+pub enum Message {
+    ToggleAbout,
+    Cosmic(cosmic::app::cosmic::Message),
+}
+
+/// The [`App`] stores application-specific state.
+pub struct App {
+    core: Core,
+    nav_model: nav_bar::Model,
+    about: About,
+}
+
+/// Implement [`cosmic::Application`] to integrate with COSMIC.
+impl cosmic::Application for App {
+    /// Default async executor to use with the app.
+    type Executor = executor::Default;
+
+    /// Argument received [`cosmic::Application::new`].
+    type Flags = ();
+
+    /// Message type specific to our [`App`].
+    type Message = Message;
+
+    /// The unique application ID to supply to the window manager.
+    const APP_ID: &'static str = "org.cosmic.AboutDemo";
+
+    fn core(&self) -> &Core {
+        &self.core
+    }
+
+    fn core_mut(&mut self) -> &mut Core {
+        &mut self.core
+    }
+
+    /// Creates the application, and optionally emits command on initialize.
+    fn init(core: Core, _flags: Self::Flags) -> (Self, Task<Self::Message>) {
+        let nav_model = nav_bar::Model::default();
+
+        let about = About::default()
+            .set_application_name("About Demo")
+            .set_application_icon(Self::APP_ID)
+            .set_developer_name("System 76")
+            .set_license_type("GPL-3.0")
+            .set_website("https://system76.com/cosmic")
+            .set_repository_url("https://github.com/pop-os/libcosmic")
+            .set_support_url("https://github.com/pop-os/libcosmic/issues")
+            .set_developers([("Michael Murphy".into(), "mmstick@system76.com".into())]);
+
+        let mut app = App {
+            core,
+            nav_model,
+            about,
+        };
+
+        let command = app.update_title();
+
+        (app, command)
+    }
+
+    /// Allows COSMIC to integrate with your application's [`nav_bar::Model`].
+    fn nav_model(&self) -> Option<&nav_bar::Model> {
+        Some(&self.nav_model)
+    }
+
+    /// Called when a navigation item is selected.
+    fn on_nav_select(&mut self, id: nav_bar::Id) -> Task<Self::Message> {
+        self.nav_model.activate(id);
+        self.update_title()
+    }
+
+    fn context_drawer(&self) -> Option<Element<Self::Message>> {
+        if !self.core.window.show_context {
+            return None;
+        }
+
+        if let Some(abuot_view) = self.about_view() {
+            Some(abuot_view.map(Message::Cosmic))
+        } else {
+            None
+        }
+    }
+
+    /// Handle application events here.
+    fn update(&mut self, message: Self::Message) -> Task<Self::Message> {
+        match message {
+            Message::ToggleAbout => {
+                self.core.window.show_context = !self.core.window.show_context;
+                self.core.set_show_context(self.core.window.show_context)
+            }
+            Message::Cosmic(message) => {
+                return cosmic::command::message(cosmic::app::Message::Cosmic(message))
+            }
+        }
+        Task::none()
+    }
+
+    fn about(&self) -> Option<&About> {
+        Some(&self.about)
+    }
+
+    /// Creates a view after each update.
+    fn view(&self) -> Element<Self::Message> {
+        let centered = cosmic::widget::container(
+            column![widget::button::text("Show about").on_press(Message::ToggleAbout)]
+                .width(iced::Length::Fill)
+                .height(iced::Length::Shrink)
+                .align_x(iced::alignment::Horizontal::Center),
+        )
+        .width(iced::Length::Fill)
+        .height(iced::Length::Shrink)
+        .align_x(iced::alignment::Horizontal::Center)
+        .align_y(iced::alignment::Vertical::Center);
+
+        Element::from(centered)
+    }
+}
+
+impl App
+where
+    Self: cosmic::Application,
+{
+    fn active_page_title(&mut self) -> &str {
+        self.nav_model
+            .text(self.nav_model.active())
+            .unwrap_or("Unknown Page")
+    }
+
+    fn update_title(&mut self) -> Task<Message> {
+        let header_title = self.active_page_title().to_owned();
+        let window_title = format!("{header_title} — COSMIC AppDemo");
+        self.set_header_title(header_title);
+        if let Some(id) = self.core.main_window_id() {
+            self.set_window_title(window_title, id)
+        } else {
+            Task::none()
+        }
+    }
+}

src/app/about.rs

@@ -0,0 +1,119 @@
+#[cfg(feature = "desktop")]
+use std::collections::BTreeMap;
+
+#[cfg(feature = "desktop")]
+#[derive(Debug, Default, Clone, derive_setters::Setters)]
+#[setters(prefix = "set_", into, strip_option)]
+pub struct About {
+    /// The application's name.
+    pub application_name: Option<String>,
+    /// The application's icon name.
+    pub application_icon: Option<String>,
+    /// Artists who contributed to the application.
+    #[setters(skip)]
+    pub artists: BTreeMap<String, String>,
+    /// Comments about the application.
+    pub comments: Option<String>,
+    /// The application's copyright.
+    pub copyright: Option<String>,
+    /// Designers who contributed to the application.
+    #[setters(skip)]
+    pub designers: BTreeMap<String, String>,
+    /// Name of the application's developer.
+    pub developer_name: Option<String>,
+    /// Developers who contributed to the application.
+    #[setters(skip)]
+    pub developers: BTreeMap<String, String>,
+    /// Documenters who contributed to the application.
+    #[setters(skip)]
+    pub documenters: BTreeMap<String, String>,
+    /// The license text.
+    pub license: Option<String>,
+    /// The license from a list of known licenses.
+    pub license_type: Option<String>,
+    /// The URL of the application’s support page.
+    #[setters(skip)]
+    pub support_url: Option<String>,
+    /// The URL of the application’s repository.
+    #[setters(skip)]
+    pub repository_url: Option<String>,
+    /// Translators who contributed to the application.
+    #[setters(skip)]
+    pub translators: BTreeMap<String, String>,
+    /// Links associated with the application.
+    #[setters(skip)]
+    pub links: BTreeMap<String, String>,
+    /// The application’s version.
+    pub version: Option<String>,
+    /// The application’s website.
+    #[setters(skip)]
+    pub website: Option<String>,
+}
+
+impl About {
+    pub fn set_repository_url(mut self, repository_url: impl Into<String>) -> Self {
+        let repository_url = repository_url.into();
+        self.repository_url = Some(repository_url.clone());
+        self.links.insert("Repository".into(), repository_url);
+        self
+    }
+
+    pub fn set_support_url(mut self, support_url: impl Into<String>) -> Self {
+        let support_url = support_url.into();
+        self.support_url = Some(support_url.clone());
+        self.links.insert("Support".into(), support_url);
+        self
+    }
+
+    pub fn set_website(mut self, website: impl Into<String>) -> Self {
+        let website = website.into();
+        self.website = Some(website.clone());
+        self.links.insert("Website".into(), website);
+        self
+    }
+
+    pub fn set_artists(mut self, artists: impl Into<BTreeMap<String, String>>) -> Self {
+        let artists: BTreeMap<String, String> = artists.into();
+        self.artists = artists
+            .into_iter()
+            .map(|(k, v)| (k, format!("mailto:{v}")))
+            .collect();
+        self
+    }
+
+    pub fn set_designers(mut self, designers: impl Into<BTreeMap<String, String>>) -> Self {
+        let designers: BTreeMap<String, String> = designers.into();
+        self.designers = designers
+            .into_iter()
+            .map(|(k, v)| (k, format!("mailto:{v}")))
+            .collect();
+        self
+    }
+
+    pub fn set_developers(mut self, developers: impl Into<BTreeMap<String, String>>) -> Self {
+        let developers: BTreeMap<String, String> = developers.into();
+        self.developers = developers
+            .into_iter()
+            .map(|(k, v)| (k, format!("mailto:{v}")))
+            .collect();
+        self
+    }
+
+    pub fn set_documenters(mut self, documenters: impl Into<BTreeMap<String, String>>) -> Self {
+        let documenters: BTreeMap<String, String> = documenters.into();
+        self.documenters = documenters
+            .into_iter()
+            .map(|(k, v)| (k, format!("mailto:{v}")))
+            .collect();
+        self
+    }
+
+    pub fn set_translators(mut self, translators: impl Into<BTreeMap<String, String>>) -> Self {
+        let translators: BTreeMap<String, String> = translators.into();
+        self.translators = translators
+            .into_iter()
+            .map(|(k, v)| (k, format!("mailto:{v}")))
+            .collect();
+        self
+    }
+}

src/app/cosmic.rs

@@ -78,6 +78,9 @@ pub enum Message {
     /// Tracks updates to window suggested size.
     #[cfg(feature = "applet")]
     SuggestedBounds(Option<iced::Size>),
+    #[cfg(feature = "desktop")]
+    /// Opens the provided URL.
+    OpenUrl(String),
 }
 
 #[derive(Default)]
@@ -661,6 +664,11 @@ impl<T: Application> Cosmic<T> {
                 let core = self.app.core_mut();
                 core.applet.suggested_bounds = b;
             }
+            #[cfg(feature = "desktop")]
+            Message::OpenUrl(url) => match open::that_detached(url) {
+                Ok(_) => (),
+                Err(err) => tracing::error!("{err}"),
+            },
             _ => {}
         }
 

src/app/mod.rs

@@ -6,6 +6,9 @@
 //! Check out our [application](https://github.com/pop-os/libcosmic/tree/master/examples/application)
 //! example in our repository.
 
+#[cfg(feature = "desktop")]
+pub mod about;
+
 pub mod command;
 mod core;
 pub mod cosmic;
@@ -71,6 +74,14 @@ use {
     zbus::{interface, proxy, zvariant::Value},
 };
 
+#[cfg(feature = "desktop")]
+use {
+    crate::app::about::About,
+    crate::widget,
+    iced::{alignment::Vertical, Alignment},
+    std::collections::BTreeMap,
+};
+
 pub(crate) fn iced_settings<App: Application>(
     settings: Settings,
     flags: App::Flags,
@@ -591,6 +602,88 @@ where
         panic!("no view for window {id:?}");
     }
 
+    #[cfg(feature = "desktop")]
+    /// Provides information about the application.
+    fn about(&self) -> Option<&About> {
+        None
+    }
+
+    #[cfg(feature = "desktop")]
+    /// Constructs the view for the about section.
+    fn about_view<'a>(&'a self) -> Option<Element<'a, crate::app::cosmic::Message>> {
+        let about = self.about()?;
+
+        let spacing = crate::theme::active().cosmic().spacing;
+
+        let section = |list: &'a BTreeMap<String, String>, title: &'a str| {
+            if list.is_empty() {
+                None
+            } else {
+                let developers: Vec<Element<crate::app::cosmic::Message>> = list
+                    .into_iter()
+                    .map(|(name, url)| {
+                        widget::button::custom(
+                            widget::row()
+                                .push(widget::text(name))
+                                .push(horizontal_space())
+                                .push(crate::widget::icon::from_name("link-symbolic").icon())
+                                .padding(spacing.space_xxs)
+                                .align_y(Vertical::Center),
+                        )
+                        .class(crate::theme::Button::Text)
+                        .on_press(crate::app::cosmic::Message::OpenUrl(url.clone()))
+                        .width(Length::Fill)
+                        .into()
+                    })
+                    .collect();
+                Some(widget::settings::section().title(title).extend(developers))
+            }
+        };
+
+        let application_name = about.application_name.as_ref().map(widget::text::title3);
+        let application_icon = about
+            .application_icon
+            .as_ref()
+            .map(|icon| crate::desktop::IconSource::Name(icon.clone()).as_cosmic_icon());
+
+        let links_section = section(&about.links, "Links");
+        let developers_section = section(&about.developers, "Developers");
+        let designers_section = section(&about.designers, "Designers");
+        let artists_section = section(&about.artists, "Artists");
+        let translators_section = section(&about.translators, "Translators");
+        let documenters_section = section(&about.documenters, "Documenters");
+
+        let developer_name = about.developer_name.as_ref().map(widget::text);
+        let version = about.version.as_ref().map(widget::button::standard);
+        let license = about.license_type.as_ref().map(widget::button::standard);
+        let copyright = about.copyright.as_ref().map(widget::text::body);
+        let comments = about.comments.as_ref().map(widget::text::body);
+
+        let about = widget::column()
+            .push_maybe(application_icon)
+            .push_maybe(application_name)
+            .push_maybe(developer_name)
+            .push(
+                widget::row()
+                    .push_maybe(version)
+                    .push_maybe(license)
+                    .spacing(spacing.space_xs),
+            )
+            .push_maybe(links_section)
+            .push_maybe(developers_section)
+            .push_maybe(designers_section)
+            .push_maybe(artists_section)
+            .push_maybe(translators_section)
+            .push_maybe(documenters_section)
+            .push_maybe(comments)
+            .push_maybe(copyright)
+            .align_x(Alignment::Center)
+            .spacing(spacing.space_xs)
+            .width(Length::Fill)
+            .into();
+        Some(about)
+    }
+
     /// Overrides the default style for applications
     fn style(&self) -> Option<iced_runtime::Appearance> {
         None