diff --git a/doc/adaptive-layouts.md b/doc/adaptive-layouts.md new file mode 100644 index 0000000000000000000000000000000000000000..af19b3c8763a36884156ce5111800397b04e4864 --- /dev/null +++ b/doc/adaptive-layouts.md @@ -0,0 +1,288 @@ +Title: Adaptive Layouts +Slug: adaptive-layouts + +# Adaptive Layouts + +Libadwaita provides a number of widgets that change their layout based on the +available space. This can be used to make applications adapt their UI between +desktop and mobile devices. + +## Clamp + +[class@Clamp] has one child and constrains its maximum size, while still +allowing it to shrink. In other words, it allows the child to have padding when +there's enough space, and to remove them otherwise. + +This is commonly used for patterns such as [boxed lists](boxed-lists.html): + + + + adaptive-boxed-lists-wide + + + + adaptive-boxed-lists-narrow + + +```xml + + + + vertical + 24 + 24 + 12 + 12 + 24 + + + none + + + + + + + + +``` + +See also: [class@ClampLayout], [class@ClampScrollable]. + +## Leaflet + +[class@Leaflet] shows all its children side by side when there's enough room, or +one child otherwise. In other words, it behaves like a [class@Gtk.Box] or +[class@Gtk.Stack]. + +A common use for a leaflet is implementing a split header bar layout, with a +sidebar, a content view and a separator between them: + + + + adaptive-split-headers-wide + + + + adaptive-split-headers-narrow-1 + + + + adaptive-split-headers-narrow-2 + + +```xml + + True + + + vertical + + + + leaflet + + + + Sidebar + + + + + + + + + + False + + + + + + + + vertical + True> + + + + leaflet + + + + + leaflet + + go-previous-symbolic + + + + + Content + + + + + + + + +``` + +When the window is wide, the leaflet shows the sidebar, separator and content +side by side. When it's narrow, the leaflet shows either sidebar or content, +using the [browsing](https://developer.gnome.org/hig/patterns/nav/browsing.html) +pattern to navigate between them. If [property@Leaflet:can-navigate-back] is set +to `TRUE`, the leaflet will provide a swipe gesture allowing to go back from +the content page, as well as handle the relevant keyboard shortcuts and mouse +buttons. + +The application needs to provide a back button and to switch leaflet's visible +child to content appropriate (for example, show content after a sidebar row has +been clicked, show sidebar after the back button has been clicked). The +[method@Leaflet.navigate] method is convenient for this. + +Split header bars are typically used with [class@Window] or +[class@ApplicationWindow], since the layout already contains header bars. + +## Flap + +[class@Flap] shows children side by side when there's enough room, or overlays +one child on top of the other otherwise. + +This is commonly used to implement [utility panes](https://developer.gnome.org/hig/patterns/containers/utility-panes.html), +via setting the utility pane as the [property@Flap:flap] and the main view as +[property@Flap:content]. + + + + adaptive-utility-pane-wide + + + + adaptive-utility-pane-narrow + + +```xml + + sidebar-show-symbolic + True + + + + + + + + + + + + + + +``` + +To make the utility pane permanently visible on desktop, and only allow to show +and hide it on mobile, bind the relevant properties to +the flap's [property@Flap:folded] value. + +```xml + + sidebar-show-symbolic + True + + + + + + + + + + + + + + + + + +``` + +## View Switcher + +The [class@ViewSwitcherTitle] and [class@ViewSwitcherBar] widgets implement an +adaptive [view switcher](https://developer.gnome.org/hig/patterns/nav/view-switchers.html). + +They are typically used together, providing desktop and mobile UI for the same +navigation: a view switcher in the header bar when there's enough space, or a +view switcher in a bottom bar otherwise. + + + + adaptive-view-switcher-wide + + + + adaptive-view-switcher-narrow + + +```xml + + vertical + + + strict + + + stack + + + + + + + True + + + + + + stack + + title + + + + +``` + +View switcher is also available separately as [class@ViewSwitcher]. This can be +useful if the higher level widgets cannot work for some reason. + +## Squeezer + +[class@Squeezer] is similar to [class@Gtk.Stack], but shows the largest of its +children that can fit into the available space. + +For example, [class@ViewSwitcherTitle] uses it to conditionally show a view +switcher or the window title. diff --git a/doc/boxed-lists.md b/doc/boxed-lists.md new file mode 100644 index 0000000000000000000000000000000000000000..640c83092608f868cfeb645c521b9e780d6a9ade --- /dev/null +++ b/doc/boxed-lists.md @@ -0,0 +1,90 @@ +Title: Boxed Lists +Slug: boxed-lists + +# Boxed Lists + +Libadwaita provides API to implement the [boxed lists](https://developer.gnome.org/hig/patterns/containers/boxed-lists.html) +pattern. + +Boxed lists are composed of a [class@Gtk.ListBox] with the +[property@Gtk.ListBox:selection-mode] set to `GTK_SELECTION_NONE` and with the +[`.boxed-list`](style-classes.html#boxed-lists-cards) style class. + +[class@Gtk.ListView] cannot be used as a boxed list at the moment. + +An example boxed list: + +```xml + + none + + + + Item 1 + + + + + Item 2 + + + + + Item 3 + + + +``` + + + + boxed-lists + + +# Rows + +A number of predefined list row classes are available and intended to be used +inside boxed lists: + +## Action Rows + +[class@ActionRow] is a basic row. It has a title, a subtitle, an icon, and can +have prefix and suffix children. + + + + action-row + + +## Expander Rows + +[class@ExpanderRow] is similar to [class@ActionRow], but can expand to show +other rows. + + + + expander-row + + +## Combo Rows + +[class@ComboRow] is a row with an embedded drop down menu, similar to +[class@Gtk.DropDown]. + + + + combo-row + + +## Preferences Group + +[class@PreferencesGroup] provides a boxed list along with a title and a +description. It's mainly meant to be used as a child of [class@PreferencesPage], +but can also be used separately. + + + + preferences-group + diff --git a/doc/images/adaptive-boxed-lists-narrow-dark.png b/doc/images/adaptive-boxed-lists-narrow-dark.png new file mode 100644 index 0000000000000000000000000000000000000000..8365bca2d1c7a3f8291fee04bad3abb45e2be61b Binary files /dev/null and b/doc/images/adaptive-boxed-lists-narrow-dark.png differ diff --git a/doc/images/adaptive-boxed-lists-narrow.png b/doc/images/adaptive-boxed-lists-narrow.png new file mode 100644 index 0000000000000000000000000000000000000000..86c2a51c49a24e6f7816c352895a51c0712789a8 Binary files /dev/null and b/doc/images/adaptive-boxed-lists-narrow.png differ diff --git a/doc/images/adaptive-boxed-lists-wide-dark.png b/doc/images/adaptive-boxed-lists-wide-dark.png new file mode 100644 index 0000000000000000000000000000000000000000..ff43de759fba5883af3c29ff7dcc76f7e1c087b0 Binary files /dev/null and b/doc/images/adaptive-boxed-lists-wide-dark.png differ diff --git a/doc/images/adaptive-boxed-lists-wide.png b/doc/images/adaptive-boxed-lists-wide.png new file mode 100644 index 0000000000000000000000000000000000000000..55e130a969f8cb6d5e2099294622898710eb9745 Binary files /dev/null and b/doc/images/adaptive-boxed-lists-wide.png differ diff --git a/doc/images/adaptive-split-headers-narrow-1-dark.png b/doc/images/adaptive-split-headers-narrow-1-dark.png new file mode 100644 index 0000000000000000000000000000000000000000..91ba33cff66e11f5767e954d9a47d0a65e233076 Binary files /dev/null and b/doc/images/adaptive-split-headers-narrow-1-dark.png differ diff --git a/doc/images/adaptive-split-headers-narrow-1.png b/doc/images/adaptive-split-headers-narrow-1.png new file mode 100644 index 0000000000000000000000000000000000000000..87fa954695449e77fb2dd791eb6e344435c77eba Binary files /dev/null and b/doc/images/adaptive-split-headers-narrow-1.png differ diff --git a/doc/images/adaptive-split-headers-narrow-2-dark.png b/doc/images/adaptive-split-headers-narrow-2-dark.png new file mode 100644 index 0000000000000000000000000000000000000000..3e64e2f17e5f43d9db357ce4e82c65a89d6ebb2c Binary files /dev/null and b/doc/images/adaptive-split-headers-narrow-2-dark.png differ diff --git a/doc/images/adaptive-split-headers-narrow-2.png b/doc/images/adaptive-split-headers-narrow-2.png new file mode 100644 index 0000000000000000000000000000000000000000..15161ddcb0663efb1c4c097d6058ac43c74734a1 Binary files /dev/null and b/doc/images/adaptive-split-headers-narrow-2.png differ diff --git a/doc/images/adaptive-split-headers-wide-dark.png b/doc/images/adaptive-split-headers-wide-dark.png new file mode 100644 index 0000000000000000000000000000000000000000..8994fd4acb0ca16d7edbc66a63358cbf8f9b65e4 Binary files /dev/null and b/doc/images/adaptive-split-headers-wide-dark.png differ diff --git a/doc/images/adaptive-split-headers-wide.png b/doc/images/adaptive-split-headers-wide.png new file mode 100644 index 0000000000000000000000000000000000000000..0db2cd5b3ae639a54a80e159c4c116afbeb24186 Binary files /dev/null and b/doc/images/adaptive-split-headers-wide.png differ diff --git a/doc/images/adaptive-utility-pane-narrow-dark.png b/doc/images/adaptive-utility-pane-narrow-dark.png new file mode 100644 index 0000000000000000000000000000000000000000..81636cc88c886ea2539eb11aa9666c0162843d26 Binary files /dev/null and b/doc/images/adaptive-utility-pane-narrow-dark.png differ diff --git a/doc/images/adaptive-utility-pane-narrow.png b/doc/images/adaptive-utility-pane-narrow.png new file mode 100644 index 0000000000000000000000000000000000000000..04b93507dbb7cb5f075314510ad3d2aa24d9e240 Binary files /dev/null and b/doc/images/adaptive-utility-pane-narrow.png differ diff --git a/doc/images/adaptive-utility-pane-wide-dark.png b/doc/images/adaptive-utility-pane-wide-dark.png new file mode 100644 index 0000000000000000000000000000000000000000..368eefbb244d471ab3d21dd71d09717eaf30050d Binary files /dev/null and b/doc/images/adaptive-utility-pane-wide-dark.png differ diff --git a/doc/images/adaptive-utility-pane-wide.png b/doc/images/adaptive-utility-pane-wide.png new file mode 100644 index 0000000000000000000000000000000000000000..8ca036a7ee65d7fbdc27c48ae81e05d252345b3b Binary files /dev/null and b/doc/images/adaptive-utility-pane-wide.png differ diff --git a/doc/images/adaptive-view-switcher-narrow-dark.png b/doc/images/adaptive-view-switcher-narrow-dark.png new file mode 100644 index 0000000000000000000000000000000000000000..f74b4778f7168c13ef0c157457911a42530704fc Binary files /dev/null and b/doc/images/adaptive-view-switcher-narrow-dark.png differ diff --git a/doc/images/adaptive-view-switcher-narrow.png b/doc/images/adaptive-view-switcher-narrow.png new file mode 100644 index 0000000000000000000000000000000000000000..73b2a3ab56c8ac9214158e6392a3614a2ad9b72f Binary files /dev/null and b/doc/images/adaptive-view-switcher-narrow.png differ diff --git a/doc/images/adaptive-view-switcher-wide-dark.png b/doc/images/adaptive-view-switcher-wide-dark.png new file mode 100644 index 0000000000000000000000000000000000000000..5af0c2a7ec4f6121d9eaefe198fcf3e7a1d8ef20 Binary files /dev/null and b/doc/images/adaptive-view-switcher-wide-dark.png differ diff --git a/doc/images/adaptive-view-switcher-wide.png b/doc/images/adaptive-view-switcher-wide.png new file mode 100644 index 0000000000000000000000000000000000000000..e401ed275265cb78ba67b99d169f490de76302c8 Binary files /dev/null and b/doc/images/adaptive-view-switcher-wide.png differ diff --git a/doc/libadwaita.toml.in b/doc/libadwaita.toml.in index 2dcd4a73a3d5373c826ba73e09ca3c8bde8ee6a7..b6f01245ca6f74c5b16577d9cbeb3cde9775aacd 100644 --- a/doc/libadwaita.toml.in +++ b/doc/libadwaita.toml.in @@ -39,15 +39,40 @@ file_format = "{filename}#L{line}" urlmap_file = "urlmap.js" content_files = [ "build-howto.md", - "migrating-between-development-versions.md", - "migrating-libhandy-1-4-to-libadwaita.md", + + "boxed-lists.md", + "adaptive-layouts.md", + + "styles-and-appearance.md", "named-colors.md", "style-classes.md", + + "migrating-between-development-versions.md", + "migrating-libhandy-1-4-to-libadwaita.md", + "visual-index.md", ] content_images = [ "images/action-row.png", "images/action-row-dark.png", + "images/adaptive-boxed-lists-narrow.png", + "images/adaptive-boxed-lists-narrow-dark.png", + "images/adaptive-boxed-lists-wide.png", + "images/adaptive-boxed-lists-wide-dark.png", + "images/adaptive-split-headers-narrow-1.png", + "images/adaptive-split-headers-narrow-1-dark.png", + "images/adaptive-split-headers-narrow-2.png", + "images/adaptive-split-headers-narrow-2-dark.png", + "images/adaptive-split-headers-wide.png", + "images/adaptive-split-headers-wide-dark.png", + "images/adaptive-utility-pane-narrow.png", + "images/adaptive-utility-pane-narrow-dark.png", + "images/adaptive-utility-pane-wide.png", + "images/adaptive-utility-pane-wide-dark.png", + "images/adaptive-view-switcher-narrow.png", + "images/adaptive-view-switcher-narrow-dark.png", + "images/adaptive-view-switcher-wide.png", + "images/adaptive-view-switcher-wide-dark.png", "images/app-icons.png", "images/app-icons-dark.png", "images/application-window.png", diff --git a/doc/meson.build b/doc/meson.build index 46c49564701ee250407abec6cfc3a3bf7f5d3074..60ec70bbdd78b17d54c61fe1ff63690a63420372 100644 --- a/doc/meson.build +++ b/doc/meson.build @@ -3,10 +3,13 @@ if get_option('gtk_doc') subdir('tools') expand_content_md_files = [ + 'adaptive-layouts.md', + 'boxed-lists.md', 'build-howto.md', 'migrating-between-development-versions.md', 'migrating-libhandy-1-4-to-libadwaita.md', 'named-colors.md', + 'styles-and-appearance.md', 'style-classes.md', 'visual-index.md', ] diff --git a/doc/style-classes.md b/doc/style-classes.md index 9e2ff917b3b1cef65dd40347b7009412b3e2827b..e2704904e37ea01eaf37399f71ac46eca43d0131 100644 --- a/doc/style-classes.md +++ b/doc/style-classes.md @@ -348,8 +348,8 @@ state. The `.boxed-list` style class can be applied to a [class@Gtk.ListBox] to make it -a boxed list. The list box should have [property@Gtk.ListBox:selection-mode] set -to `GTK_SELECTION_NONE`. +a [boxed list](boxed-lists.html). The list box should have +[property@Gtk.ListBox:selection-mode] set to `GTK_SELECTION_NONE`. diff --git a/doc/styles-and-appearance.md b/doc/styles-and-appearance.md new file mode 100644 index 0000000000000000000000000000000000000000..e06560bcff692d2d9b355a3ef12a6ce1741b8aec --- /dev/null +++ b/doc/styles-and-appearance.md @@ -0,0 +1,132 @@ +Title: Styles & Appearance +Slug: styles-and-appearance + +# Styles & Appearance + +## Dark Style + +Libadwaita applications can use a light or a dark appearance. This can be used +to request a darker UI, or to support a system-wide dark style preference if one +exists. + +By default applications use light appearance unless the system prefers dark +appearance, matching the `ADW_COLOR_SCHEME_PREFER_LIGHT` color scheme. The +[property@StyleManager:color-scheme] property allows to change this behavior +when set to: + +* `ADW_COLOR_SCHEME_PREFER_DARK`: Use dark appearance unless the system prefers + light appearance. +* `ADW_COLOR_SCHEME_FORCE_DARK`: Always use dark appearance. +* `ADW_COLOR_SCHEME_FORCE_LIGHT`: Always use light appearance. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
App \ SystemPrefer LightNo PreferencePrefer Dark
FORCE_LIGHTLightLightLight
PREFER_LIGHTLightLightDark
PREFER_DARKLightDarkDark
FORCE_DARKDarkDarkDark
+ +Common use cases: + +1. An application wants to use dark UI. Use the `ADW_COLOR_SCHEME_PREFER_DARK` + color scheme. + +2. An application has a style switcher with the system, light and +dark states. Use the following color scheme values: + + * System: `ADW_COLOR_SCHEME_PREFER_LIGHT` + * Light: `ADW_COLOR_SCHEME_FORCE_LIGHT` + * Dark: `ADW_COLOR_SCHEME_FORCE_DARK` + +If the system does not provide a style preference, the +[property@StyleManager:system-supports-color-schemes] property can be used to +provide a fallback. For example, applications with a system/light/dark switcher +may want to hide or disable the system value. + +All standard GTK and Libadwaita widgets automatically support both styles. +Applications that use custom drawing or styles may need to ensure the UI +remains legible in both appearances: + +* When possible, use [named colors](named-colors.html) instead of hardcoded + colors. For custom drawing, use [method@Gtk.StyleContext.get_color] to get the + current text color for your widget, or [method@Gtk.StyleContext.lookup_color] + to look up other colors. + +* If that's not possible, use the [property@StyleManager:dark] property to check + the current appearance and vary the drawing accordingly. + +* [class@Application] allows to load additional styles for dark appearance via + the `style-dark.css` resource. + +## High Contrast + +The system can provide a high contrast preference. Libadwaita applications +automatically sepport it; applications cannot disable it. + +High contrast appearance can be combined with the [dark style](#dark-style) and +is independent from it. + +All standard GTK and Libadwaita widgets automatically support the high contrast +appearance. Applications that use custom drawing or styles may need to support +it manually. + +* Use style classes such as [`.dim-label`](style-classes.html#dim-label) instead + of changing widget opacity manually. + +* Use the [@borders](named-colors.html#helper-colors) color for + borders instead of hardcoded colors. + +* The [property@StyleManager:high-contrast] property can be used to check the + current appearance. + +* [class@Application] allows to load additional styles for high contrast + appearance via the `style-hc.css` and `style-hc-dark.css` resources. + +## Custom Styles + +[class@Application] provides a simple way to load additional styles from +[struct@Gio.Resource], relative to the application's base path (see +[method@Gio.Application.set_resource_base_path]). + +When using custom styles, applications should be careful to + +The following resources will automatically be loaded if present: + +- `style.css` contains styles that are always used. +- `style-dark.css` contains styles only used with the dark appearance. +- `style-hc.css` contains styles used with the high contrast appearance. +- `style-hc-dark.css` contains styles used when both dark and high contrast + +Styles are stacked on top of each other: when using dark appearance, both +`style.css` and `style-dark.css` are loaded, and so on. + +## See Also + +- [Style Classes](style-classes.html) +- [Named Colors](named-colors.html) diff --git a/doc/tools/data/adaptive-boxed-lists-narrow.ui b/doc/tools/data/adaptive-boxed-lists-narrow.ui new file mode 100644 index 0000000000000000000000000000000000000000..c3236ec3294bb6bff600b89101c52597bb648acb --- /dev/null +++ b/doc/tools/data/adaptive-boxed-lists-narrow.ui @@ -0,0 +1,71 @@ + + + + + + 360 + 500 + Boxed List + + + + + + + + + + Row 1 + + + + + Row 2 + + + + + Row 3 + + + + + Row 4 + + + + + Row 5 + + + + + Row 6 + + + + + Row 7 + + + + + Row 8 + + + + + Row 9 + + + + + Row 10 + + + + + + + + diff --git a/doc/tools/data/adaptive-boxed-lists-wide.ui b/doc/tools/data/adaptive-boxed-lists-wide.ui new file mode 100644 index 0000000000000000000000000000000000000000..e01cdf1dd6679675fc413a8af39b61fdb5dced9e --- /dev/null +++ b/doc/tools/data/adaptive-boxed-lists-wide.ui @@ -0,0 +1,71 @@ + + + + + + 800 + 500 + Boxed List + + + + + + + + + + Row 1 + + + + + Row 2 + + + + + Row 3 + + + + + Row 4 + + + + + Row 5 + + + + + Row 6 + + + + + Row 7 + + + + + Row 8 + + + + + Row 9 + + + + + Row 10 + + + + + + + + diff --git a/doc/tools/data/adaptive-split-headers-narrow-1.ui b/doc/tools/data/adaptive-split-headers-narrow-1.ui new file mode 100644 index 0000000000000000000000000000000000000000..998153599450d00e5a63f2d7ce928fc97c0b48ec --- /dev/null +++ b/doc/tools/data/adaptive-split-headers-narrow-1.ui @@ -0,0 +1,107 @@ + + + + + + 360 + 500 + + + True + + + vertical + + + + + + Sidebar + + + + + + + True + never + 250 + + + True + + + none + + + + Item 1 + 0 + + + + + Item 2 + 0 + + + + + Item 3 + 0 + + + + + + + + + + + + + False + + + + + + + + vertical + True + 360 + + + + + + + go-previous-symbolic + + + + + Item 1 + + + + + + + Page 1 + True + + + + + + + + + diff --git a/doc/tools/data/adaptive-split-headers-narrow-2.ui b/doc/tools/data/adaptive-split-headers-narrow-2.ui new file mode 100644 index 0000000000000000000000000000000000000000..0f0809f4379fb64bc1535791b7e61af805ebe972 --- /dev/null +++ b/doc/tools/data/adaptive-split-headers-narrow-2.ui @@ -0,0 +1,108 @@ + + + + + + 360 + 500 + + + True + content + + + vertical + + + + + + Sidebar + + + + + + + True + never + 250 + + + True + + + none + + + + Item 1 + 0 + + + + + Item 2 + 0 + + + + + Item 3 + 0 + + + + + + + + + + + + + False + + + + + + + + vertical + True + 360 + + + + + + + go-previous-symbolic + + + + + Item 1 + + + + + + + Page 1 + True + + + + + + + + + diff --git a/doc/tools/data/adaptive-split-headers-wide.ui b/doc/tools/data/adaptive-split-headers-wide.ui new file mode 100644 index 0000000000000000000000000000000000000000..793481e806cfb3055e3a763c21074c1076ab878f --- /dev/null +++ b/doc/tools/data/adaptive-split-headers-wide.ui @@ -0,0 +1,107 @@ + + + + + + 800 + 500 + + + True + + + vertical + + + + + + Sidebar + + + + + + + True + never + 250 + + + True + + + single + + + + Item 1 + 0 + + + + + Item 2 + 0 + + + + + Item 3 + 0 + + + + + + + + + + + + + False + + + + + + + + vertical + True + 360 + + + + + + + go-previous-symbolic + + + + + Item 1 + + + + + + + Page 1 + True + + + + + + + + + diff --git a/doc/tools/data/adaptive-utility-pane-narrow.ui b/doc/tools/data/adaptive-utility-pane-narrow.ui new file mode 100644 index 0000000000000000000000000000000000000000..62ebe991761a84a46dd4b3943301bcc4ac21c9dd --- /dev/null +++ b/doc/tools/data/adaptive-utility-pane-narrow.ui @@ -0,0 +1,53 @@ + + + + + + 360 + 500 + Utility Pane + + + + + sidebar-show-symbolic + True + + + + + + + + True + + + Utility Pane + True + 250 + + + + + + + + + 360 + Main View + True + + + + + + + diff --git a/doc/tools/data/adaptive-utility-pane-wide.ui b/doc/tools/data/adaptive-utility-pane-wide.ui new file mode 100644 index 0000000000000000000000000000000000000000..170c2c5275c7f8b2986493e96cf4a2982e1b4f40 --- /dev/null +++ b/doc/tools/data/adaptive-utility-pane-wide.ui @@ -0,0 +1,53 @@ + + + + + + 800 + 500 + Utility Pane + + + + + sidebar-show-symbolic + True + + + + + + + + True + + + Utility Pane + True + 250 + + + + + + + + + 360 + Main View + True + + + + + + + diff --git a/doc/tools/data/adaptive-view-switcher-narrow.ui b/doc/tools/data/adaptive-view-switcher-narrow.ui new file mode 100644 index 0000000000000000000000000000000000000000..dd87a61340f96e7450ad984cd4b6de7fb6fdfdc0 --- /dev/null +++ b/doc/tools/data/adaptive-view-switcher-narrow.ui @@ -0,0 +1,94 @@ + + + + + + 360 + 500 + + + strict + + + stack + View Switcher + + + + + + + vertical + + + True + + + View 1 + folder-music-symbolic + + + View 1 + + + + + + + + View 2 + folder-pictures-symbolic + + + View 2 + + + + + + + + View 3 + folder-videos-symbolic + + + View 3 + + + + + + + + View 4 + non-starred-symbolic + + + View 4 + + + + + + + + + + stack + + title + + + + + + + diff --git a/doc/tools/data/adaptive-view-switcher-wide.ui b/doc/tools/data/adaptive-view-switcher-wide.ui new file mode 100644 index 0000000000000000000000000000000000000000..1fa421af3fd06de7350bfe31f09dd410bf5c70cd --- /dev/null +++ b/doc/tools/data/adaptive-view-switcher-wide.ui @@ -0,0 +1,94 @@ + + + + + + 800 + 500 + + + strict + + + stack + View Switcher + + + + + + + vertical + + + True + + + View 1 + folder-music-symbolic + + + View 1 + + + + + + + + View 2 + folder-pictures-symbolic + + + View 2 + + + + + + + + View 3 + folder-videos-symbolic + + + View 3 + + + + + + + + View 4 + non-starred-symbolic + + + View 4 + + + + + + + + + + stack + + title + + + + + + + diff --git a/doc/tools/screenshot.gresources.xml b/doc/tools/screenshot.gresources.xml index c7ce7e47b594835e27f4d17bf8f8e7724818e05d..536029bd813783883649d7d941d2749b001bf1a3 100644 --- a/doc/tools/screenshot.gresources.xml +++ b/doc/tools/screenshot.gresources.xml @@ -4,6 +4,15 @@ icons/scalable/apps/org.gnome.Boxes.svg data/action-row.ui + data/adaptive-boxed-lists-narrow.ui + data/adaptive-boxed-lists-wide.ui + data/adaptive-split-headers-narrow-1.ui + data/adaptive-split-headers-narrow-2.ui + data/adaptive-split-headers-wide.ui + data/adaptive-utility-pane-narrow.ui + data/adaptive-utility-pane-wide.ui + data/adaptive-view-switcher-narrow.ui + data/adaptive-view-switcher-wide.ui data/app-icons.ui data/application-window.ui data/avatar.ui diff --git a/src/adw-header-bar.c b/src/adw-header-bar.c index f2bd7316d93bcd3dd96ec0c1dad18a22ef606684..4a2517d403aa6b3d48f8e73d9c77cff2c9bf07f5 100644 --- a/src/adw-header-bar.c +++ b/src/adw-header-bar.c @@ -60,10 +60,10 @@ * * * - * ... + * * * - * ... + * * * * vertical @@ -75,7 +75,7 @@ * * * - * ... + * * * * diff --git a/src/adw-view-switcher-bar.c b/src/adw-view-switcher-bar.c index 75fcbfeb6291fbea63820f6612be39e0a1f05b9e..88479e7883e6dcd6b58c951753fdb0a14fe09cab 100644 --- a/src/adw-view-switcher-bar.c +++ b/src/adw-view-switcher-bar.c @@ -26,12 +26,13 @@ * at the bottom of a window and to be revealed only on really narrow windows, * e.g. on mobile phones. It can't be revealed if there are less than two pages. * - * You can conveniently bind the [property@Adw.ViewSwitcherBar:reveal] property - * to [property@Adw.ViewSwitcherTitle:title-visible] to automatically reveal the - * view switcher bar when the title label is displayed in place of the view - * switcher. + * `Adw.ViewSwitcherBar` is intended to be used together with + * [class@Adw.ViewSwitcherTitle]. * - * An example of the UI definition for a common use case: + * A common use case is to bind the [property@Adw.ViewSwitcherBar:reveal] + * property to [property@Adw.ViewSwitcherTitle:title-visible] to automatically + * reveal the view switcher bar when the title label is displayed in place of + * the view switcher, as follows: * * ```xml * diff --git a/src/adw-view-switcher-title.c b/src/adw-view-switcher-title.c index 75c39d5f9aaee85bea6bf250edae19124b0b6839..b3cfa0dc77f903e9696179ad474d09d9426f0d76 100644 --- a/src/adw-view-switcher-title.c +++ b/src/adw-view-switcher-title.c @@ -29,12 +29,17 @@ * will display the window's title when the window is too narrow to fit the view * switcher e.g. on mobile phones, or if there are less than two views. * - * You can conveniently bind the [property@Adw.ViewSwitcherBar:reveal] property - * to [property@Adw.ViewSwitcherTitle:title-visible] to automatically reveal the - * view switcher bar when the title label is displayed in place of the view - * switcher. + * In order to center the title in narrow windows, the header bar should have + * [property@Adw.HeaderBar:centering-policy] set to + * `ADW_CENTERING_POLICY_STRICT`. * - * An example of the UI definition for a common use case: + * `Adw.ViewSwitcherTitle` is intended to be used together with + * [class@Adw.ViewSwitcherBar]. + * + * A common use case is to bind the [property@Adw.ViewSwitcherBar:reveal] + * property to [property@Adw.ViewSwitcherTitle:title-visible] to automatically + * reveal the view switcher bar when the title label is displayed in place of + * the view switcher, as follows: * * ```xml * diff --git a/src/adw-view-switcher.c b/src/adw-view-switcher.c index df6200a354daa210a88994df991acd63753f4b2f..071f4484ddc04a425ead9363413e383bd27731fe 100644 --- a/src/adw-view-switcher.c +++ b/src/adw-view-switcher.c @@ -29,10 +29,12 @@ * contained in a [class@Adw.ViewStack] in a similar fashion to * [class@Gtk.StackSwitcher]. * - * Depending on the available width, the view switcher can adapt from a wide - * mode showing the view's icon and title side by side, to a narrow mode showing - * the view's icon and title one on top of the other, in a more compact way. - * This can be controlled via the [property@Adw.ViewSwitcher:policy] property. + * `AdwViewSwitcher` buttons always have an icon and a label. They can be + * displayed side by side, or icon on top of the label. This can be controlled + * via the [property@Adw.ViewSwitcher:policy] property. + * + * Most applications should be using [class@Adw.ViewSwitcherBar] and + * [class@Adw.ViewSwitcherTitle]. * * ## CSS nodes *