cosmic/widget/
mod.rs

1// Copyright 2022 System76 <info@system76.com>
2// SPDX-License-Identifier: MPL-2.0
3
4//! The COSMIC widget library
5//!
6//! This module contains a wide variety of widgets used throughout the COSMIC app ecosystem.
7//!
8//! # Overview
9//!
10//! Add widgets to your application view by calling the modules and functions below.
11//! Widgets are constructed by chaining their property methods using a functional paradigm.
12//! Modules may contain additional functions for constructing different variations of a widget.
13//! Each module will typically have one widget with the same name as the module, which will be re-exported here.
14//!
15//! ```no_run,ignore
16//! use cosmic::prelude::*;
17//! use cosmic::{cosmic_theme, theme, widget};
18//!
19//! const REPOSITORY: &str = "https://github.com/pop-os/libcosmic";
20//!
21//! let cosmic_theme::Spacing { space_xxs, .. } = theme::spacing();
22//!
23//! let link = widget::button::link(REPOSITORY)
24//!     .on_press(Message::LaunchUrl(REPOSITORY))
25//!     .padding(0);
26//!
27//! let content = widget::column()
28//!     .push(widget::icon::from_name("my-app-icon"))
29//!     .push(widget::text::title3("My App Name"))
30//!     .push(link)
31//!     .align_items(Alignment::Center)
32//!     .spacing(space_xxs);
33//! ```
34//!
35//! Widgets may borrow data from your application struct, and should do so to avoid allocating.
36//!
37//! ```no_run,ignore
38//! let text = widget::text::body(&self.cached_text);
39//! ```
40//!
41//! Use the [`cosmic::Apply`](crate::Apply) trait to embed widgets into other widgets which accept them.
42//!
43//! ```no_run,ignore
44//! let button = widget::icon::from_name("printer-symbolic")
45//!     .apply(widget::button::icon)
46//!     .on_press(Message::Print);
47//! ```
48
49// Re-exports from Iced
50#[doc(inline)]
51pub use iced::widget::{Canvas, canvas};
52
53#[doc(inline)]
54pub use iced::widget::{Checkbox, checkbox};
55
56#[doc(inline)]
57pub use iced::widget::{ComboBox, combo_box};
58
59#[doc(inline)]
60pub use iced::widget::{Container, container};
61
62#[doc(inline)]
63pub use iced::widget::{Space, horizontal_space, vertical_space};
64
65#[doc(inline)]
66pub use iced::widget::{Image, image};
67
68#[doc(inline)]
69pub use iced::widget::{Lazy, lazy};
70
71#[doc(inline)]
72pub use iced::widget::{MouseArea, mouse_area};
73
74#[doc(inline)]
75pub use iced::widget::{PaneGrid, pane_grid};
76
77#[doc(inline)]
78pub use iced::widget::{ProgressBar, progress_bar};
79
80#[doc(inline)]
81pub use iced::widget::{Responsive, responsive};
82
83#[doc(inline)]
84pub use iced::widget::{Slider, VerticalSlider, slider, vertical_slider};
85
86#[doc(inline)]
87pub use iced::widget::{Svg, svg};
88
89#[doc(inline)]
90pub use iced::widget::{TextEditor, text_editor};
91
92#[doc(inline)]
93pub use iced_core::widget::{Id, Operation, Widget};
94
95pub mod aspect_ratio;
96
97#[cfg(feature = "autosize")]
98pub mod autosize;
99
100pub(crate) mod responsive_container;
101
102#[cfg(feature = "surface-message")]
103mod responsive_menu_bar;
104#[cfg(feature = "surface-message")]
105#[doc(inline)]
106pub use responsive_menu_bar::{ResponsiveMenuBar, responsive_menu_bar};
107
108pub mod button;
109#[doc(inline)]
110pub use button::{Button, IconButton, LinkButton, TextButton};
111
112pub(crate) mod common;
113
114pub mod calendar;
115#[doc(inline)]
116pub use calendar::{Calendar, calendar};
117
118pub mod card;
119#[doc(inline)]
120pub use card::*;
121
122pub mod color_picker;
123#[doc(inline)]
124pub use color_picker::{ColorPicker, ColorPickerModel};
125
126#[cfg(feature = "qr_code")]
127#[doc(inline)]
128pub use iced::widget::qr_code;
129
130pub mod context_drawer;
131#[doc(inline)]
132pub use context_drawer::{ContextDrawer, context_drawer};
133
134#[doc(inline)]
135pub use column::{Column, column};
136pub mod column {
137    //! A container which aligns its children in a column.
138
139    pub type Column<'a, Message> = iced::widget::Column<'a, Message, crate::Theme, crate::Renderer>;
140
141    #[must_use]
142    /// A container which aligns its children in a column.
143    pub fn column<'a, Message>() -> Column<'a, Message> {
144        Column::new()
145    }
146
147    #[must_use]
148    /// A pre-allocated [`column`].
149    pub fn with_capacity<'a, Message>(capacity: usize) -> Column<'a, Message> {
150        Column::with_children(Vec::with_capacity(capacity))
151    }
152
153    #[must_use]
154    /// A [`column`] that will be assigned a [`Vec`] of children.
155    pub fn with_children<Message>(children: Vec<crate::Element<Message>>) -> Column<Message> {
156        Column::with_children(children)
157    }
158}
159
160pub mod layer_container;
161#[doc(inline)]
162pub use layer_container::{LayerContainer, layer_container};
163
164pub mod context_menu;
165#[doc(inline)]
166pub use context_menu::{ContextMenu, context_menu};
167
168pub mod dialog;
169#[doc(inline)]
170pub use dialog::{Dialog, dialog};
171
172/// An element to distinguish a boundary between two elements.
173pub mod divider {
174    /// Horizontal variant of a divider.
175    pub mod horizontal {
176        use iced::widget::{Rule, horizontal_rule};
177
178        /// Horizontal divider with default thickness
179        #[must_use]
180        pub fn default<'a>() -> Rule<'a, crate::Theme> {
181            horizontal_rule(1).class(crate::theme::Rule::Default)
182        }
183
184        /// Horizontal divider with light thickness
185        #[must_use]
186        pub fn light<'a>() -> Rule<'a, crate::Theme> {
187            horizontal_rule(1).class(crate::theme::Rule::LightDivider)
188        }
189
190        /// Horizontal divider with heavy thickness.
191        #[must_use]
192        pub fn heavy<'a>() -> Rule<'a, crate::Theme> {
193            horizontal_rule(4).class(crate::theme::Rule::HeavyDivider)
194        }
195    }
196
197    /// Vertical variant of a divider.
198    pub mod vertical {
199        use iced::widget::{Rule, vertical_rule};
200
201        /// Vertical divider with default thickness
202        #[must_use]
203        pub fn default<'a>() -> Rule<'a, crate::Theme> {
204            vertical_rule(1).class(crate::theme::Rule::Default)
205        }
206
207        /// Vertical divider with light thickness
208        #[must_use]
209        pub fn light<'a>() -> Rule<'a, crate::Theme> {
210            vertical_rule(4).class(crate::theme::Rule::LightDivider)
211        }
212
213        /// Vertical divider with heavy thickness.
214        #[must_use]
215        pub fn heavy<'a>() -> Rule<'a, crate::Theme> {
216            vertical_rule(10).class(crate::theme::Rule::HeavyDivider)
217        }
218    }
219}
220
221pub mod dnd_destination;
222#[doc(inline)]
223pub use dnd_destination::{DndDestination, dnd_destination};
224
225pub mod dnd_source;
226#[doc(inline)]
227pub use dnd_source::{DndSource, dnd_source};
228
229pub mod dropdown;
230#[doc(inline)]
231pub use dropdown::{Dropdown, dropdown};
232
233pub mod flex_row;
234#[doc(inline)]
235pub use flex_row::{FlexRow, flex_row};
236
237pub mod grid;
238#[doc(inline)]
239pub use grid::{Grid, grid};
240
241mod header_bar;
242#[doc(inline)]
243pub use header_bar::{HeaderBar, header_bar};
244
245pub mod icon;
246#[doc(inline)]
247pub use icon::{Icon, icon};
248
249pub mod id_container;
250#[doc(inline)]
251pub use id_container::{IdContainer, id_container};
252
253#[cfg(feature = "animated-image")]
254pub mod frames;
255
256pub use taffy::JustifyContent;
257
258pub mod list;
259#[doc(inline)]
260pub use list::{ListColumn, list_column};
261
262pub mod menu;
263
264pub mod nav_bar;
265#[doc(inline)]
266pub use nav_bar::{nav_bar, nav_bar_dnd};
267
268pub mod nav_bar_toggle;
269#[doc(inline)]
270pub use nav_bar_toggle::{NavBarToggle, nav_bar_toggle};
271
272pub mod popover;
273#[doc(inline)]
274pub use popover::{Popover, popover};
275
276pub mod radio;
277#[doc(inline)]
278pub use radio::{Radio, radio};
279
280pub mod rectangle_tracker;
281#[doc(inline)]
282pub use rectangle_tracker::{RectangleTracker, rectangle_tracking_container};
283
284#[doc(inline)]
285pub use row::{Row, row};
286
287pub mod row {
288    //! A container which aligns its children in a row.
289
290    pub type Row<'a, Message> = iced::widget::Row<'a, Message, crate::Theme, crate::Renderer>;
291
292    #[must_use]
293    /// A container which aligns its children in a row.
294    pub fn row<'a, Message>() -> Row<'a, Message> {
295        Row::new()
296    }
297
298    #[must_use]
299    /// A pre-allocated [`row`].
300    pub fn with_capacity<'a, Message>(capacity: usize) -> Row<'a, Message> {
301        Row::with_children(Vec::with_capacity(capacity))
302    }
303
304    #[must_use]
305    /// A [`row`] that will be assigned a [`Vec`] of children.
306    pub fn with_children<Message>(children: Vec<crate::Element<Message>>) -> Row<Message> {
307        Row::with_children(children)
308    }
309}
310
311pub mod scrollable;
312#[doc(inline)]
313pub use scrollable::scrollable;
314pub mod segmented_button;
315pub mod segmented_control;
316
317pub mod settings;
318
319pub mod spin_button;
320#[doc(inline)]
321pub use spin_button::{SpinButton, spin_button, vertical as vertical_spin_button};
322
323pub mod tab_bar;
324
325pub mod table;
326#[doc(inline)]
327pub use table::{compact_table, table};
328
329pub mod text;
330#[doc(inline)]
331pub use text::{Text, text};
332
333pub mod text_input;
334#[doc(inline)]
335pub use text_input::{
336    TextInput, editable_input, inline_input, search_input, secure_input, text_input,
337};
338
339pub mod toaster;
340#[doc(inline)]
341pub use toaster::{Toast, ToastId, Toasts, toaster};
342
343mod toggler;
344#[doc(inline)]
345pub use toggler::toggler;
346
347#[doc(inline)]
348pub use tooltip::{Tooltip, tooltip};
349
350#[cfg(all(feature = "wayland", feature = "winit"))]
351pub mod wayland;
352
353pub mod tooltip {
354    use crate::Element;
355
356    pub use iced::widget::tooltip::Position;
357
358    pub type Tooltip<'a, Message> =
359        iced::widget::Tooltip<'a, Message, crate::Theme, crate::Renderer>;
360
361    pub fn tooltip<'a, Message>(
362        content: impl Into<Element<'a, Message>>,
363        tooltip: impl Into<Element<'a, Message>>,
364        position: Position,
365    ) -> Tooltip<'a, Message> {
366        let xxs = crate::theme::spacing().space_xxs;
367
368        Tooltip::new(content, tooltip, position)
369            .class(crate::theme::Container::Tooltip)
370            .padding(xxs)
371            .gap(1)
372    }
373}
374
375pub mod warning;
376#[doc(inline)]
377pub use warning::*;
378
379pub mod wrapper;
380#[doc(inline)]
381pub use wrapper::*;
382
383#[cfg(feature = "markdown")]
384#[doc(inline)]
385pub use iced::widget::markdown;
386
387#[cfg(feature = "about")]
388pub mod about;
389#[cfg(feature = "about")]
390#[doc(inline)]
391pub use about::about;