Interface NavigationView

All Superinterfaces:
Activatable<NavigationView>, Component<NavigationView>, Enableable<NavigationView>, EventTarget<NavigationView>, Focusable<NavigationView>, HasContextMenu<NavigationView>, HasCursor<NavigationView>, HasTooltip<NavigationView>, Selection<NavigationItem, NavigationView>, SingleSelection<NavigationItem, NavigationView>, Titled<NavigationView>
public interface NavigationView extends Component<NavigationView>, Focusable<NavigationView>, HasCursor<NavigationView>, HasTooltip<NavigationView>, HasContextMenu<NavigationView>, Titled<NavigationView>, SingleSelection<NavigationItem, NavigationView>, Activatable<NavigationView>
A pane of navigation items at the side of a screen, with the content of the selected item beside it, for screens with several sections such as a settings screen or a market with Buy, Sell and History.

Display modes

The pane opened over the content is a popup laid out at the view's left edge, the pane's width wide and as tall as the view, through Overlays.popupIn(Component, Rect). A press outside it, Escape, and a pick close it, as does a change of the shown mode. While it is open the pane is in that popup, outside the view's tree, so control events of the pane header and footer reach only handlers on them until it closes.

The pane

From the top: the toggle, drawn as three lines, and the title, then the pane header, the items in a scrolling list, the footer items, and the pane footer. The toggle shows while the pane can be opened over the content, so not in EXPANDED. Headers are captions, hidden in the column of icons along with the pane header and footer, and separators are lines. An item with children shows an arrow at its right end; its children show below it, indented, while it is expanded. The selected item draws its selected background and an indicator 3.0f units wide down its left edge, and so does an item whose selected descendant is hidden. Disabled items draw in the disabled text and cannot be picked; their tooltips still show.

Picking

A click on an item asks Activatable.ACTIVATE, then, if the item is selectable and not selected, Selection.SELECT, and reports Selection.SELECTED and Activatable.ACTIVATED. Activation fires on every click, the selected item included, so an item that only acts, such as Sign out, is made not selectable and handled with ACTIVATED. An item with children that is not selectable expands or collapses instead of being selected. A click on an item's arrow asks EXPAND_ITEM and nothing else. In the column of icons, a click on an item with children opens its children in a menu beside it, made of menu items that mirror them; choosing one is a click on that child. With activate on click turned off, a single click selects or expands without activating, and a double click activates.

The indexes of SELECT, SELECTED, ACTIVATE and ACTIVATED count allItems(): every item depth first, the children of collapsed items included, then the footer items in the same way. Adding or removing items before the selected one changes its index, which reports SELECTED.

Keyboard

The view is one tab stop. While it has focus, a cursor marks one of the items the pane shows, starting on the selected item: Up and Down move it, skipping headers, separators, disabled items and items whose rows are hidden, without wrapping, and Home and End go to the first and last; held keys repeat. Enter, keypad Enter and Space pick its item as a click does, and always activate it (not repeated). Right expands a collapsed item with children, or opens its menu in the column of icons. Left collapses an expanded item or moves to its parent, and does nothing in the column of icons. With the pane hidden in MINIMAL, Enter and Space open it as the toggle does. These keys work with any modifiers held, and only while the view itself has focus. Tab moves on to the pane header, the pane footer and the content. The cursor's item draws "nav.focus" while the view has focus.

Pages and content

An item's page is built with the view's factory the first time the item is selected, and kept while the item stays in the view. Selecting another item takes the old page out of the tree, as a collapsed expander takes out its content, so a hidden page holds no focus and costs no layout, and coming back finds its text, scroll and selection as they were. Removing the item or setting its page again discards the kept page. While the selected item has no page, or nothing is selected, the view shows its content, so code that manages its own content sets it from a SELECTED handler. Pages, the content, the pane header and the pane footer are content, so their controls' events go on past the view.

The view stretches over its slot by default. Disabled, it closes the pane over the content and its menu, and it and everything in it take no focus or input.

Events

  • Selection.SELECT and Selection.SELECTED: asked when the user picks a selectable item that is not selected, and reported after every change, code included.
  • Activatable.ACTIVATE and Activatable.ACTIVATED: asked and reported for every pick of an enabled item.
  • EXPAND and EXPANDED: asked when the user opens or closes the pane with the toggle, and reported after every change, code, a press outside, Escape, a pick and a change of mode included.
  • EXPAND_ITEM and ITEM_EXPANDED: asked when the user expands or collapses an item, and reported after every change of an item in the view.

Theme keys

  • "nav.pane" (paint, optional): behind the pane beside the content and the bar of MINIMAL. Nothing is drawn if it is missing.
  • "nav.pane.overlay" (paint, optional): behind the pane opened over the content. Falls back to "nav.pane", and to the combo box's combobox.popup when that is missing too.
  • "nav.item.hovered" (paint, optional): behind the hovered item. Falls back to the list's list.row.hovered.
  • "nav.item.selected" (paint, required): behind the selected item.
  • "nav.indicator" (paint, optional): the strip down the selected item's left edge. Nothing is drawn if it is missing.
  • "nav.item.text" (text style, optional): an item's text, and the color of arrows and of the toggle's lines. Falls back to the default text style.
  • "nav.item.text.selected" (text style, optional): the selected item's text. Falls back to "nav.item.text".
  • "nav.item.text.disabled" (text style, optional): a disabled item's text. Falls back to the text box's textbox.text.disabled, then to "nav.item.text".
  • "nav.header.text" (text style, optional): a header. Falls back to "nav.item.text.disabled".
  • "nav.title.text" (text style, optional): the title. Falls back to the default text style.
  • "nav.separator" (paint, optional): a separator's line. Falls back to the separator control's separator.
  • "nav.toggle" and "nav.toggle.hovered" (paint, optional): behind the toggle, and behind it while the pointer is over it. Without the first nothing is drawn, and the second falls back to "nav.item.hovered". The three lines are drawn over them in the item text's color.
  • "nav.focus" (paint, optional): a one-unit ring around the keyboard cursor's item. Falls back to the button's button.focus.
  • "nav.item.padding" (insets, optional): around an item's icon and text. Defaults to 6 at the sides and 5 at the top and bottom, so an item is a line plus 10 tall.
  • "nav.pane.padding" (insets, optional): between the pane's edges and what it holds. Defaults to 2 on every side.

Badges use the shared badge.* keys of Avatar, and the scrolling list the scroll panel's keys.

NavigationView settings = factory.navigationView()
        .setTitle("Settings")
        .addItem("General", GeneralPage::new)
        .addItem("Sound", SoundPage::new)
        .addSeparator()
        .addFooterItem(factory.navigationItem("Sign out").setSelectable(false));
settings.onEvent(Activatable.ACTIVATED, event -> { ... });

Get one from ComponentFactory.navigationView(). Do not implement this interface.

  • Field Details

    • STYLE_PANE

      static final String STYLE_PANE
      Style key for behind the pane beside the content and the bar of MINIMAL (paint, optional).
      See Also:

    • STYLE_PANE_OVERLAY

      static final String STYLE_PANE_OVERLAY
      Style key for behind the pane opened over the content (paint, optional).
      See Also:

    • STYLE_ITEM_HOVERED

      static final String STYLE_ITEM_HOVERED
      Style key for behind the hovered item (paint, optional).
      See Also:

    • STYLE_ITEM_SELECTED

      static final String STYLE_ITEM_SELECTED
      Style key for behind the selected item (paint, required).
      See Also:

    • STYLE_INDICATOR

      static final String STYLE_INDICATOR
      Style key for the strip down the selected item's left edge (paint, optional).
      See Also:

    • STYLE_ITEM_TEXT

      static final String STYLE_ITEM_TEXT
      Style key for an item's text (text style, optional).
      See Also:

    • STYLE_ITEM_TEXT_SELECTED

      static final String STYLE_ITEM_TEXT_SELECTED
      Style key for the selected item's text (text style, optional).
      See Also:

    • STYLE_ITEM_TEXT_DISABLED

      static final String STYLE_ITEM_TEXT_DISABLED
      Style key for a disabled item's text (text style, optional).
      See Also:

    • STYLE_HEADER_TEXT

      static final String STYLE_HEADER_TEXT
      Style key for a header (text style, optional).
      See Also:

    • STYLE_TITLE_TEXT

      static final String STYLE_TITLE_TEXT
      Style key for the title (text style, optional).
      See Also:

    • STYLE_SEPARATOR

      static final String STYLE_SEPARATOR
      Style key for a separator's line (paint, optional).
      See Also:

    • STYLE_TOGGLE

      static final String STYLE_TOGGLE
      Style key for behind the toggle (paint, optional).
      See Also:

    • STYLE_TOGGLE_HOVERED

      static final String STYLE_TOGGLE_HOVERED
      Style key for behind the toggle while the pointer is over it (paint, optional).
      See Also:

    • STYLE_FOCUS

      static final String STYLE_FOCUS
      Style key for the ring around the keyboard cursor's item (paint, optional).
      See Also:

    • STYLE_ITEM_PADDING

      static final String STYLE_ITEM_PADDING
      Style key for the space around an item's icon and text (insets, optional). Defaults to 6 at the sides and 5 at the top and bottom.
      See Also:

    • STYLE_PANE_PADDING

      static final String STYLE_PANE_PADDING
      Style key for the space between the pane's edges and what it holds (insets, optional). Defaults to 2 on every side.
      See Also:

    • STYLE_ANIMATION

      static final String STYLE_ANIMATION
      Style key for how long the pane takes to slide in over the content from the view's left edge, in milliseconds (metric, optional). The pane is cut to its area while it slides and takes the pointer where it is drawn; it closes at once. Defaults to 0: the pane appears at once.
      See Also:

    • DEFAULT_PANE_WIDTH

      static final float DEFAULT_PANE_WIDTH
      The pane's width unless setPaneWidth(float) says otherwise, in UI units.
      See Also:

    • DEFAULT_COMPACT_BELOW

      static final float DEFAULT_COMPACT_BELOW
      The width below which NavigationView.DisplayMode.AUTO shows COMPACT unless setAutoWidths(float, float) says otherwise, in UI units.
      See Also:

    • DEFAULT_MINIMAL_BELOW

      static final float DEFAULT_MINIMAL_BELOW
      The width below which NavigationView.DisplayMode.AUTO shows MINIMAL unless setAutoWidths(float, float) says otherwise, in UI units.
      See Also:

    • INDICATOR_WIDTH

      static final float INDICATOR_WIDTH
      The width of the strip down the selected item's left edge, in UI units.
      See Also:

    • EXPAND

      static final EventType<ValueRequestEvent<NavigationView, Boolean>> EXPAND
      Asked before the user opens or closes the pane over the content with the toggle, with whether it would be open. Cancel it to leave the pane as it is. Fires only for the toggle, and for Enter or Space on a view with a hidden pane.

    • EXPANDED

      static final EventType<ValueEvent<NavigationView, Boolean>> EXPANDED
      Told after the pane over the content opened or closed, by the user, from code, or because a press outside, Escape, a pick or a change of the shown mode closed it.

    • EXPAND_ITEM

      static final EventType<ValueRequestEvent<NavigationView, NavigationView.Expansion>> EXPAND_ITEM
      Asked before the user expands or collapses an item's children, with the item and whether it would be expanded. A handler may rewrite it to another item of the view; the view ignores null and items it does not hold.

    • ITEM_EXPANDED

      static final EventType<ValueEvent<NavigationView, NavigationView.Expansion>> ITEM_EXPANDED
      Told after an item of the view was expanded or collapsed, by the user or with NavigationItem.setExpanded(boolean). The previous value names the same item with the other state.

    • IS_EXPANDED

      static final PropertyKey<NavigationView, Boolean> IS_EXPANDED
      Whether the pane is open over the content, as isExpanded() and setExpanded(boolean) say. Binds two ways through EXPANDED, so the pane closing on a press outside or a pick writes false. A true value does nothing where setExpanded cannot open the pane, and is not written back. It is named after the getter because the report has the property's name.

  • Method Details

    • items

      List<NavigationEntry> items()
      Returns the entries of the pane above the footer.
      Returns:
      a copy, in order

    • addItem

      NavigationView addItem(NavigationEntry entry)
      Adds an entry at the end of the pane, above the footer items.
      Parameters:
      entry - the entry
      Returns:
      this view
      Throws:
      IllegalArgumentException - if the entry belongs to a view or an item already, or was not made by Strata

    • addItem

      NavigationView addItem(int index, NavigationEntry entry)
      Adds an entry at a place among the entries above the footer.
      Parameters:
      index - where it goes: 0 for the first, the number of entries for the last
      entry - the entry
      Returns:
      this view
      Throws:
      IndexOutOfBoundsException - if the index is negative or greater than the number of entries
      IllegalArgumentException - if the entry belongs to a view or an item already, or was not made by Strata

    • removeItem

      NavigationView removeItem(NavigationEntry entry)
      Removes an entry from above the footer, and with it the pages kept for it and its children. Removing the selected item clears the selection. Does nothing if the view does not hold the entry there.
      Parameters:
      entry - the entry
      Returns:
      this view

    • clearItems

      NavigationView clearItems()
      Removes every entry above the footer, as removeItem(NavigationEntry) does. The footer items stay.
      Returns:
      this view

    • addItem

      NavigationView addItem(Text text, Function<ComponentFactory, ? extends Component<?>> page)
      Adds an item with a text and a page at the end of the pane.
      Parameters:
      text - the item's text
      page - builds the item's page; see NavigationItem.setPage(Function)
      Returns:
      this view

    • addItem

      default NavigationView addItem(String text, Function<ComponentFactory, ? extends Component<?>> page)
      Does the same as addItem(Text, Function) with literal text.
      Parameters:
      text - the item's text
      page - builds the item's page
      Returns:
      this view

    • addHeader

      NavigationView addHeader(Text text)
      Adds a header with a text at the end of the pane.
      Parameters:
      text - the header's text
      Returns:
      this view

    • addHeader

      default NavigationView addHeader(String text)
      Does the same as addHeader(Text) with literal text.
      Parameters:
      text - the header's text
      Returns:
      this view

    • addSeparator

      NavigationView addSeparator()
      Adds a separator at the end of the pane.
      Returns:
      this view

    • footerItems

      List<NavigationEntry> footerItems()
      Returns the entries at the foot of the pane, below the scrolling items and above the pane footer.
      Returns:
      a copy, in order

    • addFooterItem

      NavigationView addFooterItem(NavigationEntry entry)
      Adds an entry at the end of the footer, such as Settings or Sign out. Footer entries do not scroll.
      Parameters:
      entry - the entry
      Returns:
      this view
      Throws:
      IllegalArgumentException - if the entry belongs to a view or an item already, or was not made by Strata

    • addFooterItem

      NavigationView addFooterItem(int index, NavigationEntry entry)
      Adds an entry at a place in the footer.
      Parameters:
      index - where it goes: 0 for the first, the number of footer entries for the last
      entry - the entry
      Returns:
      this view
      Throws:
      IndexOutOfBoundsException - if the index is negative or greater than the number of footer entries
      IllegalArgumentException - if the entry belongs to a view or an item already, or was not made by Strata

    • removeFooterItem

      NavigationView removeFooterItem(NavigationEntry entry)
      Removes an entry from the footer, as removeItem(NavigationEntry) does. Does nothing if the footer does not hold it.
      Parameters:
      entry - the entry
      Returns:
      this view

    • clearFooterItems

      NavigationView clearFooterItems()
      Removes every entry from the footer, as removeFooterItem(NavigationEntry) does. The entries above the footer stay.
      Returns:
      this view

    • allItems

      List<NavigationItem> allItems()
      Returns every item of the view in the order selection indexes count them: the items above the footer depth first, the children of collapsed items included, then the footer items in the same way. Headers and separators are left out.
      Returns:
      a copy, in order

    • selected

      Optional<NavigationItem> selected()
      Returns the selected item.
      Specified by:
      selected in interface Selection<NavigationItem, NavigationView>
      Returns:
      the item at Selection.selectedIndex() in allItems(), or empty when none is selected

    • displayMode

      NavigationView.DisplayMode displayMode()
      Returns the display mode set.
      Returns:
      the mode; NavigationView.DisplayMode.AUTO by default

    • setDisplayMode

      NavigationView setDisplayMode(NavigationView.DisplayMode mode)
      Sets how the pane shows. A mode other than AUTO shows at once; AUTO is worked out at the next layout. A change of the shown mode closes the pane over the content and the menu of children.
      Parameters:
      mode - the mode
      Returns:
      this view

    • shownMode

      NavigationView.DisplayMode shownMode()
      Returns the mode the pane shows in: the display mode set, or what NavigationView.DisplayMode.AUTO chose from the view's width when the view was last arranged.
      Returns:
      EXPANDED, COMPACT or MINIMAL, never AUTO; EXPANDED for a view set to AUTO that was never arranged

    • compactBelow

      float compactBelow()
      Returns the width below which AUTO shows COMPACT.
      Returns:
      the width in UI units; DEFAULT_COMPACT_BELOW by default

    • minimalBelow

      float minimalBelow()
      Returns the width below which AUTO shows MINIMAL.
      Returns:
      the width in UI units; DEFAULT_MINIMAL_BELOW by default

    • setAutoWidths

      NavigationView setAutoWidths(float compactBelow, float minimalBelow)
      Sets the widths at which AUTO changes mode. The view lays out again.
      Parameters:
      compactBelow - the width below which the pane shows COMPACT
      minimalBelow - the width below which it shows MINIMAL
      Returns:
      this view
      Throws:
      IllegalArgumentException - if a width is negative or not finite, or minimalBelow is greater than compactBelow

    • isExpanded

      boolean isExpanded()
      Returns whether the pane is open over the content.
      Returns:
      true while it shows over the content in COMPACT or MINIMAL

    • setExpanded

      NavigationView setExpanded(boolean expanded)
      Opens or closes the pane over the content and reports EXPANDED if that changed. Never asks EXPAND. Opening does nothing in EXPANDED, or while the view is disabled, hidden or not shown on a screen.
      Parameters:
      expanded - true to open the pane over the content
      Returns:
      this view

    • paneWidth

      float paneWidth()
      Returns the width of the pane, beside the content in EXPANDED and over it in the other modes.
      Returns:
      the width in UI units; DEFAULT_PANE_WIDTH by default

    • setPaneWidth

      NavigationView setPaneWidth(float width)
      Sets the width of the pane. The view lays out again.
      Parameters:
      width - the width in UI units
      Returns:
      this view
      Throws:
      IllegalArgumentException - if the width is negative or not finite

    • isToggleShown

      boolean isToggleShown()
      Returns whether the toggle shows.
      Returns:
      true by default

    • setToggleShown

      NavigationView setToggleShown(boolean shown)
      Sets whether the toggle shows where the pane can be opened over the content. Without it, only code and, in MINIMAL, Enter and Space open the pane.
      Parameters:
      shown - false to leave the toggle out
      Returns:
      this view

    • paneHeader

      Optional<Component<?>> paneHeader()
      Returns the pane header.
      Returns:
      the component below the title, or empty when there is none

    • setPaneHeader

      NavigationView setPaneHeader(Component<?> header)
      Shows a component below the title, across the pane, such as a search box. It is content, so its control events go on past the view, and it is out of the tree while the pane shows as a column of icons.
      Parameters:
      header - the component, or null to remove it
      Returns:
      this view
      Throws:
      IllegalArgumentException - if the component is already in a tree or was made by another factory

    • paneFooter

      Optional<Component<?>> paneFooter()
      Returns the pane footer.
      Returns:
      the component at the foot of the pane, or empty when there is none

    • setPaneFooter

      NavigationView setPaneFooter(Component<?> footer)
      Shows a component at the foot of the pane, below the footer items, such as the user's Avatar. It is content, and it is out of the tree while the pane shows as a column of icons.
      Parameters:
      footer - the component, or null to remove it
      Returns:
      this view
      Throws:
      IllegalArgumentException - if the component is already in a tree or was made by another factory

    • content

      Optional<Component<?>> content()
      Returns the content shown while the selected item has no page.
      Returns:
      the content, or empty when there is none

    • setContent

      NavigationView setContent(Component<?> content)
      Sets what the view shows beside the pane while the selected item has no page or nothing is selected. It is content, so its control events go on past the view.
      Parameters:
      content - the component, or null for none
      Returns:
      this view
      Throws:
      IllegalArgumentException - if the component is already in a tree or was made by another factory

    • setActivateOnClick

      NavigationView setActivateOnClick(boolean onClick)
      Sets whether a single click activates an item. With it on, a click asks Activatable.ACTIVATE before it selects or expands; with it off, a single click selects or expands without activating, and a double click activates. Enter and Space always activate.
      Specified by:
      setActivateOnClick in interface Activatable<NavigationView>
      Parameters:
      onClick - false to activate on double clicks only; true by default
      Returns:
      this view