Struct NavigationView

pub struct NavigationView { /* private fields */ }

Available on crate feature v1_4 only.

A page-based navigation container.

NavigationView presents one child at a time, similar to gtk::Stack.

NavigationView can only contain NavigationPage children.

It maintains a navigation stack that can be controlled with push() and pop(). The whole navigation stack can also be replaced using replace().

NavigationView allows to manage pages statically or dynamically.

Static pages can be added using the add() method. The NavigationView will keep a reference to these pages, but they aren’t accessible to the user until push() is called (except for the first page, which is pushed automatically). Use the remove() method to remove them. This is useful for applications that have a small number of unique pages and just need navigation between them.

Dynamic pages are automatically destroyed once they are popped off the navigation stack. To add a page like this, push it using the push() method without calling add() first.

Tags

Static pages, as well as any pages in the navigation stack, can be accessed by their tag. For example, push_by_tag() can be used to push a static page that’s not in the navigation stack without having to keep a reference to it manually.

Header Bar Integration

When used inside NavigationView, HeaderBar will automatically display a back button that can be used to go back to the previous page when possible. The button also has a context menu, allowing to pop multiple pages at once, potentially across multiple navigation views.

Set show-back-button to FALSE to disable this behavior in rare scenarios where it’s unwanted.

HeaderBar will also display the title of the NavigationPage it’s placed into, so most applications shouldn’t need to customize it at all.

Shortcuts and Gestures

NavigationView supports the following shortcuts for going to the previous page:

• Escape (unless pop-on-escape is set to FALSE)
• Alt+←
• Back mouse button

Additionally, it supports interactive gestures:

• One-finger swipe towards the right on touchscreens
• Scrolling towards the right on touchpads (usually two-finger swipe)

These gestures have transitions enabled regardless of the animate-transitions value.

Applications can also enable shortcuts for pushing another page onto the navigation stack via connecting to the get-next-page signal, in that case the following shortcuts are supported:

• Alt+→
• Forward mouse button
• Swipe/scrolling towards the left

For right-to-left locales, the gestures and shortcuts are reversed.

can-pop can be used to disable them, along with the header bar back buttons.

Actions

NavigationView defines actions for controlling the navigation stack. actions for controlling the navigation stack:

• navigation.push takes a string parameter specifying the tag of the page to push, and is equivalent to calling push_by_tag().

• navigation.pop doesn’t take any parameters and pops the current page from the navigation stack, equivalent to calling pop().

NavigationView as gtk::Buildable

NavigationView allows to add pages as children, equivalent to using the add() method.

Example of an NavigationView UI definition:

<object class="AdwNavigationView">
  <child>
    <object class="AdwNavigationPage">
      <property name="title" translatable="yes">Page 1</property>
      <property name="child">
        <object class="AdwToolbarView">
          <child type="top">
            <object class="AdwHeaderBar"/>
          </child>
          <property name="content">
            <object class="GtkButton">
              <property name="label" translatable="yes">Open Page 2</property>
              <property name="halign">center</property>
              <property name="valign">center</property>
              <property name="action-name">navigation.push</property>
              <property name="action-target">'page-2'</property>
              <style>
                <class name="pill"/>
               </style>
            </object>
          </property>
        </object>
      </property>
    </object>
  </child>
  <child>
    <object class="AdwNavigationPage">
      <property name="title" translatable="yes">Page 2</property>
      <property name="tag">page-2</property>
      <property name="child">
        <object class="AdwToolbarView">
          <child type="top">
            <object class="AdwHeaderBar"/>
          </child>
          <property name="content">
            <!-- ... -->
          </property>
        </object>
      </property>
    </object>
  </child>
</object>

CSS nodes

NavigationView has a single CSS node with the name navigation-view.

Accessibility

NavigationView uses the GTK_ACCESSIBLE_ROLE_GROUP role.

Properties

animate-transitions

Whether to animate page transitions.

Gesture-based transitions are always animated.

Readable | Writeable

hhomogeneous

Whether the view is horizontally homogeneous.

If the view is horizontally homogeneous, it allocates the same width for all pages.

If it’s not, the page may change width when a different page becomes visible.

Readable | Writeable

navigation-stack

A list model that contains the pages in navigation stack.

The pages are sorted from root page to visible page.

This can be used to keep an up-to-date view.

Readable

pop-on-escape

Whether pressing Escape pops the current page.

Applications using NavigationView to implement a browser may want to disable it.

Readable | Writeable

vhomogeneous

Whether the view is vertically homogeneous.

If the view is vertically homogeneous, it allocates the same height for all pages.

If it’s not, the view may change height when a different page becomes visible.

Readable | Writeable

visible-page

The currently visible page.

Readable

Widget

can-focus

Whether the widget or any of its descendents can accept the input focus.

This property is meant to be set by widget implementations, typically in their instance init function.

Readable | Writeable

can-target

Whether the widget can receive pointer events.

Readable | Writeable

css-classes

A list of css classes applied to this widget.

Readable | Writeable

css-name

The name of this widget in the CSS tree.

This property is meant to be set by widget implementations, typically in their instance init function.

Readable | Writeable | Construct Only

cursor

The cursor used by @widget.

Readable | Writeable

focus-on-click

Whether the widget should grab focus when it is clicked with the mouse.

This property is only relevant for widgets that can take focus.

Readable | Writeable

focusable

Whether this widget itself will accept the input focus.

Readable | Writeable

halign

How to distribute horizontal space if widget gets extra space.

Readable | Writeable

has-default

Whether the widget is the default widget.

Readable

has-focus

Whether the widget has the input focus.

Readable

has-tooltip

Enables or disables the emission of the ::query-tooltip signal on @widget.

A value of true indicates that @widget can have a tooltip, in this case the widget will be queried using query-tooltip to determine whether it will provide a tooltip or not.

Readable | Writeable

height-request

Override for height request of the widget.

If this is -1, the natural request will be used.

Readable | Writeable

hexpand

Whether to expand horizontally.

Readable | Writeable

hexpand-set

Whether to use the hexpand property.

Readable | Writeable

layout-manager

The gtk::LayoutManager instance to use to compute the preferred size of the widget, and allocate its children.

This property is meant to be set by widget implementations, typically in their instance init function.

Readable | Writeable

margin-bottom

Margin on bottom side of widget.

This property adds margin outside of the widget’s normal size request, the margin will be added in addition to the size from [WidgetExtManual::set_size_request()][crate::gtk::prelude::WidgetExtManual::set_size_request()] for example.

Readable | Writeable

margin-end

Margin on end of widget, horizontally.

This property supports left-to-right and right-to-left text directions.

This property adds margin outside of the widget’s normal size request, the margin will be added in addition to the size from [WidgetExtManual::set_size_request()][crate::gtk::prelude::WidgetExtManual::set_size_request()] for example.

Readable | Writeable

margin-start

Margin on start of widget, horizontally.

This property supports left-to-right and right-to-left text directions.

This property adds margin outside of the widget’s normal size request, the margin will be added in addition to the size from [WidgetExtManual::set_size_request()][crate::gtk::prelude::WidgetExtManual::set_size_request()] for example.

Readable | Writeable

margin-top

Margin on top side of widget.

This property adds margin outside of the widget’s normal size request, the margin will be added in addition to the size from [WidgetExtManual::set_size_request()][crate::gtk::prelude::WidgetExtManual::set_size_request()] for example.

Readable | Writeable

name

The name of the widget.

Readable | Writeable

opacity

The requested opacity of the widget.

Readable | Writeable

overflow

How content outside the widget’s content area is treated.

This property is meant to be set by widget implementations, typically in their instance init function.

Readable | Writeable

parent

The parent widget of this widget.

Readable

receives-default

Whether the widget will receive the default action when it is focused.

Readable | Writeable

root

The gtk::Root widget of the widget tree containing this widget.

This will be None if the widget is not contained in a root widget.

Readable

scale-factor

The scale factor of the widget.

Readable

sensitive

Whether the widget responds to input.

Readable | Writeable

tooltip-markup

Sets the text of tooltip to be the given string, which is marked up with Pango markup.

Also see Gtk::Tooltip::set_markup().

This is a convenience property which will take care of getting the tooltip shown if the given string is not None: has-tooltip will automatically be set to true and there will be taken care of query-tooltip in the default signal handler.

Note that if both tooltip-text and tooltip-markup are set, the last one wins.

Readable | Writeable

tooltip-text

Sets the text of tooltip to be the given string.

Also see Gtk::Tooltip::set_text().

This is a convenience property which will take care of getting the tooltip shown if the given string is not None: has-tooltip will automatically be set to true and there will be taken care of query-tooltip in the default signal handler.

Note that if both tooltip-text and tooltip-markup are set, the last one wins.

Readable | Writeable

valign

How to distribute vertical space if widget gets extra space.

Readable | Writeable

vexpand

Whether to expand vertically.

Readable | Writeable

vexpand-set

Whether to use the vexpand property.

Readable | Writeable

visible

Whether the widget is visible.

Readable | Writeable

width-request

Override for width request of the widget.

If this is -1, the natural request will be used.

Readable | Writeable

Accessible

accessible-role

The accessible role of the given gtk::Accessible implementation.

The accessible role cannot be changed once set.

Readable | Writeable

Signals

get-next-page

Emitted when a push shortcut or a gesture is triggered.

To support the push shortcuts and gestures, the application is expected to return the page to push in the handler.

This signal can be emitted multiple times for the gestures, for example when the gesture is cancelled by the user. As such, the application must not make any irreversible changes in the handler, such as removing the page from a forward stack.

Instead, it should be done in the pushed handler.

popped

Emitted after @page has been popped from the navigation stack.

See NavigationView::pop().

When using NavigationView::pop_to_page() or NavigationView::pop_to_tag(), this signal is emitted for each of the popped pages.

pushed

Emitted after a page has been pushed to the navigation stack.

See NavigationView::push().

replaced

Emitted after the navigation stack has been replaced.

See NavigationView::replace().

Widget

destroy

Signals that all holders of a reference to the widget should release the reference that they hold.

May result in finalization of the widget if all references are released.

This signal is not suitable for saving widget state.

direction-changed

Emitted when the text direction of a widget changes.

hide

Emitted when @widget is hidden.

keynav-failed

Emitted if keyboard navigation fails.

See [WidgetExtManual::keynav_failed()][crate::gtk::prelude::WidgetExtManual::keynav_failed()] for details.

map

Emitted when @widget is going to be mapped.

A widget is mapped when the widget is visible (which is controlled with visible) and all its parents up to the toplevel widget are also visible.

The ::map signal can be used to determine whether a widget will be drawn, for instance it can resume an animation that was stopped during the emission of unmap.

mnemonic-activate

Emitted when a widget is activated via a mnemonic.

The default handler for this signal activates @widget if @group_cycling is false, or just makes @widget grab focus if @group_cycling is true.

move-focus

Emitted when the focus is moved.

The ::move-focus signal is a keybinding signal.

The default bindings for this signal are Tab to move forward, and Shift+Tab to move backward.

Action

query-tooltip

Emitted when the widget’s tooltip is about to be shown.

This happens when the has-tooltip property is true and the hover timeout has expired with the cursor hovering “above” @widget; or emitted when @widget got focus in keyboard mode.

Using the given coordinates, the signal handler should determine whether a tooltip should be shown for @widget. If this is the case true should be returned, false otherwise. Note that if @keyboard_mode is true, the values of @x and @y are undefined and should not be used.

The signal handler is free to manipulate @tooltip with the therefore destined function calls.

realize

Emitted when @widget is associated with a GdkSurface.

This means that [WidgetExtManual::realize()][crate::gtk::prelude::WidgetExtManual::realize()] has been called or the widget has been mapped (that is, it is going to be drawn).

show

Emitted when @widget is shown.

state-flags-changed

Emitted when the widget state changes.

See [WidgetExtManual::state_flags()][crate::gtk::prelude::WidgetExtManual::state_flags()].

unmap

Emitted when @widget is going to be unmapped.

A widget is unmapped when either it or any of its parents up to the toplevel widget have been set as hidden.

As ::unmap indicates that a widget will not be shown any longer, it can be used to, for example, stop an animation on the widget.

unrealize

Emitted when the GdkSurface associated with @widget is destroyed.

This means that [WidgetExtManual::unrealize()][crate::gtk::prelude::WidgetExtManual::unrealize()] has been called or the widget has been unmapped (that is, it is going to be hidden).

Implements

gtk::prelude::WidgetExt, [trait@glib::ObjectExt], gtk::prelude::AccessibleExt, gtk::prelude::BuildableExt, gtk::prelude::ConstraintTargetExt, SwipeableExt

GLib type: GObject with reference counted clone semantics.

Implementations

impl NavigationView

pub fn new() -> NavigationView

Creates a new NavigationView.

Returns

the new created NavigationView

pub fn builder() -> NavigationViewBuilder

Creates a new builder-pattern struct instance to construct NavigationView objects.

This method returns an instance of NavigationViewBuilder which can be used to create NavigationView objects.

pub fn add(&self, page: &impl IsA<NavigationPage>)

Permanently adds @page to @self.

Any page that has been added will stay in @self even after being popped from the navigation stack.

Adding a page while no page is visible will automatically push it to the navigation stack.

See remove().

page

the page to add

pub fn find_page(&self, tag: &str) -> Option<NavigationPage>

Finds a page in @self by its tag.

See tag.

tag

a page tag

Returns

the page with the given tag

pub fn is_animate_transitions(&self) -> bool

Gets whether @self animates page transitions.

Returns

whether to animate page transitions

pub fn is_hhomogeneous(&self) -> bool

Available on crate feature v1_7 only.

Gets whether @self is horizontally homogeneous.

Returns

whether @self is horizontally homogeneous

pub fn navigation_stack(&self) -> ListModel

Returns a gio::ListModel that contains the pages in navigation stack.

The pages are sorted from root page to visible page.

This can be used to keep an up-to-date view.

Returns

a list model for the navigation stack

pub fn is_pop_on_escape(&self) -> bool

Gets whether pressing Escape pops the current page on @self.

Returns

whether to pop the current page

pub fn previous_page( &self, page: &impl IsA<NavigationPage>, ) -> Option<NavigationPage>

Gets the previous page for @page.

If @page is in the navigation stack, returns the page popping @page will reveal.

If @page is the root page or is not in the navigation stack, returns NULL.

page

a page in @self

Returns

the previous page

pub fn is_vhomogeneous(&self) -> bool

Available on crate feature v1_7 only.

Gets whether @self is vertically homogeneous.

Returns

whether @self is vertically homogeneous

pub fn visible_page(&self) -> Option<NavigationPage>

Gets the currently visible page in @self.

Returns

the currently visible page

pub fn pop(&self) -> bool

Pops the visible page from the navigation stack.

Does nothing if the navigation stack contains less than two pages.

If add() hasn’t been called, the page is automatically removed.

popped will be emitted for the current visible page.

See pop_to_page() and pop_to_tag().

Returns

TRUE if a page has been popped

pub fn pop_to_page(&self, page: &impl IsA<NavigationPage>) -> bool

Pops pages from the navigation stack until @page is visible.

@page must be in the navigation stack.

If add() hasn’t been called for any of the popped pages, they are automatically removed.

popped will be be emitted for each of the popped pages.

See pop() and pop_to_tag().

page

the page to pop to

Returns

TRUE if any pages have been popped

pub fn pop_to_tag(&self, tag: &str) -> bool

Pops pages from the navigation stack until page with the tag @tag is visible.

The page must be in the navigation stack.

If add() hasn’t been called for any of the popped pages, they are automatically removed.

popped will be emitted for each of the popped pages.

See pop_to_page() and tag.

tag

a page tag

Returns

TRUE if any pages have been popped

pub fn push(&self, page: &impl IsA<NavigationPage>)

Pushes @page onto the navigation stack.

If add() hasn’t been called, the page is automatically removed once it’s popped.

pushed will be emitted for @page.

See push_by_tag().

page

the page to push

pub fn push_by_tag(&self, tag: &str)

Pushes the page with the tag @tag onto the navigation stack.

If add() hasn’t been called, the page is automatically removed once it’s popped.

pushed will be emitted for the page.

See push() and tag.

tag

the page tag

pub fn remove(&self, page: &impl IsA<NavigationPage>)

Removes @page from @self.

If @page is currently in the navigation stack, it will be removed once it’s popped. Otherwise, it’s removed immediately.

See add().

page

the page to remove

pub fn replace(&self, pages: &[NavigationPage])

Replaces the current navigation stack with @pages.

The last page becomes the visible page.

Replacing the navigation stack has no animation.

If add() hasn’t been called for any pages that are no longer in the navigation stack, they are automatically removed.

@n_pages can be 0, in that case no page will be visible after calling this method. This can be useful for removing all pages from @self.

The replaced signal will be emitted.

See replace_with_tags().

pages

the new navigation stack

pub fn replace_with_tags(&self, tags: &[&str])

Replaces the current navigation stack with pages with the tags @tags.

The last page becomes the visible page.

Replacing the navigation stack has no animation.

If add() hasn’t been called for any pages that are no longer in the navigation stack, they are automatically removed.

@n_tags can be 0, in that case no page will be visible after calling this method. This can be useful for removing all pages from @self.

The replaced signal will be emitted.

See replace() and tag.

tags

tags of the pages in the navigation stack

pub fn set_animate_transitions(&self, animate_transitions: bool)

Sets whether @self should animate page transitions.

Gesture-based transitions are always animated.

animate_transitions

whether to animate page transitions

pub fn set_hhomogeneous(&self, hhomogeneous: bool)

Available on crate feature v1_7 only.

Sets @self to be horizontally homogeneous or not.

If the view is horizontally homogeneous, it allocates the same width for all pages.

If it’s not, the view may change width when a different page becomes visible.

hhomogeneous

whether to make @self horizontally homogeneous

pub fn set_pop_on_escape(&self, pop_on_escape: bool)

Sets whether pressing Escape pops the current page on @self.

Applications using NavigationView to implement a browser may want to disable it.

pop_on_escape

whether to pop the current page when pressing Escape

pub fn set_vhomogeneous(&self, vhomogeneous: bool)

Available on crate feature v1_7 only.

Sets @self to be vertically homogeneous or not.

If the view is vertically homogeneous, it allocates the same height for all pages.

If it’s not, the view may change height when a different page becomes visible.

vhomogeneous

whether to make @self vertically homogeneous

pub fn connect_get_next_page<F: Fn(&Self) -> Option<NavigationPage> + 'static>( &self, f: F, ) -> SignalHandlerId

Emitted when a push shortcut or a gesture is triggered.

To support the push shortcuts and gestures, the application is expected to return the page to push in the handler.

This signal can be emitted multiple times for the gestures, for example when the gesture is cancelled by the user. As such, the application must not make any irreversible changes in the handler, such as removing the page from a forward stack.

Instead, it should be done in the pushed handler.

Returns

the page to push

pub fn connect_popped<F: Fn(&Self, &NavigationPage) + 'static>( &self, f: F, ) -> SignalHandlerId

Emitted after @page has been popped from the navigation stack.

See pop().

When using pop_to_page() or pop_to_tag(), this signal is emitted for each of the popped pages.

page

the popped page

pub fn connect_pushed<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId

Emitted after a page has been pushed to the navigation stack.

See push().

pub fn connect_replaced<F: Fn(&Self) + 'static>(&self, f: F) -> SignalHandlerId

Emitted after the navigation stack has been replaced.

See replace().

pub fn connect_animate_transitions_notify<F: Fn(&Self) + 'static>( &self, f: F, ) -> SignalHandlerId

pub fn connect_hhomogeneous_notify<F: Fn(&Self) + 'static>( &self, f: F, ) -> SignalHandlerId

Available on crate feature v1_7 only.

pub fn connect_navigation_stack_notify<F: Fn(&Self) + 'static>( &self, f: F, ) -> SignalHandlerId

pub fn connect_pop_on_escape_notify<F: Fn(&Self) + 'static>( &self, f: F, ) -> SignalHandlerId

pub fn connect_vhomogeneous_notify<F: Fn(&Self) + 'static>( &self, f: F, ) -> SignalHandlerId

Available on crate feature v1_7 only.

pub fn connect_visible_page_notify<F: Fn(&Self) + 'static>( &self, f: F, ) -> SignalHandlerId

Trait Implementations

impl Clone for NavigationView

fn clone(&self) -> Self

Makes a clone of this shared reference.

This increments the strong reference count of the object. Dropping the object will decrement it again.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for NavigationView

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for NavigationView

fn default() -> Self

Returns the “default value” for a type.

impl HasParamSpec for NavigationView

type ParamSpec = ParamSpecObject

type SetValue = NavigationView

Preferred value to be used as setter for the associated ParamSpec.

type BuilderFn = fn(_: &str) -> ParamSpecObjectBuilder<'_, NavigationView>

fn param_spec_builder() -> Self::BuilderFn

impl Hash for NavigationView

fn hash<H>(&self, state: &mut H)

where H: Hasher,

Hashes the memory address of this object.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for NavigationView

fn cmp(&self, other: &Self) -> Ordering

Comparison for two GObjects.

Compares the memory addresses of the provided objects.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl ParentClassIs for NavigationView

type Parent = Widget

impl<OT: ObjectType> PartialEq<OT> for NavigationView

fn eq(&self, other: &OT) -> bool

Equality for two GObjects.

Two GObjects are equal if their memory addresses are equal.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<OT: ObjectType> PartialOrd<OT> for NavigationView

fn partial_cmp(&self, other: &OT) -> Option<Ordering>

Partial comparison for two GObjects.

Compares the memory addresses of the provided objects.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl StaticType for NavigationView

fn static_type() -> Type

Returns the type identifier of Self.

impl Eq for NavigationView

impl IsA<Accessible> for NavigationView

impl IsA<Buildable> for NavigationView

impl IsA<ConstraintTarget> for NavigationView

impl IsA<Swipeable> for NavigationView

impl IsA<Widget> for NavigationView