Class AppBar

  • All Implemented Interfaces:
    Styleable, EventTarget, Skinnable

    public class AppBar
    extends Control

    The AppBar is a special kind of toolbar that is used for branding, navigation, search, and actions. It is placed at the top of the view and is generally made up of:

    • Nav Icon - Left-most icon of the AppBar and is generally used for showing the NavigationDrawer or to move back in the view stack
    • Title - Label used to describe the current view
    • Action Icons - Icons with specific actions related to the current view
    • Menu Icon - Right-most icon of the AppBar and is used to show an overflow menu, which contains secondary actions and menu items

    A single instance of the AppBar is initialized by the application during its construction and therefore, need not be instantiated by the user. To change the elements of this control its instance can be fetched from MobileApplication.getInstance().getAppBar().

    The recommended node for Nav Icon and Action Icons is a button. Appropriate styling is automatically applied to buttons. To create a button without any text and only an Icon, use MaterialDesignIcon.button(). However, a user is not restricted to use buttons and can use any Node, with custom style(s). For developers, it is recommended to use the same color for all icons.

    If you wish to style the AppBar on a particular View, using CSS, just add a styleclass to the AppBar in the View.updateAppBar(AppBar) method or in a listener for View.showingProperty() and remove it in the View HIDDEN event, the following code illustrates this:
     
     public SomeView(String name) {
         ...
         setOnHidden(event -> {
              appBar.getStyleClass().remove("foo");
         });
     }
     
    @Override
     protected void updateAppBar(AppBar appBar) {
         appBar.getStyleClass().add("foo");
         ...
     }
    
     

    The following example fills the contents of an AppBar:

     AppBar appBar = MobileApplication.getInstance().getAppBar();
     appBar.setNavIcon(MaterialDesignIcon.MENU.button());
     appBar.setTitleText("The AppBar");
     appBar.getActionItems().addAll(MaterialDesignIcon.SEARCH.button(), MaterialDesignIcon.FAVORITE.button());
     appBar.getMenuItems().add(new MenuItem("Settings"));
     

    Screenshot of AppBar

    Every time a new View is loaded, the AppBar controls are removed, and its visibility is reset to true, so developers will need to provide at this point the new controls for the AppBar in this new View, either by overriding View.updateAppBar(com.gluonhq.charm.glisten.control.AppBar), by adding an event handler to the SHOWING event or by listening to View.showingProperty().

    The method clear() can be called to remove all the elements from AppBar and reset visibility of the control to true.

    Since:
    2.0.0
    See Also:
    AppManager, View
    • Constructor Detail

      • AppBar

        public AppBar()
        Creates a new instance of AppBar.
    • Method Detail

      • getTitle

        public final Node getTitle()
        Returns the title of the AppBar.
        Returns:
        The title Node.
        See Also:
        getTitleText()
      • titleProperty

        public final ObjectProperty<Node> titleProperty()
        The title in the app bar reflects the current page. It can be an app title or a page title. Setting this property to a value other than null will result in a node added right next to the navIcon in the AppBar.
        Returns:
        An ObjectProperty representing the AppBar title.
        See Also:
        titleTextProperty()
      • setTitle

        public final void setTitle​(Node title)
        Changes the title of the AppBar.
        Parameters:
        title - The new title Node.
        See Also:
        setTitleText(String)
      • titleTextProperty

        public final StringProperty titleTextProperty()
        The title in the app bar reflects the current page. It can be an app title or a page title. Setting this property to a value other than null will result in the titleProperty() being a Label with this property value as the text. This property might not reflect the actual title since this is not always synchronized with titleProperty().
        See Also:
        getTitleText(), setTitleText(String)
      • setTitleText

        public final void setTitleText​(String titleText)
        Sets the title of the AppBar.
        Parameters:
        titleText - The current title of AppBar.
        See Also:
        setTitle(Node)
      • getActionItems

        public final ObservableList<Node> getActionItems()
        Gets the action items. Typical use case for an AppBar suggest that the most common actionItems to place within it are Buttons with just a graphic, but you are not restricted to just these, and can insert any Node. The actionItems are placed between the title and the overflow menu, aligned right to left. The actionItems added must not be null.
        Returns:
        ObservableList of Node containing the action items.
      • getMenuItems

        public final ObservableList<MenuItem> getMenuItems()
        Gets the menu items listed in the overflow menu. The menu icon opens the overflow menu, which contains secondary actions and menu items like help, settings, and feedback. These menu items can be set in the menu by adding a MenuItem to the ObservableList returned by this method.
        Returns:
        ObservableList of MenuItem which is shown when an ActionEvent is triggered on the menu icon of the AppBar.
      • getNavIcon

        public final Node getNavIcon()
        Returns a node which is used as the nav icon.
        Returns:
        A Node containing the nav icon instance.
      • setNavIcon

        public final void setNavIcon​(Node navIcon)

        Sets a node as the nav icon. The nav icon is the left-most node of the app bar and can be:

        • A control to open a navigation drawer.
        • An up arrow for navigating upward through your application hierarchy.
        • Omitted entirely if no navigation is required from this screen.

        Normally, a user is advised to add a Button as the node. A Button will receive the appropriate styling automatically. Nevertheless, a user is not restricted to a Button and may add any node with custom style.

        Parameters:
        navIcon - The nav icon of the AppBar
      • getProgress

        public final double getProgress()
        Gets the value of the property progress.
        Property description:
        The progress of the ProgressBar attached to the AppBar. The ProgressBar can be either indeterminate or determinate depending on the value of this property. A negative value for progress indicates that the progress is indeterminate. A positive value between 0 and 1 indicates the percentage of progress where 0 is 0% and 1 is 100%. Any value greater than 1 is interpreted as 100%.
        Default value:
        ProgressIndicator.INDETERMINATE_PROGRESS
        Since:
        4.2.0
      • setProgress

        public final void setProgress​(double value)
        Sets the value of the property progress.
        Property description:
        The progress of the ProgressBar attached to the AppBar. The ProgressBar can be either indeterminate or determinate depending on the value of this property. A negative value for progress indicates that the progress is indeterminate. A positive value between 0 and 1 indicates the percentage of progress where 0 is 0% and 1 is 100%. Any value greater than 1 is interpreted as 100%.
        Default value:
        ProgressIndicator.INDETERMINATE_PROGRESS
        Since:
        4.2.0
      • isProgressBarVisible

        public final boolean isProgressBarVisible()
        Gets the value of the property progressBarVisible.
        Property description:
        The visible property of the ProgressBar shown on the AppBar.
        Default value:
        false
        Since:
        4.2.0
      • setProgressBarVisible

        public final void setProgressBarVisible​(boolean progressBarVisible)
        Sets the value of the property progressBarVisible.
        Property description:
        The visible property of the ProgressBar shown on the AppBar.
        Default value:
        false
        Since:
        4.2.0
      • isAutoHideProgressBar

        public final boolean isAutoHideProgressBar()
        Gets the value of the property autoHideProgressBar.
        Property description:
        Decides if a determinate ProgressBar should hide itself when the progressProperty() reaches the threshold value i.e. 1.0. If set as true and the progressProperty() is greater than equal to 1.0, the progressBarVisibleProperty() will be set to false.

        This property has no effect on an indeterminate ProgressBar.

        Default value:
        false
        Since:
        4.2.0
      • setAutoHideProgressBar

        public final void setAutoHideProgressBar​(boolean autoHideProgressBar)
        Sets the value of the property autoHideProgressBar.
        Property description:
        Decides if a determinate ProgressBar should hide itself when the progressProperty() reaches the threshold value i.e. 1.0. If set as true and the progressProperty() is greater than equal to 1.0, the progressBarVisibleProperty() will be set to false.

        This property has no effect on an indeterminate ProgressBar.

        Default value:
        false
        Since:
        4.2.0
      • setSpacing

        public final void setSpacing​(double value)
        Sets the value of the property spacing.
        Property description:
        The amount of horizontal space between each child in the AppBar. This horizontal space is also applied to the children of getActionItems().
      • getSpacing

        public final double getSpacing()
        Gets the value of the property spacing.
        Property description:
        The amount of horizontal space between each child in the AppBar. This horizontal space is also applied to the children of getActionItems().
      • clear

        public void clear()
        Clears the AppBar leaving it with no nav icon, title, action icons or menu items. The visibility of AppBar is also reset to true.
      • getClassCssMetaData

        public static List<CssMetaData<? extends Styleable,​?>> getClassCssMetaData()
        Returns:
        The CssMetaData associated with this class, which may include the CssMetaData of its super classes.
        Since:
        JavaFX 8.0