GI.Adw.Objects.NavigationView

A page-based navigation container.

<picture> <source srcset="navigation-view-dark.png" media="(prefers-color-scheme: dark)"> <img src="navigation-view.png" alt="navigation-view"> </picture>

AdwNavigationView presents one child at a time, similar to Stack.

AdwNavigationView can only contain [classnavigationPage] children.

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

AdwNavigationView allows to manage pages statically or dynamically.

Static pages can be added using the [methodnavigationView.add] method. The AdwNavigationView will keep a reference to these pages, but they aren't accessible to the user until [methodnavigationView.push] is called (except for the first page, which is pushed automatically). Use the [methodnavigationView.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 [methodnavigationView.push] method without calling [methodnavigationView.add] first.

Tags

Static pages, as well as any pages in the navigation stack, can be accessed by their [propertynavigationPage:tag]. For example, [methodnavigationView.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 AdwNavigationView, [classheaderBar] 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 [propertyheaderBar:show-back-button] to FALSE to disable this behavior in rare scenarios where it's unwanted.

AdwHeaderBar will also display the title of the AdwNavigationPage it's placed into, so most applications shouldn't need to customize it at all.

Shortcuts and Gestures

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

• <kbd>Escape</kbd> (unless [propertynavigationView:pop-on-escape] is set to FALSE)
• <kbd>Alt</kbd>+<kbd>←</kbd>
• 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 [propertynavigationView:animate-transitions] value.

Applications can also enable shortcuts for pushing another page onto the navigation stack via connecting to the signalnavigationView[getNextPage] signal, in that case the following shortcuts are supported:

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

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

propertynavigationPage:can-pop

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

Actions

AdwNavigationView 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 [methodnavigationView.push_by_tag].

• navigation.pop doesn't take any parameters and pops the current page from

the navigation stack, equivalent to calling [methodnavigationView.pop].

AdwNavigationView as GtkBuildable

AdwNavigationView allows to add pages as children, equivalent to using the [methodnavigationView.add] method.

Example of an AdwNavigationView UI definition:

xml code

<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>

<picture> <source srcset="navigation-view-example-dark.png" media="(prefers-color-scheme: dark)"> <img src="navigation-view-example.png" alt="navigation-view-example"> </picture>

CSS nodes

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

Accessibility

AdwNavigationView uses the GTK_ACCESSIBLE_ROLE_GROUP role.

Since: 1.4

Exported types

newtype NavigationView

Memory-managed wrapper type.

Constructors

NavigationView (ManagedPtr NavigationView)

Instances

Eq NavigationView

Defined in GI.Adw.Objects.NavigationView

Methods

(==) :: NavigationView -> NavigationView -> Bool

(/=) :: NavigationView -> NavigationView -> Bool

GObject NavigationView

Defined in GI.Adw.Objects.NavigationView

ManagedPtrNewtype NavigationView

Defined in GI.Adw.Objects.NavigationView

Methods

toManagedPtr :: NavigationView -> ManagedPtr NavigationView

TypedObject NavigationView

Defined in GI.Adw.Objects.NavigationView

Methods

glibType :: IO GType

HasParentTypes NavigationView

Defined in GI.Adw.Objects.NavigationView

IsGValue (Maybe NavigationView)

Convert NavigationView to and from GValue. See toGValue and fromGValue.

Defined in GI.Adw.Objects.NavigationView

Methods

gvalueGType_ :: IO GType

gvalueSet_ :: Ptr GValue -> Maybe NavigationView -> IO ()

gvalueGet_ :: Ptr GValue -> IO (Maybe NavigationView)

type ParentTypes NavigationView

Defined in GI.Adw.Objects.NavigationView

type ParentTypes NavigationView = '[Widget, Object, Swipeable, Accessible, Buildable, ConstraintTarget]

class (GObject o, IsDescendantOf NavigationView o) => IsNavigationView o

Type class for types which can be safely cast to NavigationView, for instance with toNavigationView.

Instances

(GObject o, IsDescendantOf NavigationView o) => IsNavigationView o

Defined in GI.Adw.Objects.NavigationView

toNavigationView :: (MonadIO m, IsNavigationView o) => o -> m NavigationView

Cast to NavigationView, for types for which this is known to be safe. For general casts, use castTo.

Methods

Click to display all available methods, including inherited ones

Methods

actionSetEnabled, activate, activateAction, activateDefault, add, addController, addCssClass, addMnemonicLabel, addTickCallback, allocate, announce, bindProperty, bindPropertyFull, childFocus, computeBounds, computeExpand, computePoint, computeTransform, contains, createPangoContext, createPangoLayout, disposeTemplate, dragCheckThreshold, errorBell, findPage, forceFloating, freezeNotify, getv, grabFocus, hasCssClass, hasDefault, hasFocus, hasVisibleFocus, hide, inDestruction, initTemplate, insertActionGroup, insertAfter, insertBefore, isAncestor, isDrawable, isFloating, isFocus, isSensitive, isVisible, keynavFailed, listMnemonicLabels, map, measure, mnemonicActivate, notify, notifyByPspec, observeChildren, observeControllers, pick, pop, popToPage, popToTag, push, pushByTag, queueAllocate, queueDraw, queueResize, realize, ref, refSink, remove, removeController, removeCssClass, removeMnemonicLabel, removeTickCallback, replace, replaceWithTags, resetProperty, resetRelation, resetState, runDispose, shouldLayout, show, sizeAllocate, snapshotChild, stealData, stealQdata, thawNotify, translateCoordinates, triggerTooltipQuery, unmap, unparent, unrealize, unref, unsetStateFlags, updateNextAccessibleSibling, updateProperty, updateRelation, updateState, watchClosure.

Getters

getAccessibleParent, getAccessibleRole, getAllocatedBaseline, getAllocatedHeight, getAllocatedWidth, getAllocation, getAncestor, getAnimateTransitions, getAtContext, getBaseline, getBounds, getBuildableId, getCanFocus, getCanTarget, getCancelProgress, getChildVisible, getClipboard, getColor, getCssClasses, getCssName, getCursor, getData, getDirection, getDisplay, getDistance, getFirstAccessibleChild, getFirstChild, getFocusChild, getFocusOnClick, getFocusable, getFontMap, getFontOptions, getFrameClock, getHalign, getHasTooltip, getHeight, getHexpand, getHexpandSet, getLastChild, getLayoutManager, getMapped, getMarginBottom, getMarginEnd, getMarginStart, getMarginTop, getName, getNative, getNavigationStack, getNextAccessibleSibling, getNextSibling, getOpacity, getOverflow, getPangoContext, getParent, getPlatformState, getPopOnEscape, getPreferredSize, getPrevSibling, getPreviousPage, getPrimaryClipboard, getProgress, getProperty, getQdata, getRealized, getReceivesDefault, getRequestMode, getRoot, getScaleFactor, getSensitive, getSettings, getSize, getSizeRequest, getSnapPoints, getStateFlags, getStyleContext, getSwipeArea, getTemplateChild, getTooltipMarkup, getTooltipText, getValign, getVexpand, getVexpandSet, getVisible, getVisiblePage, getWidth.

Setters

setAccessibleParent, setAnimateTransitions, setCanFocus, setCanTarget, setChildVisible, setCssClasses, setCursor, setCursorFromName, setData, setDataFull, setDirection, setFocusChild, setFocusOnClick, setFocusable, setFontMap, setFontOptions, setHalign, setHasTooltip, setHexpand, setHexpandSet, setLayoutManager, setMarginBottom, setMarginEnd, setMarginStart, setMarginTop, setName, setOpacity, setOverflow, setParent, setPopOnEscape, setProperty, setReceivesDefault, setSensitive, setSizeRequest, setStateFlags, setTooltipMarkup, setTooltipText, setValign, setVexpand, setVexpandSet, setVisible.

add

navigationViewAdd

Arguments

:: (HasCallStack, MonadIO m, IsNavigationView a, IsNavigationPage b)

=> a

self: a navigation view

-> b

page: the page to add

-> m ()

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 [methodnavigationView.remove].

Since: 1.4

findPage

navigationViewFindPage

Arguments

:: (HasCallStack, MonadIO m, IsNavigationView a)

=> a

self: a navigation view

-> Text

tag: a page tag

-> m (Maybe NavigationPage)

Returns: the page with the given tag

Finds a page in self by its tag.

See [propertynavigationPage:tag].

Since: 1.4

getAnimateTransitions

navigationViewGetAnimateTransitions

Arguments

:: (HasCallStack, MonadIO m, IsNavigationView a)

=> a

self: a navigation view

-> m Bool

Returns: whether to animate page transitions

Gets whether self animates page transitions.

Since: 1.4

getNavigationStack

navigationViewGetNavigationStack

Arguments

:: (HasCallStack, MonadIO m, IsNavigationView a)

=> a

self: a navigation view

-> m ListModel

Returns: a list model for the navigation stack

Returns a 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.

Since: 1.4

getPopOnEscape

navigationViewGetPopOnEscape

Arguments

:: (HasCallStack, MonadIO m, IsNavigationView a)

=> a

self: a navigation view

-> m Bool

Returns: whether to pop the current page

Gets whether pressing Escape pops the current page on self.

Since: 1.4

getPreviousPage

navigationViewGetPreviousPage

Arguments

:: (HasCallStack, MonadIO m, IsNavigationView a, IsNavigationPage b)

=> a

self: a navigation view

-> b

page: a page in self

-> m (Maybe NavigationPage)

Returns: the previous page

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.

Since: 1.4

getVisiblePage

navigationViewGetVisiblePage

Arguments

:: (HasCallStack, MonadIO m, IsNavigationView a)

=> a

self: a navigation view

-> m (Maybe NavigationPage)

Returns: the currently visible page

Gets the currently visible page in self.

Since: 1.4

new

navigationViewNew

Arguments

:: (HasCallStack, MonadIO m)

=> m NavigationView

Returns: the new created AdwNavigationView

Creates a new AdwNavigationView.

Since: 1.4

pop

navigationViewPop

Arguments

:: (HasCallStack, MonadIO m, IsNavigationView a)

=> a

self: a navigation view

-> m Bool

Returns: TRUE if a page has been popped

Pops the visible page from the navigation stack.

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

If [methodnavigationView.add] hasn't been called, the page is automatically removed.

signalnavigationView[popped] will be emitted for the current visible page.

See [methodnavigationView.pop_to_page] and [methodnavigationView.pop_to_tag].

Since: 1.4

popToPage

navigationViewPopToPage

Arguments

:: (HasCallStack, MonadIO m, IsNavigationView a, IsNavigationPage b)

=> a

self: a navigation view

-> b

page: the page to pop to

-> m Bool

Returns: TRUE if any pages have been popped

Pops pages from the navigation stack until page is visible.

page must be in the navigation stack.

If [methodnavigationView.add] hasn't been called for any of the popped pages, they are automatically removed.

signalnavigationView[popped] will be be emitted for each of the popped pages.

See [methodnavigationView.pop] and [methodnavigationView.pop_to_tag].

Since: 1.4

popToTag

navigationViewPopToTag

Arguments

:: (HasCallStack, MonadIO m, IsNavigationView a)

=> a

self: a navigation view

-> Text

tag: a page tag

-> m Bool

Returns: TRUE if any pages have been popped

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

The page must be in the navigation stack.

If [methodnavigationView.add] hasn't been called for any of the popped pages, they are automatically removed.

signalnavigationView[popped] will be emitted for each of the popped pages.

See [methodnavigationView.pop_to_page] and [propertynavigationPage:tag].

Since: 1.4

push

navigationViewPush

Arguments

:: (HasCallStack, MonadIO m, IsNavigationView a, IsNavigationPage b)

=> a

self: a navigation view

-> b

page: the page to push

-> m ()

Pushes page onto the navigation stack.

If [methodnavigationView.add] hasn't been called, the page is automatically removed once it's popped.

signalnavigationView[pushed] will be emitted for page.

See [methodnavigationView.push_by_tag].

Since: 1.4

pushByTag

navigationViewPushByTag

Arguments

:: (HasCallStack, MonadIO m, IsNavigationView a)

=> a

self: a navigation view

-> Text

tag: the page tag

-> m ()

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

If [methodnavigationView.add] hasn't been called, the page is automatically removed once it's popped.

signalnavigationView[pushed] will be emitted for the page.

See [methodnavigationView.push] and [propertynavigationPage:tag].

Since: 1.4

remove

navigationViewRemove

Arguments

:: (HasCallStack, MonadIO m, IsNavigationView a, IsNavigationPage b)

=> a

self: a navigation view

-> b

page: the page to remove

-> m ()

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 [methodnavigationView.add].

Since: 1.4

replace

navigationViewReplace

Arguments

:: (HasCallStack, MonadIO m, IsNavigationView a)

=> a

self: a navigation view

-> [NavigationPage]

pages: the new navigation stack

-> m ()

Replaces the current navigation stack with pages.

The last page becomes the visible page.

Replacing the navigation stack has no animation.

If [methodnavigationView.add] hasn't been called for any pages that are no longer in the navigation stack, they are automatically removed.

nPages 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 signalnavigationView[replaced] signal will be emitted.

See [methodnavigationView.replace_with_tags].

Since: 1.4

replaceWithTags

navigationViewReplaceWithTags

Arguments

:: (HasCallStack, MonadIO m, IsNavigationView a)

=> a

self: a navigation view

-> [Text]

tags: tags of the pages in the navigation stack

-> m ()

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 [methodnavigationView.add] hasn't been called for any pages that are no longer in the navigation stack, they are automatically removed.

nTags 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 signalnavigationView[replaced] signal will be emitted.

See [methodnavigationView.replace] and [propertynavigationPage:tag].

Since: 1.4

setAnimateTransitions

navigationViewSetAnimateTransitions

Arguments

:: (HasCallStack, MonadIO m, IsNavigationView a)

=> a

self: a navigation view

-> Bool

animateTransitions: whether to animate page transitions

-> m ()

Sets whether self should animate page transitions.

Gesture-based transitions are always animated.

Since: 1.4

setPopOnEscape

navigationViewSetPopOnEscape

Arguments

:: (HasCallStack, MonadIO m, IsNavigationView a)

=> a

self: a navigation view

-> Bool

popOnEscape: whether to pop the current page when pressing Escape

-> m ()

Sets whether pressing Escape pops the current page on self.

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

Since: 1.4

Properties

animateTransitions

Whether to animate page transitions.

Gesture-based transitions are always animated.

Since: 1.4

constructNavigationViewAnimateTransitions :: (IsNavigationView o, MonadIO m) => Bool -> m (GValueConstruct o)

Construct a GValueConstruct with valid value for the “animate-transitions” property. This is rarely needed directly, but it is used by new.

getNavigationViewAnimateTransitions :: (MonadIO m, IsNavigationView o) => o -> m Bool

Get the value of the “animate-transitions” property. When overloading is enabled, this is equivalent to

get navigationView #animateTransitions

setNavigationViewAnimateTransitions :: (MonadIO m, IsNavigationView o) => o -> Bool -> m ()

Set the value of the “animate-transitions” property. When overloading is enabled, this is equivalent to

set navigationView [ #animateTransitions := value ]

navigationStack

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.

Since: 1.4

getNavigationViewNavigationStack :: (MonadIO m, IsNavigationView o) => o -> m (Maybe ListModel)

Get the value of the “navigation-stack” property. When overloading is enabled, this is equivalent to

get navigationView #navigationStack

popOnEscape

Whether pressing Escape pops the current page.

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

Since: 1.4

constructNavigationViewPopOnEscape :: (IsNavigationView o, MonadIO m) => Bool -> m (GValueConstruct o)

Construct a GValueConstruct with valid value for the “pop-on-escape” property. This is rarely needed directly, but it is used by new.

getNavigationViewPopOnEscape :: (MonadIO m, IsNavigationView o) => o -> m Bool

Get the value of the “pop-on-escape” property. When overloading is enabled, this is equivalent to

get navigationView #popOnEscape

setNavigationViewPopOnEscape :: (MonadIO m, IsNavigationView o) => o -> Bool -> m ()

Set the value of the “pop-on-escape” property. When overloading is enabled, this is equivalent to

set navigationView [ #popOnEscape := value ]

visiblePage

The currently visible page.

Since: 1.4

getNavigationViewVisiblePage :: (MonadIO m, IsNavigationView o) => o -> m (Maybe NavigationPage)

Get the value of the “visible-page” property. When overloading is enabled, this is equivalent to

get navigationView #visiblePage

Signals

getNextPage

type NavigationViewGetNextPageCallback

Arguments

 = IO (Maybe NavigationPage)

Returns: the page to push

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 signalnavigationView[pushed] handler.

Since: 1.4

afterNavigationViewGetNextPage :: (IsNavigationView a, MonadIO m) => a -> ((?self :: a) => NavigationViewGetNextPageCallback) -> m SignalHandlerId

Connect a signal handler for the getNextPage signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after navigationView #getNextPage callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit ?self parameter. Note that this requires activating the ImplicitParams GHC extension.

onNavigationViewGetNextPage :: (IsNavigationView a, MonadIO m) => a -> ((?self :: a) => NavigationViewGetNextPageCallback) -> m SignalHandlerId

Connect a signal handler for the getNextPage signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on navigationView #getNextPage callback

popped

type NavigationViewPoppedCallback

Arguments

 = NavigationPage

page: the popped page

-> IO ()

Emitted after page has been popped from the navigation stack.

See [methodnavigationView.pop].

When using [methodnavigationView.pop_to_page] or [methodnavigationView.pop_to_tag], this signal is emitted for each of the popped pages.

Since: 1.4

afterNavigationViewPopped :: (IsNavigationView a, MonadIO m) => a -> ((?self :: a) => NavigationViewPoppedCallback) -> m SignalHandlerId

Connect a signal handler for the popped signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after navigationView #popped callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit ?self parameter. Note that this requires activating the ImplicitParams GHC extension.

onNavigationViewPopped :: (IsNavigationView a, MonadIO m) => a -> ((?self :: a) => NavigationViewPoppedCallback) -> m SignalHandlerId

Connect a signal handler for the popped signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on navigationView #popped callback

pushed

type NavigationViewPushedCallback = IO ()

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

See [methodnavigationView.push].

Since: 1.4

afterNavigationViewPushed :: (IsNavigationView a, MonadIO m) => a -> ((?self :: a) => NavigationViewPushedCallback) -> m SignalHandlerId

Connect a signal handler for the pushed signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after navigationView #pushed callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit ?self parameter. Note that this requires activating the ImplicitParams GHC extension.

onNavigationViewPushed :: (IsNavigationView a, MonadIO m) => a -> ((?self :: a) => NavigationViewPushedCallback) -> m SignalHandlerId

Connect a signal handler for the pushed signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on navigationView #pushed callback

replaced

type NavigationViewReplacedCallback = IO ()

Emitted after the navigation stack has been replaced.

See [methodnavigationView.replace].

Since: 1.4

afterNavigationViewReplaced :: (IsNavigationView a, MonadIO m) => a -> ((?self :: a) => NavigationViewReplacedCallback) -> m SignalHandlerId

Connect a signal handler for the replaced signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after navigationView #replaced callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit ?self parameter. Note that this requires activating the ImplicitParams GHC extension.

onNavigationViewReplaced :: (IsNavigationView a, MonadIO m) => a -> ((?self :: a) => NavigationViewReplacedCallback) -> m SignalHandlerId

Connect a signal handler for the replaced signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on navigationView #replaced callback