diff --git a/demo/pages/styles/adw-style-demo-window.c b/demo/pages/styles/adw-style-demo-window.c index d156bc4f2e3c5a36d8305b1299bb8f9aec82f945..41c1cbecf6121b966ffb9b40dda6cec259a2872d 100644 --- a/demo/pages/styles/adw-style-demo-window.c +++ b/demo/pages/styles/adw-style-demo-window.c @@ -8,7 +8,6 @@ struct _AdwStyleDemoWindow gboolean progress; - GtkWindow *header_bar_window; GtkWindow *status_page_window; GtkWindow *sidebar_window; AdwNavigationSplitView *split_view; @@ -25,16 +24,6 @@ enum { static GParamSpec *props[LAST_PROP]; -static void -header_bar_cb (GtkWidget *sender, - const char *name, - GVariant *param) -{ - AdwStyleDemoWindow *self = ADW_STYLE_DEMO_WINDOW (sender); - - gtk_window_present (self->header_bar_window); -} - static void status_page_cb (GtkWidget *sender, const char *name, @@ -68,11 +57,9 @@ set_devel_style (AdwStyleDemoWindow *self, { if (devel) { gtk_widget_add_css_class (GTK_WIDGET (self), "devel"); - gtk_widget_add_css_class (GTK_WIDGET (self->header_bar_window), "devel"); gtk_widget_add_css_class (GTK_WIDGET (self->status_page_window), "devel"); } else { gtk_widget_remove_css_class (GTK_WIDGET (self), "devel"); - gtk_widget_remove_css_class (GTK_WIDGET (self->header_bar_window), "devel"); gtk_widget_remove_css_class (GTK_WIDGET (self->status_page_window), "devel"); } } @@ -128,9 +115,6 @@ adw_style_demo_window_dispose (GObject *object) { AdwStyleDemoWindow *self = ADW_STYLE_DEMO_WINDOW (object); - if (self->header_bar_window) - gtk_window_destroy (self->header_bar_window); - if (self->status_page_window) gtk_window_destroy (self->status_page_window); @@ -163,7 +147,6 @@ adw_style_demo_window_class_init (AdwStyleDemoWindowClass *klass) g_object_class_install_properties (object_class, LAST_PROP, props); gtk_widget_class_set_template_from_resource (widget_class, "/org/gnome/Adwaita1/Demo/ui/pages/styles/adw-style-demo-window.ui"); - gtk_widget_class_bind_template_child (widget_class, AdwStyleDemoWindow, header_bar_window); gtk_widget_class_bind_template_child (widget_class, AdwStyleDemoWindow, status_page_window); gtk_widget_class_bind_template_child (widget_class, AdwStyleDemoWindow, sidebar_window); gtk_widget_class_bind_template_child (widget_class, AdwStyleDemoWindow, split_view); @@ -171,7 +154,6 @@ adw_style_demo_window_class_init (AdwStyleDemoWindowClass *klass) gtk_widget_class_install_property_action (widget_class, "style.devel", "devel"); gtk_widget_class_install_property_action (widget_class, "style.progress", "progress"); - gtk_widget_class_install_action (widget_class, "style.header-bar", NULL, header_bar_cb); gtk_widget_class_install_action (widget_class, "style.status-page", NULL, status_page_cb); gtk_widget_class_install_action (widget_class, "style.sidebar", NULL, sidebar_cb); gtk_widget_class_install_action (widget_class, "style.dummy", NULL, dummy_cb); diff --git a/demo/pages/styles/adw-style-demo-window.ui b/demo/pages/styles/adw-style-demo-window.ui index 6841d4dd00b9e09fd91559eb845869e60454118e..e173fc4473c8acfb28c1e998d2421c4aacdb9e2f 100644 --- a/demo/pages/styles/adw-style-demo-window.ui +++ b/demo/pages/styles/adw-style-demo-window.ui @@ -1021,21 +1021,6 @@ audio-volume-medium Misc - - - Flat Header Bar - True - style.header-bar - - - go-next-symbolic - - - - - Status Pages @@ -1100,31 +1085,6 @@ audio-volume-medium - - True - AdwStyleDemoWindow - Flat Header Bar - True - - - flat - False - - - - - - True - The header bar in this window has the "flat" style class. - True - 48 - 48 - 48 - - - True AdwStyleDemoWindow diff --git a/demo/pages/view-switcher/adw-view-switcher-demo-window.ui b/demo/pages/view-switcher/adw-view-switcher-demo-window.ui index 6fb80e025fa5fd98d4c144a36f42e308070c468f..3283d1210376034667da1fa1a14d35e88e1a2449 100644 --- a/demo/pages/view-switcher/adw-view-switcher-demo-window.ui +++ b/demo/pages/view-switcher/adw-view-switcher-demo-window.ui @@ -13,7 +13,6 @@ - strict stack diff --git a/doc/adaptive-layouts.md b/doc/adaptive-layouts.md index 40ef716f2bb8085f9012846ad5f7962c34eb79d3..3fa2a959f46f307edf745e96a78df02d0c180f70 100644 --- a/doc/adaptive-layouts.md +++ b/doc/adaptive-layouts.md @@ -7,7 +7,7 @@ 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 +# 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 @@ -51,111 +51,164 @@ This is commonly used for patterns such as [boxed lists](boxed-lists.html): See also: [class@ClampLayout], [class@ClampScrollable]. -## Leaflet +# Breakpoints -[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]. +[class@Breakpoint] allows applications to restructure UI in arbitrary ways +depending on available size. Breakpoints can be used with [class@Window], +[class@ApplicationWindow], or [class@BreakpointBin]. -A common use for a leaflet is implementing a split header bar layout, with a -sidebar, a content view, and a separator between them: +When using breakpoints, the widget containing them will have no minimum size, +and the application must manually set the [property@Gtk.Widget:width-request] +and [property@Gtk.Widget:height-request] properties, indicating the smallest +supported size. + +All of the examples below use breakpoints. + +# View Switcher + +The [class@ViewSwitcher] 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. An [class@Breakpoint] is used to +switch between them depending on available width. - - adaptive-split-headers-wide - - - - adaptive-split-headers-narrow-1 + + adaptive-view-switcher-wide - - - adaptive-split-headers-narrow-2 + + + adaptive-view-switcher-narrow ```xml - - True - - - raised - - - - leaflet - - - - Sidebar - - - - - - - - - - False - - - - - - - - raised - True> - - - - leaflet - - - - - leaflet - - go-previous-symbolic - - - - - Content - - - - - - - - + + 360 + 200 + + + max-width: 550sp + True + + + + + + + + + + stack + wide + + + + + + + + + + stack + + + + + ``` -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. +You may need to adjust the breakpoint threshold depending on the number of +pages in your application, as well as their titles. + +# Split Views + +Libadwaita provides two containers for creating multi-pane layouts that can +collapse on small widths: [class@NavigationSplitView] and +[class@OverlaySplitView]. + +Both widgets have two children: sidebar and content. They are typically used +together with a [class@Breakpoint] toggling their `collapsed` property for +narrow widths. + +## Navigation Split View -The application needs to provide a back button and to switch leaflet's visible -child to content as 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. +`AdwNavigationSplitView` turns into an [class@NavigationView] when collapsed, +containing the sidebar as the root page and content as its subpage. Only +[class@NavigationPage] can be used for both the sidebar and content. -Split header bars are typically used with [class@Window] or -[class@ApplicationWindow], since the layout already contains header bars. + + + adaptive-sidebar-wide + + + + adaptive-sidebar-narrow-1 + + + + adaptive-sidebar-narrow-2 + -## Flap +```xml + + 360 + 200 + + + max-width: 400sp + True + + + + + + + Sidebar + sidebar + + + + + + + + + + + + + + + Content + content + + + + + + + + + + + + + + + +``` + +`AdwHeaderBar` will automatically provide a back button, manage window controls +and display the title from its `AdwNavigationPage`. -[class@Flap] shows children side by side when there's enough room, or overlays -one child on top of the other otherwise. +## Overlay Split View -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]. +`AdwOverlaySplitView` shows the sidebar as an overlay above the content when +collapsed. It's commonly used to implement +[utility panes](https://developer.gnome.org/hig/patterns/containers/utility-panes.html), +but can be used with split header bars as well. @@ -167,120 +220,261 @@ via setting the utility pane as the [property@Flap:flap] and the main view as ```xml - - sidebar-show-symbolic - True - - - - - - - - - - + + 360 + 200 + + + max-width: 400sp + True + + - + + raised + + + + + 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. +and hide it on mobile, you can toggle the button's visibility with your +breakpoint: ```xml + + max-width: 400sp + True + True + + sidebar-show-symbolic True - - - - - - - - - - - - - - - - + False ``` -## View Switcher +## Triple Pane Layouts -The [class@ViewSwitcherTitle] and [class@ViewSwitcherBar] widgets implement an -adaptive [view switcher](https://developer.gnome.org/hig/patterns/nav/view-switchers.html). +Both split views can be used for creating triple pane layouts, via nesting two +of the views within one another. The inner view can be placed as the sidebar or +content widget in the outer view, depending on how you want to handle collapsing. -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. +An example of a triple-pane layout with the an `AdwNavigationSplitView` nested +within another `AdwNavigationSplitView`'s sidebar: + +```xml + + 360 + 200 + + + max-width: 860sp + True + 0.33 + + + + + max-width: 500sp + True + 0.33 + True + + + + + 470 + 780 + 0.47 + + + + + 260 + 0.38 + + + + + + + + + + + + + + + + +``` - - adaptive-view-switcher-wide + + adaptive-triple-pane-wide - - - adaptive-view-switcher-narrow + + + adaptive-triple-pane-medium + + + + adaptive-triple-pane-narrow-3 + + + + adaptive-triple-pane-narrow-1 + + + + adaptive-triple-pane-narrow-2 +When only the outer split view is collapsed, either the content is visible or +the sidebar and middle pane are visible. When both split views are collapsed, +only one pane is visible at a time. + +An example of a triple-pane layout with the an `AdwNavigationSplitView` nested +within an `AdwOverlaySplitView`'s content: + ```xml - - - - strict - - - stack - - + + 360 + 200 + + + max-width: 860sp + True + + + + + max-width: 500sp + True + True - - + + 260 + 0.179 + + + + + + 290 + 520 + 0.355 + + + + + + + + - - - 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. +When only the outer split view is collapsed the middle pane and content are +visible, and the sidebar can be overlaid above them. -## Squeezer +# Tabs -[class@Squeezer] is similar to [class@Gtk.Stack], but shows the largest of its -children that can fit into the available space. +[class@TabView] is a dynamic tab container. It doesn't have a visible tab +switcher on its own, leaving that to [class@TabBar], [class@TabButton] and +[class@TabOverview]. When used together with breakpoints, these widgets can +provide an adaptive tabbed interface. -For example, [class@ViewSwitcherTitle] uses it to conditionally show a view -switcher or the window title. +```xml + + 360 + 200 + + + max-width: 500px + True + False + False + + + + + view + True + + + raised + + + + + False + view + overview.open + + + + + tab-new-symbolic + + + + + + + view + + + + + + + + + + +``` + + + + adaptive-tabs-wide + + + + adaptive-tabs-narrow-1 + + + + adaptive-tabs-narrow-2 + diff --git a/doc/images/adaptive-sidebar-narrow-1-dark.png b/doc/images/adaptive-sidebar-narrow-1-dark.png new file mode 100644 index 0000000000000000000000000000000000000000..2cff3f2f2fb9655d5c2aa30a5d6dc395299c04d5 Binary files /dev/null and b/doc/images/adaptive-sidebar-narrow-1-dark.png differ diff --git a/doc/images/adaptive-sidebar-narrow-1.png b/doc/images/adaptive-sidebar-narrow-1.png new file mode 100644 index 0000000000000000000000000000000000000000..5ba6566966edce0304e209c2c90bb103dde3655f Binary files /dev/null and b/doc/images/adaptive-sidebar-narrow-1.png differ diff --git a/doc/images/adaptive-sidebar-narrow-2-dark.png b/doc/images/adaptive-sidebar-narrow-2-dark.png new file mode 100644 index 0000000000000000000000000000000000000000..2c08c1c5b75249dc070a7dd7e975e39e4dfb6300 Binary files /dev/null and b/doc/images/adaptive-sidebar-narrow-2-dark.png differ diff --git a/doc/images/adaptive-sidebar-narrow-2.png b/doc/images/adaptive-sidebar-narrow-2.png new file mode 100644 index 0000000000000000000000000000000000000000..bfc3893a28d15aae313b2839248ba02b4d288353 Binary files /dev/null and b/doc/images/adaptive-sidebar-narrow-2.png differ diff --git a/doc/images/adaptive-sidebar-wide-dark.png b/doc/images/adaptive-sidebar-wide-dark.png new file mode 100644 index 0000000000000000000000000000000000000000..6a2a2fd161983a7b03a601c5f134698fd42e1d58 Binary files /dev/null and b/doc/images/adaptive-sidebar-wide-dark.png differ diff --git a/doc/images/adaptive-sidebar-wide.png b/doc/images/adaptive-sidebar-wide.png new file mode 100644 index 0000000000000000000000000000000000000000..7c9391eb5b4242a121378f6b405ef8bd0ba50610 Binary files /dev/null and b/doc/images/adaptive-sidebar-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 deleted file mode 100644 index 25f127ef1000aaab69320ef67b3c9d4841128cb6..0000000000000000000000000000000000000000 Binary files a/doc/images/adaptive-split-headers-narrow-1-dark.png and /dev/null differ diff --git a/doc/images/adaptive-split-headers-narrow-1.png b/doc/images/adaptive-split-headers-narrow-1.png deleted file mode 100644 index 61dbf9e9c70083ec96fe087e87fb645c6756914b..0000000000000000000000000000000000000000 Binary files a/doc/images/adaptive-split-headers-narrow-1.png and /dev/null differ diff --git a/doc/images/adaptive-split-headers-narrow-2-dark.png b/doc/images/adaptive-split-headers-narrow-2-dark.png deleted file mode 100644 index f575a66e392ec8c67bd97504748cb3388d9c0fe4..0000000000000000000000000000000000000000 Binary files a/doc/images/adaptive-split-headers-narrow-2-dark.png and /dev/null differ diff --git a/doc/images/adaptive-split-headers-narrow-2.png b/doc/images/adaptive-split-headers-narrow-2.png deleted file mode 100644 index 062fbe0966facb8efd3f6be24054ea482fb979f4..0000000000000000000000000000000000000000 Binary files a/doc/images/adaptive-split-headers-narrow-2.png and /dev/null differ diff --git a/doc/images/adaptive-split-headers-wide-dark.png b/doc/images/adaptive-split-headers-wide-dark.png deleted file mode 100644 index 28e28aaacce61d2ba19fbef5821ee49472c4c0a1..0000000000000000000000000000000000000000 Binary files a/doc/images/adaptive-split-headers-wide-dark.png and /dev/null differ diff --git a/doc/images/adaptive-split-headers-wide.png b/doc/images/adaptive-split-headers-wide.png deleted file mode 100644 index e93e5392fce4740a77fcd20c1c653a22562d26ce..0000000000000000000000000000000000000000 Binary files a/doc/images/adaptive-split-headers-wide.png and /dev/null differ diff --git a/doc/images/adaptive-tabs-narrow-1-dark.png b/doc/images/adaptive-tabs-narrow-1-dark.png new file mode 100644 index 0000000000000000000000000000000000000000..b45f1099de11347ec4160a11d20e3456d229ce88 Binary files /dev/null and b/doc/images/adaptive-tabs-narrow-1-dark.png differ diff --git a/doc/images/adaptive-tabs-narrow-1.png b/doc/images/adaptive-tabs-narrow-1.png new file mode 100644 index 0000000000000000000000000000000000000000..7bdfd8c779f6d28af8bc78a4f04349d22974c09b Binary files /dev/null and b/doc/images/adaptive-tabs-narrow-1.png differ diff --git a/doc/images/adaptive-tabs-narrow-2-dark.png b/doc/images/adaptive-tabs-narrow-2-dark.png new file mode 100644 index 0000000000000000000000000000000000000000..0c2a7fd7cb4d22a4a42efd7dba74404d7d6cfb39 Binary files /dev/null and b/doc/images/adaptive-tabs-narrow-2-dark.png differ diff --git a/doc/images/adaptive-tabs-narrow-2.png b/doc/images/adaptive-tabs-narrow-2.png new file mode 100644 index 0000000000000000000000000000000000000000..be672eb50792d8396b7e0a660e777b18a89135d4 Binary files /dev/null and b/doc/images/adaptive-tabs-narrow-2.png differ diff --git a/doc/images/adaptive-tabs-wide-dark.png b/doc/images/adaptive-tabs-wide-dark.png new file mode 100644 index 0000000000000000000000000000000000000000..666e3d96ef45193ff42e3280520aff93a0c1e208 Binary files /dev/null and b/doc/images/adaptive-tabs-wide-dark.png differ diff --git a/doc/images/adaptive-tabs-wide.png b/doc/images/adaptive-tabs-wide.png new file mode 100644 index 0000000000000000000000000000000000000000..b3137f1a20b59a3ac0652aa482b97fd362480894 Binary files /dev/null and b/doc/images/adaptive-tabs-wide.png differ diff --git a/doc/images/adaptive-triple-pane-medium-dark.png b/doc/images/adaptive-triple-pane-medium-dark.png new file mode 100644 index 0000000000000000000000000000000000000000..766ac13e04fed0fe0d44336161a5042c212735bf Binary files /dev/null and b/doc/images/adaptive-triple-pane-medium-dark.png differ diff --git a/doc/images/adaptive-triple-pane-medium.png b/doc/images/adaptive-triple-pane-medium.png new file mode 100644 index 0000000000000000000000000000000000000000..1cec537cdf0ee4f62dea848e280ea51fb80c4a7e Binary files /dev/null and b/doc/images/adaptive-triple-pane-medium.png differ diff --git a/doc/images/adaptive-triple-pane-narrow-1-dark.png b/doc/images/adaptive-triple-pane-narrow-1-dark.png new file mode 100644 index 0000000000000000000000000000000000000000..1004f1d687c1d21f9bb4bfc39bbfd6702c105230 Binary files /dev/null and b/doc/images/adaptive-triple-pane-narrow-1-dark.png differ diff --git a/doc/images/adaptive-triple-pane-narrow-1.png b/doc/images/adaptive-triple-pane-narrow-1.png new file mode 100644 index 0000000000000000000000000000000000000000..ba6834cef92a1906a815c6d4a3ddf176350d2358 Binary files /dev/null and b/doc/images/adaptive-triple-pane-narrow-1.png differ diff --git a/doc/images/adaptive-triple-pane-narrow-2-dark.png b/doc/images/adaptive-triple-pane-narrow-2-dark.png new file mode 100644 index 0000000000000000000000000000000000000000..5ae7a9cc36a2255166e87ec61217aed79d98e9d8 Binary files /dev/null and b/doc/images/adaptive-triple-pane-narrow-2-dark.png differ diff --git a/doc/images/adaptive-triple-pane-narrow-2.png b/doc/images/adaptive-triple-pane-narrow-2.png new file mode 100644 index 0000000000000000000000000000000000000000..92a9c824607c398f9bb18a83558d7448a8fbb60a Binary files /dev/null and b/doc/images/adaptive-triple-pane-narrow-2.png differ diff --git a/doc/images/adaptive-triple-pane-narrow-3-dark.png b/doc/images/adaptive-triple-pane-narrow-3-dark.png new file mode 100644 index 0000000000000000000000000000000000000000..5fafe5366533eb43abc7d757b68752fb12868fc9 Binary files /dev/null and b/doc/images/adaptive-triple-pane-narrow-3-dark.png differ diff --git a/doc/images/adaptive-triple-pane-narrow-3.png b/doc/images/adaptive-triple-pane-narrow-3.png new file mode 100644 index 0000000000000000000000000000000000000000..7327e240fe420ebd1299dd872ef30145863d8309 Binary files /dev/null and b/doc/images/adaptive-triple-pane-narrow-3.png differ diff --git a/doc/images/adaptive-triple-pane-wide-dark.png b/doc/images/adaptive-triple-pane-wide-dark.png new file mode 100644 index 0000000000000000000000000000000000000000..da6a24b9846acfa1ee521183f10781c1678710d3 Binary files /dev/null and b/doc/images/adaptive-triple-pane-wide-dark.png differ diff --git a/doc/images/adaptive-triple-pane-wide.png b/doc/images/adaptive-triple-pane-wide.png new file mode 100644 index 0000000000000000000000000000000000000000..7794eb147672344815701c056237ed22d41019cd Binary files /dev/null and b/doc/images/adaptive-triple-pane-wide.png differ diff --git a/doc/images/adaptive-utility-pane-narrow-dark.png b/doc/images/adaptive-utility-pane-narrow-dark.png index 67729526a0977cec8d8f9c4a1276fdfbb718d010..2597d1111f8dcf4479ee9876d4e26eb2b12df725 100644 Binary files a/doc/images/adaptive-utility-pane-narrow-dark.png 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 index ab9f3c695887f587165fad569a7a15ae24cdcbe2..523930ab2983dfdfab8c4bc4cfd2646eb2ee00a2 100644 Binary files a/doc/images/adaptive-utility-pane-narrow.png 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 index 064c867d0c56ac383b37bbce9a6b03b0fa5af3de..8558a971e1b400fb311bd9de7778dc30a6c259ee 100644 Binary files a/doc/images/adaptive-utility-pane-wide-dark.png 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 index b98fd3d2942daa9bfa6a8fe509282cad878bca60..b19c3cf97ed345e11c1663a3cd441b1cb0f16916 100644 Binary files a/doc/images/adaptive-utility-pane-wide.png and b/doc/images/adaptive-utility-pane-wide.png differ diff --git a/doc/images/header-bar-split-dark.png b/doc/images/header-bar-split-dark.png deleted file mode 100644 index 4525f719d31e796847a85818e54da6d4d8d0f590..0000000000000000000000000000000000000000 Binary files a/doc/images/header-bar-split-dark.png and /dev/null differ diff --git a/doc/images/header-bar-split.png b/doc/images/header-bar-split.png deleted file mode 100644 index 5b896667a82319607e44588cc09cc4c526dc7507..0000000000000000000000000000000000000000 Binary files a/doc/images/header-bar-split.png and /dev/null differ diff --git a/doc/images/tab-overview-dark.png b/doc/images/tab-overview-dark.png index cacfb40786e7f054cedf067aed9238a9864c1430..9458b28b255adee74f34ab7130a4870f06d8a23a 100644 Binary files a/doc/images/tab-overview-dark.png and b/doc/images/tab-overview-dark.png differ diff --git a/doc/images/view-switcher-dark.png b/doc/images/view-switcher-dark.png index aee27e644fde206a3f210910b614b495d7e12c33..81707290f3a7288ddf86757c0fce9e5ed9cd0bb6 100644 Binary files a/doc/images/view-switcher-dark.png and b/doc/images/view-switcher-dark.png differ diff --git a/doc/images/view-switcher.png b/doc/images/view-switcher.png index 553cacc3d0bc0bd3aa49671c27d3fd535475a28c..0e20044e3da0507bb8591d000d4d08947d7e0e8c 100644 Binary files a/doc/images/view-switcher.png and b/doc/images/view-switcher.png differ diff --git a/doc/libadwaita.toml.in b/doc/libadwaita.toml.in index ee59c1a77801c6448c0d0ade3a31371fa6fcf460..7e89b915d93d1e42f5f6d9792f9a76efde30e5fc 100644 --- a/doc/libadwaita.toml.in +++ b/doc/libadwaita.toml.in @@ -48,7 +48,6 @@ content_files = [ "named-colors.md", "style-classes.md", - "migrating-between-development-versions.md", "migrating-libhandy-1-4-to-libadwaita.md", "widget-gallery.md", @@ -64,12 +63,28 @@ content_images = [ "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-sidebar-narrow-1.png", + "images/adaptive-sidebar-narrow-1-dark.png", + "images/adaptive-sidebar-narrow-2.png", + "images/adaptive-sidebar-narrow-2-dark.png", + "images/adaptive-sidebar-wide.png", + "images/adaptive-sidebar-wide-dark.png", + "images/adaptive-tabs-narrow-1.png", + "images/adaptive-tabs-narrow-1-dark.png", + "images/adaptive-tabs-narrow-2.png", + "images/adaptive-tabs-narrow-2-dark.png", + "images/adaptive-tabs-wide.png", + "images/adaptive-tabs-wide-dark.png", + "images/adaptive-triple-pane-narrow-1.png", + "images/adaptive-triple-pane-narrow-1-dark.png", + "images/adaptive-triple-pane-narrow-2.png", + "images/adaptive-triple-pane-narrow-2-dark.png", + "images/adaptive-triple-pane-narrow-3.png", + "images/adaptive-triple-pane-narrow-3-dark.png", + "images/adaptive-triple-pane-medium.png", + "images/adaptive-triple-pane-medium-dark.png", + "images/adaptive-triple-pane-wide.png", + "images/adaptive-triple-pane-wide-dark.png", "images/adaptive-utility-pane-narrow.png", "images/adaptive-utility-pane-narrow-dark.png", "images/adaptive-utility-pane-wide.png", @@ -142,8 +157,6 @@ content_images = [ "images/flat-header-bar-dark.png", "images/header-bar.png", "images/header-bar-dark.png", - "images/header-bar-split.png", - "images/header-bar-split-dark.png", "images/hello-world.png", "images/hello-world-dark.png", "images/leaflet-narrow.png", diff --git a/doc/meson.build b/doc/meson.build index 1126fd323de30d6be2e8fbf7624c0bcfa30cf1a5..cf694624f4415d6d753afba757584e759a4bfb1e 100644 --- a/doc/meson.build +++ b/doc/meson.build @@ -7,7 +7,6 @@ expand_content_md_files = [ 'boxed-lists.md', 'build-howto.md', 'initialization.md', - 'migrating-between-development-versions.md', 'migrating-libhandy-1-4-to-libadwaita.md', 'named-colors.md', 'styles-and-appearance.md', diff --git a/doc/migrating-between-development-versions.md b/doc/migrating-between-development-versions.md deleted file mode 100644 index 183e0951ed6c2657f9d3dc27667e0c962aa1d889..0000000000000000000000000000000000000000 --- a/doc/migrating-between-development-versions.md +++ /dev/null @@ -1,356 +0,0 @@ -Title: Migrating between development versions -Slug: migrating-between-development-versions - -# Migrating Between Development Versions - -This guide outlines the differences between Libadwaita development releases. -It assumes you've already migrated from Libhandy 1.4 to Libadwaita, or you -created a new project using a development release of Libadwaita. - -If you want to migrate from Libhandy 1.4 to the latest Libadwaita release, -[follow this guide](migrating-libhandy-1-4-to-libadwaita.html). - -## Migrating From alpha 1 to alpha 2 - -### Adapt to view switcher API Changes - -[class@ViewSwitcher], [class@ViewSwitcherBar] and [class@ViewSwitcherTitle] now -use [class@ViewStack] instead of [class@Gtk.Stack]. - -You should stop using [property@Gtk.Stack:transition-type] and -[property@Gtk.Stack:transition-duration] properties before switching to -[class@ViewStack]. - -### Adapt to Stylesheet Changes - -If you were using -[@theme_selected_bg_color](named-colors.html#compatibility-colors) -as a text color, use -[@accent_color](named-colors.html#accent-colors) instead to -make sure the text is readable. You can also use the -[`.accent`](style-classes.html#colors) style class to apply the correct color. - -## Migrating From alpha 2 to alpha 3 - -### Stop Using `AdwValueObject` With Non-string Values - -`AdwValueObject` has been removed. The typical use for storing strings in -combination with [class@Gio.ListStore] can be replaced by using -[class@Gtk.StringList], others cases can be replaced by creating your own -objects to store those values . - -### Adapt to `AdwEnumValueObject` API Changes - -`AdwEnumValueObject` has been renamed to [class@EnumListItem]. - -### Adapt to Window API Changes - -The `child` property in [class@Window] and [class@ApplicationWindow] has -been renamed to `content`. - -### Adapt to [class@Leaflet] API Changes - -The `hhomogeneous-folded`, `vhomogeneous-folded`, `hhomogeneous-unfolded`, and -`vhomogeneous-unfolded` properties have been replaced by a single -[property@Leaflet:homogeneous] property, set to `TRUE` by default, applied when -the leaflet is folded for the opposite orientation. - -When unfolded, children are never homogeneous. Use [class@Gtk.SizeGroup] to make -them homogeneous if needed. - -The `interpolate-size` property has been removed with no replacement, it's -always enabled when [property@Leaflet:homogeneous] is set to `FALSE`. - -### Adapt to View Switcher API Changes - -The `auto` view switcher policy has been removed. [class@ViewSwitcher] only has -narrow and wide policies; if you had used the `auto` policy, use an -[class@Squeezer] with two view switchers inside. - -#### Adapt to [class@ViewSwitcher] API Changes - -The `narrow-ellipsize` property has been removed. Narrow view switchers always -ellipsize their labels, wide switchers never do. - -#### Adapt to [class@ViewSwitcherBar] API Changes - -The `policy` property has been removed. If you had used it, use a plain -[class@ViewSwitcher] in a [class@Gtk.ActionBar] instead. - -#### Adapt to [class@ViewSwitcherTitle] API Changes - -The `policy` property has been removed, the behavior is similar to the removed -`auto` policy. If you had used `wide` or `narrow` policies, use an -[class@Squeezer] with an [class@ViewSwitcher] and an [class@WindowTitle] inside, -with the switcher having the desired policy. - -### Adapt to [class@Avatar] API Changes - -The `adw_avatar_draw_to_pixbuf()` function have been removed, use the newly -added [method@Avatar.draw_to_texture] instead. [class@Gdk.Texture] implements -[iface@Gio.Icon], so it should just work for that case. - -[method@Avatar.draw_to_texture] does not have the `size` parameter. Instead, it -uses the avatar's current size, with no replacement. - -### Use [class@StyleManager] Instead of [property@Gtk.Settings:gtk-application-prefer-dark-theme] - -Using [property@Gtk.Settings:gtk-application-prefer-dark-theme] to control dark -appearance is not supported anymore, set [property@StyleManager:color-scheme] to -`ADW_COLOR_SCHEME_PREFER_DARK` and make sure the application can work with light -appearance as well. If that's not possible, set it to or -`ADW_COLOR_SCHEME_FORCE_DARK` instead. - -If your application is using light appearance, make sure it works wit dark -appearance as well, or set the color scheme to `ADW_COLOR_SCHEME_FORCE_LIGHT` -otherwise. - -### Adapt to Stylesheet Changes - -#### Adapt to Header Bar, Action Bar and Toolbar Style Changes - -When possible, buttons in [class@Gtk.HeaderBar] and [class@Gtk.ActionBar] will -use flat appearance by default. - -The following rules are used when deciding when to make buttons flat or not: - -The following buttons get flat appearance: - -* Icon-only buttons; -* Buttons with an icon and a label (using [class@ButtonContent]); -* Menu buttons containing an arrow; -* [class@SplitButton]; -* Any other button with the [`.flat`](style-classes.html#flat) style class. - -The following buttons keep default appearance: - -* Text-only buttons; -* Buttons with other content; -* Buttons within widgets containing the - [`.linked`](style-classes.html#linked-controls) class; -* Buttons with the [`.suggested-action`](style-classes.html#suggested-action), - [`.destructive-action`](style-classes.html#destructive-action) or - [`.opaque`](style-classes.html#opaque) style classes. -* Buttons with the [`.raised`](style-classes.html#raised) style class. - -It's important to avoid ambiguous layouts, for example text-only buttons with -no icon, since such a button would be indistinguishable from the window title -without hovering it. - -In rare cases, the existing layout may need a redesign to work with the new -style. - -The same rules are also used for the [`.toolbar`](style-classes.html#toolbars) -style class now, instead of making every button appear flat. - -#### Adjusting Icon+Arrow Menu Buttons - -If you had menu buttons containing an icon and a dropdown arrow, switch to -[property@Gtk.MenuButton:icon-name] and set the -[property@Gtk.MenuButton:always-show-arrow] property to `TRUE`. - -#### Adjusting Text-only Buttons - -If you had text-only buttons, consider using [class@ButtonContent]. For example, -the following button: - -```xml - - _Open - True - -``` - -can be changed into: - -```xml - - - - document-open-symbolic - _Open - True - - - -``` - -One exception are the two primary buttons in a dialog, for example, "Cancel" and -"Open". Those buttons should retain their default appearance. - -#### Adjusting Split Buttons - -If you had split buttons implemented via a [class@Gtk.Box] with the -[`.linked`](style-classes.html#linked-controls) style class and two buttons -packed inside, use [class@SplitButton] as follows: - -```xml - - some_menu - view-list-symbolic - -``` - -#### Adjusting Linked Buttons - -For other linked together buttons, simply stop linking them. - -If multiple linked groups were used to separate different groups of actions, -insert extra spacing as follows: - -```xml - - - -``` - -#### Custom Adjustments - -The [`.flat`](style-classes.html#flat) and -[`.raised`](style-classes.html#raised) style classes can always be used to -override the default appearance. - -Important: the [property@Gtk.Button:has-frame] property will **not** be set to -`FALSE` when a button gets the flat appearance automatically. It also cannot be -set to `TRUE` to make a button raised, the style class should be used directly -instead. - -## Migrating From alpha 3 to alpha 4 - -### Adapt to [class@ActionRow] and [class@ExpanderRow] API Changes - -The `use-underline` property and its accessors have been removed. Use -[property@PreferencesRow:use-underline] and its accessors instead. - -The title and subtitle have markup enabled, make sure to escape it with -[func@GLib.markup_escape_text] if this is unwanted. - -### Adapt to [class@ExpanderRow] API Changes - -The `adw_expander_row_add()` function has been renamed to -[method@ExpanderRow.add_row]. - -### Adjusting Header Bar Icons - -If you're using the `object-select-symbolic` icon in a header bar button -(typically for selection mode), use `selection-mode-symbolic` instead. - -### Adapt to Stylesheet Changes - -### Stop Using the `.sidebar` Style Class - -The [`.sidebar`](style-classes.html#sidebar) style class is now deprecated, -although still works for compatibility reasons. The main use case - adjusting -the background color of [class@Gtk.ListBox] and [class@Gtk.ListView] - can now -be done with the [`.navigation-sidebar`](style-classes.html#sidebars) style -class on those widgets instead, along with adjusting the item selection style. -The border can be replicated by manually adding a [class@Gtk.Separator]. - -#### Adapt to the `popover.combo` Style Removal - -The `.combo` popover style class has been removed. Use -[`.menu`](style-classes.html#menu-popovers) instead. You may need to remove -manually added margins, padding or minimum height from the list items inside -while doing it. - -#### Adapt to List Style Changes - -For boxed lists we now have the -[`.boxed-list`](style-classes.html#boxed-lists-cards) style class that matches -the name of the design pattern. If you were using the -[`.content`](style-classes.html#content) style class, you should use -`.boxed-list` instead. - -The `.content` style class currently remains for compatibility purposes. - -Neither the `.content` style class nor the `.boxed-list` style class work -for [class@Gtk.ListView], as the widget cannot currently be used for the -boxed list pattern. - -## Migrating From alpha 4 to beta 1 - -#### Adapt to [class@SwipeTracker] API Changes - -The [signal@SwipeTracker::begin-swipe] signal is now emitted immediately before -the swipe starts, after the drag threshold has been reached, and it has lost its -`direction` parameter. The new [signal@SwipeTracker::prepare] signal behaves -exactly like `begin-swipe` did, and can be used instead of it. - -The type of the `duration` parameter in [signal@SwipeTracker::end-swipe] has -changed from `gint64` to `guint`. - -### Adapt to [class@TabView] API Changes - -The `HdyTabView:shortcut-widget` property has been removed with no replacement; -[class@TabView] automatically installs shortcuts with the -`GTK_SHORTCUT_SCOPE_MANAGED` scope, so they are automatically available -throughout the window without the need to set shortcut widget. - -If some of these shortcuts conflict with another widget, the latter has -priority, and it should work automatically if the widget correctly stops event -propagation. - -### Adapt to [class@Leaflet] API Changes - -The `can-swipe-back` and `can-swipe-forward` properties have been renamed to -[property@Leaflet:can-navigate-back] and -[property@Leaflet:can-navigate-forward], along with their accessors. The new -properties also handle keyboard and mouse shortcuts in addition to swipes. - -`AdwLeaflet` now uses spring animations instead of timed animations for child -transitions. As such, the `child-transition-duration` property has been replaced -with [property@Leaflet:child-transition-params], allowing to customize the -animation. Unlike the duration, spring parameters are also used for animation -triggered by swipe gestures. - -### Adapt to [class@Flap] API Changes - -`AdwFlap` now uses spring animations instead of timed animations for reveal -animations. As such, the `reveal-duration` property has been replaced with -[property@Flap:reveal-params], allowing to customize the animation. Unlike the -duration, spring parameters are also used for transitions triggered by swipe -gestures. - -### Adapt to [class@Carousel] API Changes - -`AdwCarousel` now uses spring animations instead of timed animations for -scrolling. As such, the `animation-duration` property has been replaced with -[property@Carousel:scroll-params], allowing to customize the animation. Unlike -the duration, spring parameters are also used for animation triggered by swipe -gestures. - -The `adw_carousel_scroll_to_full()` method has been removed. Instead, -[method@Carousel.scroll_to] has got an additional parameter `animate`. - -### Adapt to [class@PreferencesWindow] API Changes - -The `can-swipe-back` property have been renamed to -[property@PreferencesWindow:can-navigate-back], along with its accessors. The -new properties also handle keyboard and mouse shortcuts in addition to swipes. - -### Adapt to [class@ViewStack] API Changes - -[class@ViewStack] has stopped supporting transitions. As such, the -`interpolate-size` and `transition-running` properties have been removed with -no replacement. - -### Adapt to Miscellaneous Changes - -The `adw_ease_out_cubic()` function has been removed. Instead, -[func@Easing.ease] can be used with the `ADW_EASE_OUT_CUBIC` parameter. - -### Adapt to Stylesheet Changes - -### Adapt to the `button.outline` Style Removal - -The `.outline` style class has been removed with no replacement. The regular -button style should be used instead. - -### Adapt to the `content-view` Check Button Style Removal - -The selection mode [class@Gtk.CheckButton] style, used inside views with the -`.content-view` has been changed into a separate style class -[`.selection-mode`](style-classes.html#selection-mode-check-buttons) that can be -applied directly onto check buttons. diff --git a/doc/migrating-libhandy-1-4-to-libadwaita.md b/doc/migrating-libhandy-1-4-to-libadwaita.md index 9e491cdf32d3cba305973df8fb6b45f92f8fdbfa..eee2dc99ec1ec799623ae782e8cb1384b27dc19a 100644 --- a/doc/migrating-libhandy-1-4-to-libadwaita.md +++ b/doc/migrating-libhandy-1-4-to-libadwaita.md @@ -13,7 +13,7 @@ used together with the [GTK 3 to 4 migration guide](https://docs.gtk.org/gtk4/mi If you notice that some differences between Libhandy and Libadwaita are missing in this guide, [please report them](https://gitlab.gnome.org/GNOME/libadwaita/-/issues/new). -## Preparation in Libhandy 1.4 +# Preparation in Libhandy 1.4 The steps outlined in the following sections assume that your software is working with Libhandy 1.4, which is the latest stable release of Libhandy 1.x. @@ -21,7 +21,7 @@ It includes all the necessary APIs and tools to help you port your software to Libadwaita. If you are using an older version of Libhandy, you should first get your software to build and work with Libhandy 1.4. -### Do not Use Deprecated Symbols +## Do not Use Deprecated Symbols Over the years, a number of functions, and in some cases, entire widgets have been deprecated. These deprecations are clearly spelled out in the API @@ -29,19 +29,19 @@ reference, with hints about the recommended replacements. The API reference for Libhandy 1.4 also includes an [index](https://gnome.pages.gitlab.gnome.org/libhandy/doc/1-latest/deprecated-api-index.html) of all deprecated symbols. -### Subclassing +## Subclassing Following GTK4's emphasis on composition and delegation over subclassing, [class@Leaflet] and [class@HeaderBar] are no longer derivable. As a replacement, you can subclass `GtkBin` or [class@Gtk.Box] and include a leaflet or a header bar as a child widget. -### Stop Using `HdyKeypad` +## Stop Using `HdyKeypad` `HdyKeypad` has been removed from Libadwaita. Applications that had used it can copy it in tree instead. -### Stop Using Named WM Colors +## Stop Using Named WM Colors The following named colors have been removed from the stylesheet in Libadwaita: @@ -64,21 +64,21 @@ Libadwaita: Applications should not use them. -### Use `HdyFlap` Properties for Adding Children Instead of `gtk_container_add()` +## Use `HdyFlap` Properties for Adding Children Instead of `gtk_container_add()` `HdyFlap` provides the `content`, `flap` and `separator` properties that can be used for managing children instead of `GtkContainer` API. In Libadwaita [property@Flap:content], [property@Flap:flap] and [property@Flap:separator] are the only way to manage [class@Flap] children. -### Stop Using `HdyValueObject` with non-string values +## Stop Using `HdyValueObject` with non-string values `HdyValueObject` has been removed. While it's not practical to replace the cases where it's storing strings in GTK3, as the preferred replacement only exists in 4, it can also be used with any other [struct@GObject.Value]. That use has no replacement and you can instead create your own objects to store those values. -### Use `HdyStyleManager` Instead of [property@Gtk.Settings:gtk-application-prefer-dark-theme] +## Use `HdyStyleManager` Instead of [property@Gtk.Settings:gtk-application-prefer-dark-theme] If your application is setting [property@Gtk.Settings:gtk-application-prefer-dark-theme] to `TRUE` to request dark appearance, consider setting `HdyStyleManager:color-scheme` @@ -91,14 +91,14 @@ to `HDY_COLOR_SCHEME_PREFER_LIGHT` and support dark appearance. In libadwaita color schemes will be the only way to request dark appearance. -## Changes that Need to Be Done at the Time of the Switch +# Changes that Need to Be Done at the Time of the Switch This section outlines porting tasks that you need to tackle when you get to the point that you actually build your application against Libadwaita 1. Making it possible to prepare for these in GTK 3 would have been either impossible or impractical. -### Adapt to `GtkContainer` Removal +## Adapt to `GtkContainer` Removal Same as GTK itself, all widgets that have children have a new API to replace `gtk_container_add()` and `gtk_container_remove()`. @@ -126,15 +126,15 @@ Widget | `gtk_container_add()` replacement | `gtk_container_r Adding children in a UI file still works. -### Adapt to `HdySearchBar` Removal +## Adapt to `HdySearchBar` Removal `HdySearchBar` has been removed, use [class@Gtk.SearchBar] instead. -### Adapt to `HdyWindowHandle` Removal +## Adapt to `HdyWindowHandle` Removal `HdyWindowHandle` has been removed, use [class@Gtk.WindowHandle] instead. -### Adapt to [class@ActionRow] and [class@ExpanderRow] API Changes +## Adapt to [class@ActionRow] and [class@ExpanderRow] API Changes The `use-underline` property and its accessors have been removed. Use [property@PreferencesRow:use-underline] and its accessors instead. @@ -142,13 +142,13 @@ The `use-underline` property and its accessors have been removed. Use The title and subtitle have markup enabled, make sure to escape it with [func@GLib.markup_escape_text] if this is unwanted. -### Adapt to [class@Clamp] API Changes +## Adapt to [class@Clamp] API Changes `HdyClamp` previously had `.small`, `.medium` or `.large` style classes depending on the current size of its child. These style classes are now added to the child instead of the clamp itself. -### Adapt to [class@ComboRow] API Changes +## Adapt to [class@ComboRow] API Changes [class@ComboRow] API has been completely overhauled compared to `HdyComboRow` and closely mirrors [class@Gtk.DropDown]. Refer to [class@Gtk.DropDown]'s @@ -180,23 +180,23 @@ requiring an expression. The `HdyComboRow:selected-index` property has been renamed to [property@ComboRow:selected] and its type changed from `gint` to `guint`, matching [class@Gtk.DropDown]. -### Adapt to [class@PreferencesGroup] API Changes +## Adapt to [class@PreferencesGroup] API Changes `HdyPreferencesGroup:use-markup` has been removed, the labels always use markup now. -### Adapt to `HdyEnumValueObject` API Changes +## Adapt to `HdyEnumValueObject` API Changes `HdyEnumValueObject` has been renamed to [class@EnumListItem] and can no longer be manually created. It's only intended to be used with [class@EnumListModel]. -### Stop Using `HdyValueObject` +## Stop Using `HdyValueObject` `HdyValueObject` has been removed. The typical use for storing strings in combination with [class@Gio.ListStore] can be replaced by using [class@Gtk.StringList]. -### Adapt to [class@HeaderBar] API Changes +## Adapt to [class@HeaderBar] API Changes [class@HeaderBar] API mostly mirrors [class@Gtk.HeaderBar], refer to the [GTK 3 to 4 migration guide](https://docs.gtk.org/gtk4/migrating-3to4.html#adapt-to-gtkheaderbar-and-gtkactionbar-api-changes) @@ -210,7 +210,7 @@ layouts. The corresponding getter and the setter have been split as well. The [class@WindowTitle] widget may be useful for replacing the title and subtitle. -### Adapt to `HdyHeaderGroup` Removal +## Adapt to `HdyHeaderGroup` Removal `HdyHeaderGroup` has been removed. Its behavior can be replicated by changing the [property@HeaderBar:show-start-title-buttons] and @@ -245,12 +245,12 @@ for example binding them to the [property@Leaflet:folded] property as follows: ``` -### Adapt to `HdyDeck` Removal +## Adapt to `HdyDeck` Removal `HdyDeck` has been removed. Instead, an [class@Leaflet] can be used the same way by setting the [property@Leaflet:can-unfold] property to `FALSE`. -### Adapt to [class@Leaflet] and [class@Squeezer] API Changes +## Adapt to [class@Leaflet] and [class@Squeezer] API Changes The child properties of `HdyLeaflet` and `HdySqueezer` have been converted into page objects, similarly to [class@Gtk.Stack]. For example, @@ -279,7 +279,7 @@ with [property@Leaflet:child-transition-params], allowing to customize the animation. Unlike the duration, spring parameters are also used for animation triggered by swipe gestures. -### Adapt to [class@Flap] API Changes +## Adapt to [class@Flap] API Changes `AdwFlap` now uses spring animations instead of timed animations for reveal animations. As such, the `reveal-duration` property has been replaced with @@ -287,7 +287,7 @@ animations. As such, the `reveal-duration` property has been replaced with the duration, spring parameters are also used for transitions triggered by swipe gestures. -### Adapt to [class@Carousel] API changes +## Adapt to [class@Carousel] API changes `AdwCarousel` now uses spring animations instead of timed animations for scrolling. As such, the `animation-duration` property has been replaced with @@ -298,7 +298,7 @@ gestures. The `adw_carousel_scroll_to_full()` method has been removed. Instead, [method@Carousel.scroll_to] has got an additional parameter `animate`. -### Adapt to View Switcher API Changes +## Adapt to View Switcher API Changes [class@ViewSwitcher], [class@ViewSwitcherBar] and [class@ViewSwitcherTitle] now use [class@ViewStack] instead of [class@Gtk.Stack]. @@ -313,24 +313,24 @@ The `auto` view switcher policy has been removed. [class@ViewSwitcher] only has narrow and wide policies; if you had used the `auto` policy, use an [class@Squeezer] with two view switchers inside. -#### Adapt to [class@ViewSwitcher] API Changes +### Adapt to [class@ViewSwitcher] API Changes The `narrow-ellipsize` property has been removed. Narrow view switchers always ellipsize their labels, wide switchers never do. -#### Adapt to [class@ViewSwitcherBar] API Changes +### Adapt to [class@ViewSwitcherBar] API Changes The `policy` property has been removed. If you had used it, use a plain [class@ViewSwitcher] in a [class@Gtk.ActionBar] instead. -#### Adapt to [class@ViewSwitcherTitle] API Changes +### Adapt to [class@ViewSwitcherTitle] API Changes The `policy` property has been removed, the behavior is similar to the removed `auto` policy. If you had used `wide` or `narrow` policies, use an [class@Squeezer] with an [class@ViewSwitcher] and an [class@WindowTitle] inside, with the switcher having the desired policy. -### Adapt to [class@Avatar] API Changes +## Adapt to [class@Avatar] API Changes The `HdyAvatar:loadable-icon` property has been removed along with its getter and setter. It can be replaced by [property@Avatar:custom-image]. @@ -343,7 +343,7 @@ for that case. [method@Avatar.draw_to_texture] does not have the `size` parameter. Instead, it uses the avatar's current size, with no replacement. -### Adapt to [class@StyleManager] API Changes +## Adapt to [class@StyleManager] API Changes When used with the default style manager, `ADW_COLOR_SCHEME_DEFAULT` is now equivalent to `ADW_COLOR_SCHEME_PREFER_LIGHT` instead of @@ -351,7 +351,7 @@ equivalent to `ADW_COLOR_SCHEME_PREFER_LIGHT` instead of default. Make sure your application works with it, or otherwise set the `ADW_COLOR_SCHEME_FORCE_LIGHT` color scheme manually. -### Adapt to [class@SwipeTracker] API Changes +## Adapt to [class@SwipeTracker] API Changes The [signal@SwipeTracker::begin-swipe] signal is now emitted immediately before the swipe starts, after the drag threshold has been reached, and it has lost its @@ -361,7 +361,7 @@ exactly like `begin-swipe` did, and can be used instead of it. The type of the `duration` parameter in [signal@SwipeTracker::end-swipe] has changed from `gint64` to `guint`. -### Adapt to [class@TabView] API Changes +## Adapt to [class@TabView] API Changes The `HdyTabView:shortcut-widget` property has been removed with no replacement; [class@TabView] automatically installs shortcuts with the @@ -372,18 +372,18 @@ If some of these shortcuts conflict with another widget, the latter has priority, and it should work automatically if the widget correctly stops event propagation. -### Adapt to [class@PreferencesWindow] API Changes +## Adapt to [class@PreferencesWindow] API Changes The `can-swipe-back` property have been renamed to [property@PreferencesWindow:can-navigate-back], along with its accessors. The new properties also handle keyboard and mouse shortcuts in addition to swipes. -### Adapt to Miscellaneous Changes +## Adapt to Miscellaneous Changes The `hdy_ease_out_cubic()` function has been removed. Instead, [func@Easing.ease] can be used with the `ADW_EASE_OUT_CUBIC` parameter. -### Adapt to Stylesheet Changes +## Adapt to Stylesheet Changes If you were using [@theme_selected_bg_color](named-colors.html#compatibility-colors) @@ -392,7 +392,7 @@ as a text color, use make sure the text is readable. You can also use the [`.accent`](style-classes.html#colors) style class to apply the correct color. -### Stop Using the `.sidebar` Style Class +## Stop Using the `.sidebar` Style Class The [`.sidebar`](style-classes.html#sidebar) style class is now deprecated, although still works for compatibility reasons. The main use case - adjusting @@ -401,19 +401,19 @@ be done with the [`.navigation-sidebar`](style-classes.html#sidebars) style class on those widgets instead, along with adjusting the item selection style. The border can be replicated by manually adding a [class@Gtk.Separator]. -### Adapt to the `popover.combo` Style Removal +## Adapt to the `popover.combo` Style Removal The `.combo` popover style class has been removed. Use [`.menu`](style-classes.html#menu-popovers) instead. You may need to remove manually added margins, padding or minimum height from the list items inside while doing it. -### Adapt to the `button.list-button` Style Removal +## Adapt to the `button.list-button` Style Removal The `.list-button` style class has been removed with no replacement. The regular button style should be used instead. -### Adapt to the `content-view` Style Removal +## Adapt to the `content-view` Style Removal The `.content-view` style class has been removed. The selection mode [class@Gtk.CheckButton] style had inside content views has been split out into a @@ -422,7 +422,7 @@ separate style class applied directly onto check buttons instead of the view. The unique background color has no replacement and the default background should be used instead. -#### Adapt to Header Bar, Action Bar, Search Bar and Toolbar Style Changes +### Adapt to Header Bar, Action Bar, Search Bar and Toolbar Style Changes When possible, buttons in [class@Gtk.HeaderBar], [class@Gtk.ActionBar] and [class@Gtk.SearchBar] will use flat appearance by default. @@ -458,7 +458,7 @@ style. The same rules are also used for the [`.toolbar`](style-classes.html#toolbars) style class now, instead of making every button appear flat. -#### Adapt to List Style Changes +### Adapt to List Style Changes For boxed lists we now have the [`.boxed-list`](style-classes.html#boxed-lists-cards) style class that matches @@ -472,7 +472,7 @@ Neither the `.content` style class nor the `.boxed-list` style class work for [class@Gtk.ListView], as the widget cannot currently be used for the boxed list pattern. -#### Adjusting Icons +### Adjusting Icons If you're bundling icons from the icon library with your application, make sure to update them. Many icons have been redrawn to be larger to work better without @@ -481,13 +481,13 @@ button frames. If you're using the `object-select-symbolic` icon in a header bar button (typically for selection mode), use `selection-mode-symbolic` instead. -#### Adjusting Icon+Arrow Menu Buttons +### Adjusting Icon+Arrow Menu Buttons If you had menu buttons containing an icon and a dropdown arrow, switch to [property@Gtk.MenuButton:icon-name] and set the [property@Gtk.MenuButton:always-show-arrow] property to `TRUE`. -#### Adjusting Text-only Buttons +### Adjusting Text-only Buttons If you had text-only buttons, consider using [class@ButtonContent]. For example, the following button: @@ -516,7 +516,7 @@ can be changed into: One exception are the two primary buttons in a dialog, for example, "Cancel" and "Open". Those buttons should retain their default appearance. -#### Adjusting Split Buttons +### Adjusting Split Buttons If you had split buttons implemented via a [class@Gtk.Box] with the [`.linked`](style-classes.html#linked-controls) style class and two buttons @@ -529,7 +529,7 @@ packed inside, use [class@SplitButton] as follows: ``` -#### Adjusting Linked Buttons +### Adjusting Linked Buttons For other linked together buttons, simply stop linking them. @@ -544,7 +544,7 @@ insert extra spacing as follows: ``` -#### Custom Adjustments +### Custom Adjustments The [`.flat`](style-classes.html#flat) and [`.raised`](style-classes.html#raised) style classes can always be used to diff --git a/doc/named-colors.md b/doc/named-colors.md index 3cfd25cc418ab9baf03b0e2dcc48e5eb6be637ac..d1d91c2fd0b359b179e88d967a829bbf5ffbc90e 100644 --- a/doc/named-colors.md +++ b/doc/named-colors.md @@ -28,7 +28,7 @@ Slug: named-colors The Adwaita stylesheet provides a number of predefined colors that can be used from applications. -## UI Colors +# UI Colors These colors are used throughout the UI. They can differ between the light and dark styles. @@ -63,7 +63,7 @@ Applications can override any of these colors by re-declaring them, for example: @define-color accent_bg_color #e01b24; ``` -### Accent Colors +## Accent Colors The accent color is used across many different widgets, often to indicate that a widget is important, interactive, or currently active. Try to avoid using it on @@ -103,7 +103,7 @@ widgets such as [class@Gtk.Label]. -### Destructive Colors +## Destructive Colors The destructive color indicates a dangerous action, such as deleting a file. It's used by [class@Gtk.Button] with the @@ -140,7 +140,7 @@ It's used by [class@Gtk.Button] with the -### Success Colors +## Success Colors This color is used with the [`.success`](style-classes.html#colors) style class, or in a [class@Gtk.LevelBar] with the [const@Gtk.LEVEL_BAR_OFFSET_HIGH] offset. @@ -176,7 +176,7 @@ or in a [class@Gtk.LevelBar] with the [const@Gtk.LEVEL_BAR_OFFSET_HIGH] offset. -### Warning Colors +## Warning Colors This color is used with the [`.warning`](style-classes.html#colors) style class, or in a [class@Gtk.LevelBar] with the [const@Gtk.LEVEL_BAR_OFFSET_LOW] offset. @@ -212,7 +212,7 @@ or in a [class@Gtk.LevelBar] with the [const@Gtk.LEVEL_BAR_OFFSET_LOW] offset. -### Error Colors +## Error Colors This color is used with the [`.error`](style-classes.html#colors) style class. @@ -247,7 +247,7 @@ This color is used with the [`.error`](style-classes.html#colors) style class. -### Window Colors +## Window Colors These colors are used on [class@Gtk.Window], as well as with the [`.background`](style-classes.html#background) style class. @@ -276,7 +276,7 @@ These colors are used on [class@Gtk.Window], as well as with the -### View Colors +## View Colors These colors are used in a variety of widgets such as [class@Gtk.TextView], as well as with the [`.view`](style-classes.html#view) style class. @@ -305,7 +305,7 @@ well as with the [`.view`](style-classes.html#view) style class. -### Header Bar Colors +## Header Bar Colors These colors are used for header bars and similar widgets, generally attached to the top or bottom sides of a window. The full list of widgets using them: @@ -383,7 +383,7 @@ value matching your @headerbar_bg_color. border for header bars and similar widgets. This color should always be partially transparent black. -### Sidebar Colors +## Sidebar Colors These colors are used for sidebars, generally attached to the left or right sides of a window. They are used by [class@NavigationSplitView] and @@ -440,7 +440,7 @@ opacity tuned to be well visible on top of @sidebar_bg_color. Since: 1.4 -### Secondary Sidebar Colors +## Secondary Sidebar Colors These colors are used for middle panes in triple-pane layouts, created via nesting two split views within one another. @@ -502,7 +502,7 @@ the opacity tuned to be well visible on top of Since: 1.4 -### Card Colors +## Card Colors These colors are used for [cards and boxed lists](style-classes.html#boxed-lists-cards). @@ -543,7 +543,7 @@ boxed list rows and similar widgets. This color should always be partially transparent black, with the opacity tuned to be well visible on top of @card_bg_color. -### Thumbnail Colors +## Thumbnail Colors These colors are used for [class@TabOverview] thumbnails. @@ -573,7 +573,7 @@ These colors are used for [class@TabOverview] thumbnails. Since: 1.3 -### Dialog Colors +## Dialog Colors These colors are used for [class@MessageDialog]. @@ -603,7 +603,7 @@ These colors are used for [class@MessageDialog]. Since: 1.2 -### Popover Colors +## Popover Colors These colors are used for [class@Gtk.Popover]. @@ -645,7 +645,7 @@ always be partially transparent black, with the opacity tuned to be well visible on top of @popover_bg_color. This color is only available since 1.4. -### Miscellaneous Colors +## Miscellaneous Colors @@ -681,7 +681,7 @@ ensure that overlay scrollbars are visible regardless of the content color. It should always be the opposite of the scrollbar color - light with a dark scrollbar and dark with a light scrollbar. -## Helper Colors +# Helper Colors The following colors are derived from the current foreground color (`currentColor`) and change between regular and high contrast modes. They should @@ -691,7 +691,7 @@ Name | Regular | High contrast --------------------- | ---------------------------------- | --------------------------------- @borders | alpha(currentColor, 0.15) | alpha(currentColor, 0.5) -## Palette Colors +# Palette Colors The stylesheet provides the full [GNOME color palette](https://developer.gnome.org/hig/reference/palette.html) @@ -931,7 +931,7 @@ as the following set of named colors:
-## Compatibility Colors +# Compatibility Colors A number of colors has been available in Adwaita in GTK3. They are aliases of UI colors or otherwise derived from them: diff --git a/doc/style-classes.md b/doc/style-classes.md index dda5e42ac9d47a5e5c443d2229c2f4c42a3a2dbe..e22d05fda24431e57bb2684537d2d1fc82889741 100644 --- a/doc/style-classes.md +++ b/doc/style-classes.md @@ -6,12 +6,12 @@ Slug: style-classes The Adwaita stylesheet provides a number of style classes. They can be applied to widgets to change their appearance. -## Buttons +# Buttons The following style classes can be applied to [class@Gtk.Button] to change its appearance. -### Suggested Action +## Suggested Action @@ -26,7 +26,7 @@ It can be used in combination with [`.circular`](#circular) or [`.pill`](#pill). Can also be used with [class@Gtk.MenuButton] or [class@SplitButton]. -### Destructive Action +## Destructive Action @@ -41,7 +41,7 @@ It can be used in combination with [`.circular`](#circular) or [`.pill`](#pill). Can also be used with [class@Gtk.MenuButton] or [class@SplitButton]. -### Flat +## Flat @@ -60,7 +60,7 @@ Can also be used with [class@Gtk.MenuButton] or [class@SplitButton]. Can be set via [property@Gtk.Button:has-frame] and [property@Gtk.MenuButton:has-frame]. -### Raised +## Raised @@ -76,7 +76,7 @@ It can be used in combination with [`.circular`](#circular) or [`.pill`](#pill). Can also be used with [class@Gtk.MenuButton] or [class@SplitButton]. -### Opaque +## Opaque @@ -109,7 +109,7 @@ It can be used in combination with [`.circular`](#circular) or [`.pill`](#pill). Can also be used with [class@Gtk.MenuButton] or [class@SplitButton]. -### Circular +## Circular @@ -125,7 +125,7 @@ It can be used in combination with [`.suggested-action`](#suggested-action), Can also be used with [class@Gtk.MenuButton]. -### Pill +## Pill @@ -139,7 +139,7 @@ It can be used in combination with [`.suggested-action`](#suggested-action), [`.destructive-action`](#destructive-action), [`.flat`](#flat), [`.raised`](#raised), [`.opaque`](#opaque) or [`.osd`](#overlay-buttons). -## Linked Controls +# Linked Controls @@ -175,7 +175,7 @@ classes: If a linked box is contained within a [toolbar or a similar widget](#toolbars), buttons inside it won't get the flat appearance. -## Toolbars +# Toolbars @@ -226,7 +226,7 @@ Important: the [property@Gtk.Button:has-frame] property will **not** be set to set to `TRUE` to make a button raised, the style class should be used directly instead. -## Spacers +# Spacers @@ -237,7 +237,7 @@ The `.spacer` style class can be applied to a [class@Gtk.Separator] to make it appear invisible and act as whitespace. This can be useful with [toolbars and similar widgets](#toolbars) to separate groups of widgets from each other. -## Dim Labels +# Dim Labels @@ -250,7 +250,7 @@ transparent. The level of transparency differs between regular and high contrast styles. As such, it's highly recommended to be used instead of changing opacity manually. -## Typography Styles +# Typography Styles These style classes can be applied to any widgets, but are mostly used for [class@Gtk.Label] or other widgets that contain them. @@ -312,7 +312,7 @@ This style is useful in situations where multiple labels are vertically aligned, or when displaying time, an operation progress or another number that can quickly change. -## Colors +# Colors @@ -334,7 +334,7 @@ The `.error`, `.warning` and `.success` style classes can be applied to [class@Gtk.Entry]. In that case, they can be used to indicate input validation state. -## Boxed Lists & Cards +# Boxed Lists & Cards @@ -360,7 +360,7 @@ inside a boxed list. If the `.card` style class is applied to a [class@Gtk.Button], it will get these states automatically, without needing the `.activatable` class. -## Sidebars +# Sidebars @@ -372,11 +372,7 @@ or [class@Gtk.ListView] to make it look like a sidebar: it makes the items rounded and padded, makes selected items use a neutral color instead of accent, and removes the default list background. -When using it on a flap child in an [class@Flap], the lack of background can be -problematic. In that case, it can be used together with the -[`.background`](#background) style class. - -## App Icons +# App Icons @@ -390,7 +386,7 @@ with [class@Gtk.Image] or any other widget that contains an image. `.lowres-icon` should be used for 32×32 or smaller icons, and `.icon-dropshadow` should be used otherwise. -## Selection Mode Check Buttons +# Selection Mode Check Buttons @@ -401,7 +397,7 @@ The `.selection-mode` style class can be added to a [class@Gtk.CheckButton] to give it a larger and round appearance. These check buttons are intended to be used for selecting items from a list or a grid. -## OSD +# OSD @@ -416,7 +412,7 @@ makes its accent color white. However, it has different effects in a few specific cases. -### Overlay Buttons +## Overlay Buttons @@ -429,7 +425,7 @@ image viewer. They appear dark and slightly larger than regular buttons. It can be used in combination with [`.circular`](#circular) or [`.pill`](#pill). -### Floating Toolbars +## Floating Toolbars @@ -440,7 +436,7 @@ When used along with the [`.toolbar`](#toolbars) style class, `.osd` gives the box additional padding and round corners. This can be used to create floating toolbars, such as video player controls. -### Progress Bars +## Progress Bars @@ -453,7 +449,7 @@ and removes its visible trough. OSD progress bars are intended to be used as [class@Gtk.Overlay] children, attached to the top of the window. -## Background +# Background @@ -463,8 +459,7 @@ attached to the top of the window. The `.background` style class can be used with any widget to give it the default [window](named-colors.html#window-colors) background and foreground colors. -This can be useful when a widget needs an opaque background - for example, a -flap child inside an [class@Flap]. +This can be useful when a widget needs an opaque background. It's equivalent to using the following CSS: @@ -475,7 +470,7 @@ It's equivalent to using the following CSS: } ``` -## View +# View @@ -494,7 +489,7 @@ It's equivalent to using the following CSS: } ``` -## Frame +# Frame @@ -512,7 +507,7 @@ It's equivalent to using the following CSS: } ``` -## Flat Header Bar +# Flat Header Bar @@ -522,7 +517,7 @@ It's equivalent to using the following CSS: The `.flat` style class can be used with an [class@HeaderBar] or [class@Gtk.HeaderBar] to give it a flat appearance. -## Compact Status Page +# Compact Status Page @@ -532,7 +527,7 @@ The `.flat` style class can be used with an [class@HeaderBar] or The `.compact` style class can be used with a [class@StatusPage] to make it take less space. This is usually used with sidebars or popovers. -## Menu Popovers +# Menu Popovers @@ -543,7 +538,7 @@ The `.menu` style class can be used with a [class@Gtk.Popover] to give it a menu-like appearance if it has a [class@Gtk.ListBox] or a [class@Gtk.ListView] inside it. -## Development Window +# Development Window @@ -556,7 +551,7 @@ appearance. This style class is typically used to indicate unstable or nightly applications. -## Inline Tab Bars & Search Bars +# Inline Tab Bars & Search Bars @@ -573,7 +568,7 @@ By default [class@Gtk.SearchBar] and [class@TabBar] look like a part of an attached to one. With the `.inline` style class they have neutral backgrounds and can be used in different contexts instead. -## Undershoot Indicators +# Undershoot Indicators @@ -593,7 +588,7 @@ bars. Since: 1.4 -## Property Rows +# Property Rows diff --git a/doc/tools/data/adaptive-sidebar-narrow-1.ui b/doc/tools/data/adaptive-sidebar-narrow-1.ui new file mode 100644 index 0000000000000000000000000000000000000000..480167f34aee75f81e7064b997f66344457179d9 --- /dev/null +++ b/doc/tools/data/adaptive-sidebar-narrow-1.ui @@ -0,0 +1,84 @@ + + + + + + 360 + 200 + 360 + 500 + + + max-width: 400sp + True + none + + + + + + + Sidebar + sidebar + + + + + + + + never + + + browse + + + + Item 1 + 0 + + + + + Item 2 + 0 + + + + + Item 3 + 0 + + + + + + + + + + + + + Content + content + + + + + + + + Page 1 + + + + + + + + + + diff --git a/doc/tools/data/adaptive-sidebar-narrow-2.ui b/doc/tools/data/adaptive-sidebar-narrow-2.ui new file mode 100644 index 0000000000000000000000000000000000000000..dcd10163814148be9d313ce9fa30eac4b365efea --- /dev/null +++ b/doc/tools/data/adaptive-sidebar-narrow-2.ui @@ -0,0 +1,86 @@ + + + + + + 360 + 200 + 360 + 500 + + + max-width: 400sp + True + none + + + + + True + + + Sidebar + sidebar + + + + + + + + never + 250 + + + browse + + + + Item 1 + 0 + + + + + Item 2 + 0 + + + + + Item 3 + 0 + + + + + + + + + + + + + Content + content + + + + + + + + Page 1 + + + + + + + + + + diff --git a/doc/tools/data/adaptive-sidebar-wide.ui b/doc/tools/data/adaptive-sidebar-wide.ui new file mode 100644 index 0000000000000000000000000000000000000000..fc538bd4dc41c1fdcca0e96b85f8bc1670ba7a82 --- /dev/null +++ b/doc/tools/data/adaptive-sidebar-wide.ui @@ -0,0 +1,84 @@ + + + + + + 360 + 200 + 800 + 500 + + + max-width: 400sp + True + none + + + + + + + Sidebar + sidebar + + + + + + + + never + + + browse + + + + Item 1 + 0 + + + + + Item 2 + 0 + + + + + Item 3 + 0 + + + + + + + + + + + + + Content + content + + + + + + + + Page 1 + + + + + + + + + + diff --git a/doc/tools/data/adaptive-split-headers-narrow-1.ui b/doc/tools/data/adaptive-split-headers-narrow-1.ui deleted file mode 100644 index 04644ce032b2cd893d8c901e9a8ec303f658eaa3..0000000000000000000000000000000000000000 --- a/doc/tools/data/adaptive-split-headers-narrow-1.ui +++ /dev/null @@ -1,101 +0,0 @@ - - - - - - 360 - 500 - - - True - - - raised - - - - - - Sidebar - - - - - - - never - 250 - - - none - - - - Item 1 - 0 - - - - - Item 2 - 0 - - - - - Item 3 - 0 - - - - - - - - - - - False - - - - - - - - True - 360 - raised - - - - - - - go-previous-symbolic - - - - - Item 1 - - - - - - - Page 1 - - - - - - - - - - diff --git a/doc/tools/data/adaptive-split-headers-narrow-2.ui b/doc/tools/data/adaptive-split-headers-narrow-2.ui deleted file mode 100644 index adb8dd0249ec0488cce64bc2e1e4b4389d0c1ae3..0000000000000000000000000000000000000000 --- a/doc/tools/data/adaptive-split-headers-narrow-2.ui +++ /dev/null @@ -1,101 +0,0 @@ - - - - - - 360 - 500 - - - True - content - - - raised - - - - - - Sidebar - - - - - - - never - 250 - - - none - - - - Item 1 - 0 - - - - - Item 2 - 0 - - - - - Item 3 - 0 - - - - - - - - - - - False - - - - - - - - True - 360 - raised - - - - - - - go-previous-symbolic - - - - - Item 1 - - - - - - - Page 1 - - - - - - - - - diff --git a/doc/tools/data/adaptive-split-headers-wide.ui b/doc/tools/data/adaptive-split-headers-wide.ui deleted file mode 100644 index 7469367c1b724012c605f0ff2a6037f89b3c8a66..0000000000000000000000000000000000000000 --- a/doc/tools/data/adaptive-split-headers-wide.ui +++ /dev/null @@ -1,100 +0,0 @@ - - - - - - 800 - 500 - - - True - - - raised - - - - - - Sidebar - - - - - - - never - 250 - - - none - - - - Item 1 - 0 - - - - - Item 2 - 0 - - - - - Item 3 - 0 - - - - - - - - - - - False - - - - - - - - True - 360 - raised - - - - - - - go-previous-symbolic - - - - - Item 1 - - - - - - - Page 1 - - - - - - - - - diff --git a/doc/tools/data/adaptive-tabs-narrow-1.ui b/doc/tools/data/adaptive-tabs-narrow-1.ui new file mode 100644 index 0000000000000000000000000000000000000000..5e6163dbd23f5c3f7e428f12dd3ee227c9dfa6c2 --- /dev/null +++ b/doc/tools/data/adaptive-tabs-narrow-1.ui @@ -0,0 +1,92 @@ + + + + + + Tab View + 360 + 200 + 360 + 640 + + + max-width: 500px + True + False + False + + + + + view + True + + + raised + + + + + False + view + overview.open + + + + + tab-new-symbolic + + + + + + + view + + + + + + + Page 1 + + + + + + + + + + Page 2 + + + + + + + + + + Page 3 + + + + + + + + + + + + + + + diff --git a/doc/tools/data/adaptive-tabs-narrow-2.ui b/doc/tools/data/adaptive-tabs-narrow-2.ui new file mode 100644 index 0000000000000000000000000000000000000000..76ec579c61056b5e1569806b1386f753a85c77d6 --- /dev/null +++ b/doc/tools/data/adaptive-tabs-narrow-2.ui @@ -0,0 +1,93 @@ + + + + + + Tab View + 360 + 200 + 360 + 640 + + + max-width: 500px + True + False + False + + + + + view + True + True + + + raised + + + + + False + view + overview.open + + + + + tab-new-symbolic + + + + + + + view + + + + + + + Page 1 + + + + + + + + + + Page 2 + + + + + + + + + + Page 3 + + + + + + + + + + + + + + + diff --git a/doc/tools/data/adaptive-tabs-wide.ui b/doc/tools/data/adaptive-tabs-wide.ui new file mode 100644 index 0000000000000000000000000000000000000000..1d719098232b13f7a482f735c6e458ba748708fb --- /dev/null +++ b/doc/tools/data/adaptive-tabs-wide.ui @@ -0,0 +1,92 @@ + + + + + + Tab View + 360 + 200 + 800 + 300 + + + max-width: 500px + True + False + False + + + + + view + True + + + raised + + + + + False + view + overview.open + + + + + tab-new-symbolic + + + + + + + view + + + + + + + Page 1 + + + + + + + + + + Page 2 + + + + + + + + + + Page 3 + + + + + + + + + + + + + + + diff --git a/doc/tools/data/adaptive-triple-pane-medium.ui b/doc/tools/data/adaptive-triple-pane-medium.ui new file mode 100644 index 0000000000000000000000000000000000000000..2d2696568c61c8c763587e7c3ebc4be07a6d465e --- /dev/null +++ b/doc/tools/data/adaptive-triple-pane-medium.ui @@ -0,0 +1,103 @@ + + + + + + 360 + 200 + 600 + 300 + + + max-width: 860sp + True + 0.33 + + + + + max-width: 500sp + True + 0.33 + True + + + + + 470 + 780 + 0.47 + + + + + 260 + 0.38 + + + Sidebar + + + True + + + False + + + + + Sidebar + + + + + + + + + Middle Pane + + + True + + + False + + + + + Middle Pane + + + + + + + + + + + + + Content + + + True + + + False + + + + + Content + + + + + + + + + + diff --git a/doc/tools/data/adaptive-triple-pane-narrow-1.ui b/doc/tools/data/adaptive-triple-pane-narrow-1.ui new file mode 100644 index 0000000000000000000000000000000000000000..72d76b48b654acec6f4b3a282e4f8ba79afc39f0 --- /dev/null +++ b/doc/tools/data/adaptive-triple-pane-narrow-1.ui @@ -0,0 +1,103 @@ + + + + + + 360 + 200 + 360 + 300 + + + max-width: 860sp + True + 0.33 + + + + + max-width: 500sp + True + 0.33 + True + + + + + 470 + 780 + 0.47 + + + + + 260 + 0.38 + + + Sidebar + + + True + + + False + + + + + Sidebar + + + + + + + + + Middle Pane + + + True + + + False + + + + + Middle Pane + + + + + + + + + + + + + Content + + + True + + + False + + + + + Content + + + + + + + + + + diff --git a/doc/tools/data/adaptive-triple-pane-narrow-2.ui b/doc/tools/data/adaptive-triple-pane-narrow-2.ui new file mode 100644 index 0000000000000000000000000000000000000000..af8b5adf31d4259acc37fbd70c4a544afe2458e8 --- /dev/null +++ b/doc/tools/data/adaptive-triple-pane-narrow-2.ui @@ -0,0 +1,104 @@ + + + + + + 360 + 200 + 360 + 300 + + + max-width: 860sp + True + 0.33 + + + + + max-width: 500sp + True + 0.33 + True + + + + + 470 + 780 + 0.47 + + + + + 260 + 0.38 + True + + + Sidebar + + + True + + + False + + + + + Sidebar + + + + + + + + + Middle Pane + + + True + + + False + + + + + Middle Pane + + + + + + + + + + + + + Content + + + True + + + False + + + + + Content + + + + + + + + + + diff --git a/doc/tools/data/adaptive-triple-pane-narrow-3.ui b/doc/tools/data/adaptive-triple-pane-narrow-3.ui new file mode 100644 index 0000000000000000000000000000000000000000..04f2894e68edec3bdaeccb6191150ecdcf2e632f --- /dev/null +++ b/doc/tools/data/adaptive-triple-pane-narrow-3.ui @@ -0,0 +1,105 @@ + + + + + + 360 + 200 + 360 + 300 + + + max-width: 860sp + True + 0.33 + + + + + max-width: 500sp + True + 0.33 + True + + + + + 470 + 780 + 0.47 + True + + + + + 260 + 0.38 + True + + + Sidebar + + + True + + + False + + + + + Sidebar + + + + + + + + + Middle Pane + + + True + + + False + + + + + Middle Pane + + + + + + + + + + + + + Content + + + True + + + False + + + + + Content + + + + + + + + + + diff --git a/doc/tools/data/adaptive-triple-pane-wide.ui b/doc/tools/data/adaptive-triple-pane-wide.ui new file mode 100644 index 0000000000000000000000000000000000000000..4324339976e93bd4f2ec9f0faa6d1f44eb777ca6 --- /dev/null +++ b/doc/tools/data/adaptive-triple-pane-wide.ui @@ -0,0 +1,103 @@ + + + + + + 360 + 200 + 1200 + 300 + + + max-width: 860sp + True + 0.33 + + + + + max-width: 500sp + True + 0.33 + True + + + + + 470 + 780 + 0.47 + + + + + 260 + 0.38 + + + Sidebar + + + True + + + False + + + + + Sidebar + + + + + + + + + Middle Pane + + + True + + + False + + + + + Middle Pane + + + + + + + + + + + + + Content + + + True + + + False + + + + + Content + + + + + + + + + + diff --git a/doc/tools/data/adaptive-utility-pane-narrow.ui b/doc/tools/data/adaptive-utility-pane-narrow.ui index 62ebe991761a84a46dd4b3943301bcc4ac21c9dd..c7ed1d2b1517e3419fdcf8a538d54a0cf358c0e6 100644 --- a/doc/tools/data/adaptive-utility-pane-narrow.ui +++ b/doc/tools/data/adaptive-utility-pane-narrow.ui @@ -2,49 +2,48 @@ - + + 360 + 200 360 500 Utility Pane - - - - - sidebar-show-symbolic - True - - + + + max-width: 400sp + True - - - - - True - - - Utility Pane - True - 250 - + + + + raised + + + + + sidebar-show-symbolic + True + + - - - - + - - 360 - Main View - True - + + + True + + + Utility Pane + + + + + Main View + + diff --git a/doc/tools/data/adaptive-utility-pane-wide.ui b/doc/tools/data/adaptive-utility-pane-wide.ui index 170c2c5275c7f8b2986493e96cf4a2982e1b4f40..a655e242277929e722087794143d742bf25b2ceb 100644 --- a/doc/tools/data/adaptive-utility-pane-wide.ui +++ b/doc/tools/data/adaptive-utility-pane-wide.ui @@ -2,49 +2,48 @@ - + + 360 + 200 800 500 Utility Pane - - - - - sidebar-show-symbolic - True - - + + + max-width: 400sp + True - - - - - True - - - Utility Pane - True - 250 - + + + + raised + + + + + sidebar-show-symbolic + True + + - - - - + - - 360 - Main View - True - + + + True + + + Utility Pane + + + + + Main View + + diff --git a/doc/tools/data/adaptive-view-switcher-narrow.ui b/doc/tools/data/adaptive-view-switcher-narrow.ui index 770e650a610061503489f8c83610f0304a17faf7..9de6a05d639740cfcfcd90175fb211b3ce6b82ab 100644 --- a/doc/tools/data/adaptive-view-switcher-narrow.ui +++ b/doc/tools/data/adaptive-view-switcher-narrow.ui @@ -3,17 +3,26 @@ + 360 + 200 360 500 + View Switcher + + + max-width: 550sp + True + + + - - strict + - + stack - View Switcher + wide @@ -79,11 +88,8 @@ - + stack - - title - diff --git a/doc/tools/data/adaptive-view-switcher-wide.ui b/doc/tools/data/adaptive-view-switcher-wide.ui index 17c5c43d6f53842abf7755ec4f5eee89acbad8c1..0831fc742852dcf99ca59ef20fb30e5c61e4cc13 100644 --- a/doc/tools/data/adaptive-view-switcher-wide.ui +++ b/doc/tools/data/adaptive-view-switcher-wide.ui @@ -3,17 +3,26 @@ + 360 + 200 800 500 + View Switcher + + + max-width: 550sp + True + + + - - strict + - + stack - View Switcher + wide @@ -79,11 +88,8 @@ - + stack - - title - diff --git a/doc/tools/data/header-bar-split.ui b/doc/tools/data/header-bar-split.ui deleted file mode 100644 index 6ebbe8ad1c061d19e02651b93ce69f1b8b70128c..0000000000000000000000000000000000000000 --- a/doc/tools/data/header-bar-split.ui +++ /dev/null @@ -1,54 +0,0 @@ - - - - - - Window - 400 - 100 - Content - - - - - 150 - raised - - - - leaflet - - - - Sidebar - - - - - - - - - False - - - - - - - - True - raised - - - - leaflet - - - - - - - - - diff --git a/doc/tools/data/view-switcher.ui b/doc/tools/data/view-switcher.ui index b3428833398717354238050a184fd9dd474432c0..73c88bdb9ee84d5588028efe42691b38a177999c 100644 --- a/doc/tools/data/view-switcher.ui +++ b/doc/tools/data/view-switcher.ui @@ -2,14 +2,22 @@ - - False - - - vertical - + + 100 + + + + + + + stack + wide + + + + + - True Page 1 @@ -38,36 +46,7 @@ - - - - vertical - 6 - - - False - - - stack - wide - center - - - - - - - - stack - narrow - center - 9 - - - - + diff --git a/doc/tools/style-dark.css b/doc/tools/style-dark.css index c9dc04bf61ba17803bf12e467f78e4be1bb4cd3e..972735a30c7b3538dbe7d815972306b0eee7e4de 100644 --- a/doc/tools/style-dark.css +++ b/doc/tools/style-dark.css @@ -1,3 +1,4 @@ .overview-tab-page { - background: linear-gradient(to bottom right, @blue_5, @green_5 80%); + background: image(alpha(black, .25)), + linear-gradient(to bottom right, @blue_5, @green_5 80%); } diff --git a/doc/widget-gallery.md b/doc/widget-gallery.md index 560e92dfcdc3d1b950cbed2aa4e79112935d1be9..2f22ee3ad142cfedea3b57093024cc06b5ee3d3b 100644 --- a/doc/widget-gallery.md +++ b/doc/widget-gallery.md @@ -3,136 +3,136 @@ Slug: widget-gallery # Widget Gallery -## Display +# Display -### Status Page +## Status Page [ status-page ](class.StatusPage.html) -### Toast Overlay +## Toast Overlay [ toast-overlay ](class.ToastOverlay.html) -### Banner +## Banner [ banner ](class.Banner.html) -### Avatar +## Avatar [ avatar ](class.Avatar.html) -## Dialogs +# Dialogs -### Message Dialog +## Message Dialog [ message-dialog ](class.MessageDialog.html) -## Boxed Lists +# Boxed Lists -### Action Row +## Action Row [ action-row ](class.ActionRow.html) -### Switch Row +## Switch Row [ switch-row ](class.SwitchRow.html) -### Combo Row +## Combo Row [ combo-row ](class.ComboRow.html) -### Expander Row +## Expander Row [ expander-row ](class.ExpanderRow.html) -### Entry Row +## Entry Row [ entry-row ](class.EntryRow.html) -### Password Entry Row +## Password Entry Row [ password-entry-row ](class.PasswordEntryRow.html) -### Spin Row +## Spin Row [ switch-row ](class.SpinRow.html) -## Preferences +# Preferences -### Preferences Group +## Preferences Group [ preferences-group ](class.PreferencesGroup.html) -### Preferences Page +## Preferences Page [ preferences-page ](class.PreferencesPage.html) -### Preferences Window +## Preferences Window [ preferences-window ](class.PreferencesWindow.html) -## About Window +# About Window [ about-window ](class.AboutWindow.html) -## Navigation +# Navigation -### Navigation View +## Navigation View [ navigation-view ](class.NavigationView.html) -### Navigation Split View +## Navigation Split View [ @@ -143,7 +143,7 @@ Slug: widget-gallery navigation-split-view-collapsed ](class.NavigationSplitView.html) -### Overlay Split View +## Overlay Split View [ @@ -154,7 +154,7 @@ Slug: widget-gallery overlay-split-view-collapsed ](class.OverlaySplitView.html) -### Carousel +## Carousel [ @@ -171,19 +171,19 @@ Slug: widget-gallery carousel-indicator-lines ](class.CarouselIndicatorLines.html) -### View Switcher +## View Switcher [ - - view-switcher-title -](class.ViewSwitcherTitle.html) + + view-switcher +](class.ViewSwitcher.html) [ view-switcher-bar ](class.ViewSwitcherBar.html) -### Tabs +## Tabs [ @@ -200,16 +200,16 @@ Slug: widget-gallery tab-button ](class.TabButton.html) -## Adaptive Containers +# Helpers -### Breakpoint Bin +## Breakpoint Bin [ breakpoint-bin ](class.BreakpointBin.html) -### Clamp +## Clamp [ @@ -222,63 +222,28 @@ Slug: widget-gallery See also: [class@ClampLayout], [class@ClampScrollable] -### Leaflet - -[ - - leaflet-wide - - - - leaflet-narrow -](class.Leaflet.html) - -### Flap - -[ - - flap-wide - - - - flap-narrow -](class.Flap.html) - -### Squeezer - -[ - - squeezer-wide - - - - squeezer-narrow -](class.Squeezer.html) - -## Helpers - -### Toolbar View +## Toolbar View [ toolbar-view ](class.ToolbarView.html) -### Window Title +## Window Title [ window-title ](class.WindowTitle.html) -### Header Bar +## Header Bar [ header-bar ](class.HeaderBar.html) -### Window +## Window [ @@ -287,21 +252,21 @@ See also: [class@ClampLayout], [class@ClampScrollable] See also: [class@ApplicationWindow] -### Split Button +## Split Button [ split-button ](class.SplitButton.html) -### Button Content +## Button Content [ button-content ](class.ButtonContent.html) -### Bin +## Bin [ diff --git a/src/adw-header-bar.c b/src/adw-header-bar.c index 0f8a15e53fe26e4023e866390227fd1736f8fb15..15b5d01f538e6642eefed17bd0eaca17a22ffdf6 100644 --- a/src/adw-header-bar.c +++ b/src/adw-header-bar.c @@ -65,51 +65,14 @@ * ## Centering Policy * * [property@HeaderBar:centering-policy] allows to enforce strict centering of - * the title widget, this is useful for [class@ViewSwitcherTitle]. + * the title widget. This can be useful for entries inside [class@Clamp]. * * ## Title Buttons * + * Unlike `GtkHeaderBar`, `AdwHeaderBar` allows to toggle title button + * visibility for each side individually, using the * [property@HeaderBar:show-start-title-buttons] and - * [property@HeaderBar:show-end-title-buttons] allow to easily create split - * header bar layouts using [class@Leaflet], as follows: - * - * ```xml - * - * - * - * raised - * - * - * - * leaflet - * - * - * - * - * - * - * - * - * - * raised - * True - * - * - * - * leaflet - * - * - * - * - * - * - * - * ``` - * - * - * - * header-bar-split - * + * [property@HeaderBar:show-end-title-buttons] properties. * * ## CSS nodes * @@ -120,8 +83,10 @@ * ├── widget * │ ╰── box.start * │ ├── windowcontrols.start + * │ ├── [button.back] * │ ╰── [other children] - * ├── [Title Widget] + * ├── widget + * │ ╰── [Title Widget] * ╰── widget * ╰── box.end * ├── [other children] @@ -129,14 +94,17 @@ * ``` * * `AdwHeaderBar`'s CSS node is called `headerbar`. It contains a `windowhandle` - * subnode, which contains a `box` subnode, which contains two `widget` subnodes - * at the start and end of the header bar, each of which contains a `box` - * subnode with the `.start` and `.end` style classes respectively, as well as a - * center node that represents the title. + * subnode, which contains a `box` subnode, which contains three `widget` + * subnodes at the start, center and end of the header bar. The start and end + * subnotes contain a `box` subnode with the `.start` and `.end` style classes + * respectively, and the center node contains a node that represents the title. * * Each of the boxes contains a `windowcontrols` subnode, see * [class@Gtk.WindowControls] for details, as well as other children. * + * When [property@HeaderBar:show-back-button] is `TRUE`, the start box also + * contains a node with the name `button` and `.back` style class. + * * ## Accessibility * * `AdwHeaderBar` uses the `GTK_ACCESSIBLE_ROLE_GROUP` role. diff --git a/src/adw-navigation-split-view.c b/src/adw-navigation-split-view.c index 1bb475f47385664bf702106854673b337d94ef44..8f555f03b6941faa9ada6809fad53f585dd8c1ec 100644 --- a/src/adw-navigation-split-view.c +++ b/src/adw-navigation-split-view.c @@ -849,7 +849,7 @@ adw_navigation_split_view_add_child (GtkBuildable *buildable, else if (!g_strcmp0 (type, "sidebar")) adw_navigation_split_view_set_sidebar (ADW_NAVIGATION_SPLIT_VIEW (buildable), ADW_NAVIGATION_PAGE (child)); - else if (!type) + else if (!type && ADW_IS_NAVIGATION_PAGE (child)) adw_navigation_split_view_set_content (ADW_NAVIGATION_SPLIT_VIEW (buildable), ADW_NAVIGATION_PAGE (child)); else diff --git a/src/adw-preferences-window.c b/src/adw-preferences-window.c index 7614c12abb2cd7ed5dacda1c9940e10dc88d6bf9..8b8a3bfd468ac44e9d5cda531140d27860e21a3a 100644 --- a/src/adw-preferences-window.c +++ b/src/adw-preferences-window.c @@ -1079,7 +1079,9 @@ adw_preferences_window_close_subpage (AdwPreferencesWindow *self) * @self: a preferences window * @page: the subpage * - * TODO + * Pushes @page onto the subpage stack of @self. + * + * The page will be automatically removed when popped. * * Since: 1.4 */ @@ -1101,9 +1103,9 @@ adw_preferences_window_push_subpage (AdwPreferencesWindow *self, * adw_preferences_window_pop_subpage: * @self: a preferences window * - * TODO + * Pop the visible page from the subpage stack of @self. * - * Returns: TODO + * Returns: `TRUE` if a page has been popped * * Since: 1.4 */ diff --git a/src/adw-swipe-tracker.c b/src/adw-swipe-tracker.c index 39166580b47a63ba2008d9316ffc00a17c98c5e3..52915b8fe53089502f713bc6e836134c4e3976cc 100644 --- a/src/adw-swipe-tracker.c +++ b/src/adw-swipe-tracker.c @@ -35,7 +35,8 @@ /** * AdwSwipeTracker: * - * A swipe tracker used in [class@Carousel], [class@Flap] and [class@Leaflet]. + * A swipe tracker used in [class@Carousel], [class@NavigationView] and + * [class@OverlaySplitView]. * * The `AdwSwipeTracker` object can be used for implementing widgets with swipe * gestures. It supports touch-based swipes, pointer dragging, and touchpad @@ -1639,3 +1640,4 @@ adw_swipe_tracker_reset (AdwSwipeTracker *self) if (self->scroll_controller) gtk_event_controller_reset (self->scroll_controller); } + diff --git a/src/adw-view-switcher-bar.c b/src/adw-view-switcher-bar.c index b71de98317b8f629c60b5287da33d7b950d0ce34..3cc1b92e3ec6adfd93e11d1f1dffa2848cd2acdb 100644 --- a/src/adw-view-switcher-bar.c +++ b/src/adw-view-switcher-bar.c @@ -27,23 +27,29 @@ * on mobile phones. It can't be revealed if there are less than two pages. * * `AdwViewSwitcherBar` is intended to be used together with - * [class@ViewSwitcherTitle]. - * - * A common use case is to bind the [property@ViewSwitcherBar:reveal] property - * to [property@ViewSwitcherTitle:title-visible] to automatically reveal the - * view switcher bar when the title label is displayed in place of the view - * switcher, as follows: + * `AdwViewSwitcher` in a header bar, and a [class@Breakpoint] showing the view + * switcher bar on narrow sizes, while removing the view switcher from the + * header bar, as follows: * * ```xml * + * 360 + * 200 + * + * + * max-width: 550sp + * True + * + * + * * * * - * - * strict + * * - * + * * stack + * wide * * * @@ -52,11 +58,8 @@ * * * - * + * * stack - * - * title - * * * * @@ -64,6 +67,11 @@ * * ``` * + * It's recommended to set [property@ViewSwitcher:policy] to + * `ADW_VIEW_SWITCHER_POLICY_WIDE` in this case. + * + * You may have to adjust the breakpoint condition for your specific pages. + * * ## CSS nodes * * `AdwViewSwitcherBar` has a single CSS node with name` viewswitcherbar`. diff --git a/src/adw-view-switcher.c b/src/adw-view-switcher.c index 8878983ffeacbb6e8572c399fddd603336a17dce..e8058b2bd56689d07bb9fa0312d5e661de797c7b 100644 --- a/src/adw-view-switcher.c +++ b/src/adw-view-switcher.c @@ -32,8 +32,51 @@ * displayed side by side, or icon on top of the label. This can be controlled * via the [property@ViewSwitcher:policy] property. * - * Most applications should be using [class@ViewSwitcherBar] and - * [class@ViewSwitcherTitle]. + * `AdwViewSwitcher` is intended to be used in a header bar together with + * [class@ViewSwitcherBar] at the bottom of the window, and a [class@Breakpoint] + * showing the view switcher bar on narrow sizes, while removing the view + * switcher from the header bar, as follows: + * + * ```xml + * + * 360 + * 200 + * + * + * max-width: 550sp + * True + * + * + * + * + * + * + * + * + * + * stack + * wide + * + * + * + * + * + * + * + * + * + * stack + * + * + * + * + * + * ``` + * + * It's recommended to set [property@ViewSwitcher:policy] to + * `ADW_VIEW_SWITCHER_POLICY_WIDE` in this case. + * + * You may have to adjust the breakpoint condition for your specific pages. * * ## CSS nodes *