ToolbarView#

Added in version 1.4.

class ToolbarView(**properties: Any)#

Superclasses: Widget, InitiallyUnowned, Object

Implemented Interfaces: Accessible, Buildable, ConstraintTarget

A widget containing a page, as well as top and/or bottom bars.

https://gnome.pages.gitlab.gnome.org/libadwaita/doc/1-latest/toolbar-view.png

AdwToolbarView has a single content widget and one or multiple top and bottom bars, shown at the top and bottom sides respectively.

Example of an AdwToolbarView UI definition:

<object class="AdwToolbarView">
  <child type="top">
    <object class="AdwHeaderBar"/>
  </child>
  <property name="content">
    <object class="AdwPreferencesPage">
      <!-- ... -->
    </object>
  </property>
</object>

The following kinds of top and bottom bars are supported:

By default, top and bottom bars are flat and scrolling content has a subtle undershoot shadow, same as when using the `.undershoot-top <style-classes.html#undershoot-indicators>`__ and `.undershoot-bottom <style-classes.html#undershoot-indicators>`__ style classes. This works well in most cases, e.g. with StatusPage or PreferencesPage, where the background at the top and bottom parts of the page is uniform. Additionally, windows with sidebars should always use this style.

top_bar_style and bottom_bar_style properties can be used add an opaque background and a persistent shadow to top and bottom bars, this can be useful for content such as utility panes, where some elements are adjacent to the top/bottom bars, or TabView, where each page can have a different background.

<picture style=”min-width: 33%; display: inline-block;”>

<source srcset=”toolbar-view-flat-1-dark.png” media=”(prefers-color-scheme: dark)”> <img src=”toolbar-view-flat-1.png” alt=”toolbar-view-flat-1”>

</picture> <picture style=”min-width: 33%; display: inline-block;”>

<source srcset=”toolbar-view-flat-2-dark.png” media=”(prefers-color-scheme: dark)”> <img src=”toolbar-view-flat-2.png” alt=”toolbar-view-flat-2”>

</picture> <picture style=”min-width: 33%; display: inline-block;”>

<source srcset=”toolbar-view-raised-dark.png” media=”(prefers-color-scheme: dark)”> <img src=”toolbar-view-raised.png” alt=”toolbar-view-raised”>

</picture>

AdwToolbarView ensures the top and bottom bars have consistent backdrop styles and vertical spacing. For comparison:

<picture style=”min-width: 40%; display: inline-block;”>

<source srcset=”toolbar-view-spacing-dark.png” media=”(prefers-color-scheme: dark)”> <img src=”toolbar-view-spacing.png” alt=”toolbar-view-spacing”>

</picture> <picture style=”min-width: 40%; display: inline-block;”>

<source srcset=”toolbar-view-spacing-box-dark.png” media=”(prefers-color-scheme: dark)”> <img src=”toolbar-view-spacing-box.png” alt=”toolbar-view-spacing-box”>

</picture>

Any top and bottom bars can also be dragged to move the window, equivalent to putting them into a WindowHandle.

Content is typically place between top and bottom bars, but can also extend behind them. This is controlled with the extend_content_to_top_edge and extend_content_to_bottom_edge properties.

Top and bottom bars can be hidden and revealed with an animation using the reveal_top_bars and reveal_bottom_bars properties.

The AdwToolbarView implementation of the Buildable interface supports adding a top bar by specifying “top” as the “type” attribute of a <child> element, or adding a bottom bar by specifying “bottom”.

Accessibility#

AdwToolbarView uses the GTK_ACCESSIBLE_ROLE_GROUP role.

Constructors#

class ToolbarView
classmethod new() → Widget#

Creates a new AdwToolbarView.

Added in version 1.4.

Methods#

class ToolbarView
add_bottom_bar(widget: Widget) → None#

Adds a bottom bar to self.

Added in version 1.4.

Parameters:

widget – a widget

add_top_bar(widget: Widget) → None#

Adds a top bar to self.

Added in version 1.4.

Parameters:

widget – a widget

get_bottom_bar_height() → int#

Gets the current bottom bar height for self.

Bottom bar height does change depending on reveal_bottom_bars, including during the transition.

See get_top_bar_height.

Added in version 1.4.

get_bottom_bar_style() → ToolbarStyle#

Gets appearance of the bottom bars for self.

Added in version 1.4.

get_content() → Widget | None#

Gets the content widget for self.

Added in version 1.4.

get_extend_content_to_bottom_edge() → bool#

Gets whether the content widget can extend behind bottom bars.

Added in version 1.4.

get_extend_content_to_top_edge() → bool#

Gets whether the content widget can extend behind top bars.

Added in version 1.4.

get_reveal_bottom_bars() → bool#

Gets whether bottom bars are revealed for self.

Added in version 1.4.

get_reveal_top_bars() → bool#

Gets whether top bars are revealed for self.

Added in version 1.4.

get_top_bar_height() → int#

Gets the current top bar height for self.

Top bar height does change depending on reveal_top_bars, including during the transition.

See get_bottom_bar_height.

Added in version 1.4.

get_top_bar_style() → ToolbarStyle#

Gets appearance of the top bars for self.

Added in version 1.4.

remove(widget: Widget) → None#

Removes a child from self.

Added in version 1.4.

Parameters:

widget – the child to be removed

set_bottom_bar_style(style: ToolbarStyle) → None#

Sets appearance of the bottom bars for self.

If set to ADW_TOOLBAR_FLAT, bottom bars are flat and scrolling content has a subtle undershoot shadow when touching them, same as the `.undershoot-bottom <style-classes.html#undershoot-indicators>`__ style class. This works well for simple content, e.g. StatusPage or PreferencesPage, where the background at the bottom of the page is uniform. Additionally, windows with sidebars should always use this style.

Undershoot shadow is only present if a bottom bar is actually present and visible. It is also never present if extend_content_to_bottom_edge is set to TRUE.

If set to ADW_TOOLBAR_RAISED, bottom bars have an opaque background and a persistent shadow, this is suitable for content such as utility panes, where some elements are directly adjacent to the bottom bars, or TabView, where each page can have a different background.

ADW_TOOLBAR_RAISED_BORDER is similar to ADW_TOOLBAR_RAISED, but the shadow is replaced with a more subtle border. This can be useful for applications like image viewers.

See also set_top_bar_style.

Added in version 1.4.

Parameters:

style – bottom bar style

set_content(content: Widget | None = None) → None#

Sets the content widget for self.

Added in version 1.4.

Parameters:

content – the content widget

set_extend_content_to_bottom_edge(extend: bool) → None#

Sets whether the content widget can extend behind bottom bars.

This can be used in combination with reveal_bottom_bars to show and hide toolbars in fullscreen.

See set_extend_content_to_top_edge.

Added in version 1.4.

Parameters:

extend – whether content extends behind bottom bars

set_extend_content_to_top_edge(extend: bool) → None#

Sets whether the content widget can extend behind top bars.

This can be used in combination with reveal_top_bars to show and hide toolbars in fullscreen.

See set_extend_content_to_bottom_edge.

Added in version 1.4.

Parameters:

extend – whether content extends behind top bars

set_reveal_bottom_bars(reveal: bool) → None#

Sets whether bottom bars are revealed for self.

The transition will be animated.

This can be used in combination with extend_content_to_bottom_edge to show and hide toolbars in fullscreen.

See set_reveal_top_bars.

Added in version 1.4.

Parameters:

reveal – whether to reveal bottom bars

set_reveal_top_bars(reveal: bool) → None#

Sets whether top bars are revealed for self.

The transition will be animated.

This can be used in combination with extend_content_to_top_edge to show and hide toolbars in fullscreen.

See set_reveal_bottom_bars.

Added in version 1.4.

Parameters:

reveal – whether to reveal top bars

set_top_bar_style(style: ToolbarStyle) → None#

Sets appearance of the top bars for self.

If set to ADW_TOOLBAR_FLAT, top bars are flat and scrolling content has a subtle undershoot shadow when touching them, same as the `.undershoot-top <style-classes.html#undershoot-indicators>`__ style class. This works well for simple content, e.g. StatusPage or PreferencesPage, where the background at the top of the page is uniform. Additionally, windows with sidebars should always use this style.

Undershoot shadow is only present if a top bar is actually present and visible. It is also never present if extend_content_to_top_edge is set to TRUE.

If set to ADW_TOOLBAR_RAISED, top bars have an opaque background and a persistent shadow, this is suitable for content such as utility panes, where some elements are directly adjacent to the top bars, or TabView, where each page can have a different background.

ADW_TOOLBAR_RAISED_BORDER is similar to ADW_TOOLBAR_RAISED, but the shadow is replaced with a more subtle border. This can be useful for applications like image viewers.

See also set_bottom_bar_style.

Added in version 1.4.

Parameters:

style – top bar style

Properties#

class ToolbarView
props.bottom_bar_height: int#

The type of the None singleton.

Added in version 1.4.

props.bottom_bar_style: ToolbarStyle#

The type of the None singleton.

Added in version 1.4.

props.content: Widget#

The type of the None singleton.

Added in version 1.4.

props.extend_content_to_bottom_edge: bool#

The type of the None singleton.

Added in version 1.4.

props.extend_content_to_top_edge: bool#

The type of the None singleton.

Added in version 1.4.

props.reveal_bottom_bars: bool#

The type of the None singleton.

Added in version 1.4.

props.reveal_top_bars: bool#

The type of the None singleton.

Added in version 1.4.

props.top_bar_height: int#

The type of the None singleton.

Added in version 1.4.

props.top_bar_style: ToolbarStyle#

The type of the None singleton.

Added in version 1.4.