Crate cosmic 

The COSMIC Toolkit

Quickly code your project with modular elements created with customization in mind. Panels, applets, theming, tiling, launcher, app library, keyboard shortcuts and dynamic or pinned workspaces are all made flexible to bend to your users needs.

COSMIC empowers frictionless development by being approachable, easy to maintain, and modular. Use the same language and toolkit to build apps and applets, with helpful templates provided. Even shell components and the compositor use the same toolkit. Learn once and use your knowledge anywhere in the desktop.

Architecture

Based on iced, COSMIC apps and applets are modeled with the MVU (Model-View-Update) pattern from The Elm Architecture. For more details, see the architecture page of the iced book.

An application will consist of:

• An application model for holding persistent application state which implements the Application trait.
• A view function which borrows data from the model to construct a view with stateless widgets
• An update function which receives application messages from widgets, tasks, and subscriptions.

Messages handled by the update function are used to update the application model and spawn background tasks that can emit messages back to the app’s update function.

Tasks

Tasks returned by the update function are scheduled for concurrent execution on a background thread managed by the application’s async executor, which is tokio by default. They can be constructed from futures and may also stream events back to the application asynchronously.

Subscriptions

Applications may also use a subscription function to subscribe to external asynchronous event streams. These can run perpetually from application start; or optionally started, stopped, and restarted based on changes to the application model between updates. Such as:

• Conditionally starting and stopping a subscription based on the state of a boolean value or enum
• Restarting a subscription when the hash of its borrowed data changes
• Dynamically spawning a subscription for each item in a list.

Templates

Get started using cargo-generate with one of the following templates. The app template is for developing desktop applications and the applet template is for developing COSMIC applets.

• App Template
• Applet Template

Widgets

Reference the widget module for available widgets for use in the view function. Widgets are composable and can be configured through chainable builder methods. Compose widgets together to create complex interfaces and higher level widgets.

Composed widgets may be managed by their own custom type with its own view and update functions. It is a common pattern to use these functions within the application’s own view and update functions. If using a custom type, implement From for the Element type to have API treat a composed widget the same as a native custom widget.

If a widget does not exist for a specific use case, use the Widget trait to create an advanced custom widget. This can then be used to composed higher level widgets by chaining composable widgets together.

Core

Every application model requires a cosmic::Core. This contains application state which is managed by libcosmic’s runtime for its generated interfaces. Such as the context drawner, nav bar, and the headerbar. This can be used by the app to subscribe to configuration changes and to emit events to the libcosmic-managed portion of the application’s state and view.

Re-exports

pub use action::Action;

pub use dbus_activation::DbusActivation;single-instance

pub use executor::single::Executor as SingleThreadExecutor;tokio

Modules

action

Actions are managed internally by the cosmic runtime.

anim

appwinit

Build interactive cross-platform COSMIC applications.

appletapplet

cctkwayland and Linux

command

config

Configurations available to libcosmic applications.

core

State which is managed by the cosmic runtime.

cosmic_config

Integrations for cosmic-config — the cosmic configuration system.

cosmic_theme

Cosmic theme library.

dbus_activationsingle-instance

desktopdesktop

dialogxdg-portal or rfd

Create dialogs for retrieving user input.

executor

Select the preferred async executor for an application.

font

Select preferred fonts.

iced

iced is a cross-platform GUI library focused on simplicity and type-safety. Inspired by Elm.

icon_theme

Select the preferred icon theme.

keyboard_nav

Subscribe to common application keyboard shortcuts.

prelude

Recommended default imports.

processprocess and non-Windows

scroll

style

Stylesheet implements for crate::Theme

surface

task

Create asynchronous actions to be performed in the background.

theme

Contains the Theme type and its widget stylesheet implementations.

widget

The COSMIC widget library

Macros

fl

Structs

Core

COSMIC-specific application settings

Task

A set of concurrent actions to be performed by the iced runtime.

Theme

Traits

Also

Represents a type that you can apply arbitrary functions to. Useful for when a method doesn’t return the receiver but you want to apply several of them to the object.

Applicationwinit

An interactive cross-platform COSMIC application.

ApplicationExtwinit

Methods automatically derived for all types implementing Application.

Apply

Represents a type which can have functions applied to it (implemented by default for all types).

Type Aliases

Element

Renderer