Package com.smartgwt.client.widgets.layout

Class NavigationBar

java.lang.Object
com.google.gwt.user.client.ui.UIObject
com.google.gwt.user.client.ui.Widget
com.smartgwt.client.widgets.BaseWidget
com.smartgwt.client.widgets.Canvas
com.smartgwt.client.widgets.layout.Layout
com.smartgwt.client.widgets.layout.HLayout
com.smartgwt.client.widgets.layout.NavigationBar
All Implemented Interfaces:
HasAttachHandlers, HasHandlers, EventListener, HasVisibility, IsWidget, LogicalStructure, HasClearHandlers, HasClickHandlers, HasDoubleClickHandlers, HasDragMoveHandlers, HasDragRepositionMoveHandlers, HasDragRepositionStartHandlers, HasDragRepositionStopHandlers, HasDragResizeMoveHandlers, HasDragResizeStartHandlers, HasDragResizeStopHandlers, HasDragStartHandlers, HasDragStopHandlers, HasDropHandlers, HasDropMoveHandlers, HasDropOutHandlers, HasDropOverHandlers, HasFocusChangedHandlers, HasHoverHandlers, HasHoverHiddenHandlers, HasKeyDownHandlers, HasKeyPressHandlers, HasMouseDownHandlers, HasMouseMoveHandlers, HasMouseOutHandlers, HasMouseOverHandlers, HasMouseStillDownHandlers, HasMouseUpHandlers, HasMouseWheelHandlers, HasMovedHandlers, HasParentMovedHandlers, HasResizedHandlers, HasRightMouseDownHandlers, HasRuleContextChangedHandlers, HasScrolledHandlers, HasShowContextMenuHandlers, HasVisibilityChangedHandlers, HasDownClickHandlers, HasMembersChangedHandlers, HasNavigationClickHandlers, HasUpClickHandlers
public class NavigationBar extends HLayout implements HasDownClickHandlers, HasNavigationClickHandlers, HasUpClickHandlers
Navigation control implemented as a horizontal layout showing back and forward controls and a title.

  • Constructor Details

    • NavigationBar

      public NavigationBar()

    • NavigationBar

      public NavigationBar(JavaScriptObject jsObj)

  • Method Details

    • getOrCreateRef

      public static NavigationBar getOrCreateRef(JavaScriptObject jsObj)

    • changeAutoChildDefaults

      public static void changeAutoChildDefaults(String autoChildName, Canvas defaults)
      Changes the defaults for Canvas AutoChildren named autoChildName.
      Parameters:
      autoChildName - name of an AutoChild to customize the defaults for.
      defaults - Canvas defaults to apply. These defaults override any existing properties without destroying or wiping out non-overridden properties. For usage tips on this param, see SGWTProperties.
      See Also:

    • changeAutoChildDefaults

      public static void changeAutoChildDefaults(String autoChildName, FormItem defaults)
      Changes the defaults for FormItem AutoChildren named autoChildName.
      Parameters:
      autoChildName - name of an AutoChild to customize the defaults for.
      defaults - FormItem defaults to apply. These defaults override any existing properties without destroying or wiping out non-overridden properties. For usage tips on this param, see SGWTProperties.
      See Also:

    • create

      protected JavaScriptObject create()
      Overrides:
      create in class HLayout

    • setAlwaysShowLeftButtonTitle

      public NavigationBar setAlwaysShowLeftButtonTitle(boolean alwaysShowLeftButtonTitle)
      If set, the left button title will never be omitted in an attempt to fit the full title. See the documentation of title for details.

      If this method is called after the component has been drawn/initialized: Setter for alwaysShowLeftButtonTitle.
      Parameters:
      alwaysShowLeftButtonTitle - new value for alwaysShowLeftButtonTitle. Default value is false
      Returns:
      NavigationBar instance, for chaining setter calls

    • getAlwaysShowLeftButtonTitle

      public boolean getAlwaysShowLeftButtonTitle()
      If set, the left button title will never be omitted in an attempt to fit the full title. See the documentation of title for details.
      Returns:
      Current alwaysShowLeftButtonTitle value. Default value is false

    • setAnimateStateChanges

      public NavigationBar setAnimateStateChanges(boolean animateStateChanges) throws IllegalStateException
      Whether to animate a change of the view state via setViewState().

      Enabling animation of state changes does have a performance impact because more components need to be created by the NavigationBar to implement the animated transitions. It is therefore recommended to leave animateStateChanges at its default value of false unless setViewState() might be called on this NavigationBar instance and animation is desired.

      Note also that when animation is enabled, certain AutoChild defaults and properties may be used to create other AutoChildren that are internal to the animation implementation. This generally does not cause an issue unless certain non-UI event handlers are added to the defaults and/or properties (e.g. Canvas.visibilityChanged(), Canvas.resized()). For those types of handlers, a check should be added to make sure that the handler is running for the expected component.

      Note : This is an advanced setting

      Parameters:
      animateStateChanges - New animateStateChanges value. Default value is false
      Returns:
      NavigationBar instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getAnimateStateChanges

      public boolean getAnimateStateChanges()
      Whether to animate a change of the view state via setViewState().

      Enabling animation of state changes does have a performance impact because more components need to be created by the NavigationBar to implement the animated transitions. It is therefore recommended to leave animateStateChanges at its default value of false unless setViewState() might be called on this NavigationBar instance and animation is desired.

      Note also that when animation is enabled, certain AutoChild defaults and properties may be used to create other AutoChildren that are internal to the animation implementation. This generally does not cause an issue unless certain non-UI event handlers are added to the defaults and/or properties (e.g. Canvas.visibilityChanged(), Canvas.resized()). For those types of handlers, a check should be added to make sure that the handler is running for the expected component.

      Returns:
      Current animateStateChanges value. Default value is false

    • setCustomNavControl

      public NavigationBar setCustomNavControl(Canvas customNavControl)
      An arbitrary component that will be placed where the miniNavControl AutoChild would normally be placed (see miniNavAlign).

      If this method is called after the component has been drawn/initialized: Setter to update the customNavControl at runtime.
      Parameters:
      customNavControl - New customNavControl value. Default value is null
      Returns:
      NavigationBar instance, for chaining setter calls

    • getCustomNavControl

      public Canvas getCustomNavControl()
      An arbitrary component that will be placed where the miniNavControl AutoChild would normally be placed (see miniNavAlign).
      Returns:
      Current customNavControl value. Default value is null

    • setIconBaseStyle

      public NavigationBar setIconBaseStyle(String iconBaseStyle) throws IllegalStateException
      A CSS style to apply to images in the left and right buttons. This is a base style supporting suffixes for states, specifically "Over", "Down" and "Disabled", which are applied when ImgButton settings like ImgButton.showRollOverIcon are applied to the icons.
      Parameters:
      iconBaseStyle - New iconBaseStyle value. Default value is "icon"
      Returns:
      NavigationBar instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
      See Also:

    • getIconBaseStyle

      public String getIconBaseStyle()
      A CSS style to apply to images in the left and right buttons. This is a base style supporting suffixes for states, specifically "Over", "Down" and "Disabled", which are applied when ImgButton settings like ImgButton.showRollOverIcon are applied to the icons.
      Returns:
      Current iconBaseStyle value. Default value is "icon"
      See Also:

    • setIconSize

      public NavigationBar setIconSize(Integer iconSize)
      Default size for icons in the left and right buttons in this NavigationBar.
      Parameters:
      iconSize - New iconSize value. Default value is null
      Returns:
      NavigationBar instance, for chaining setter calls

    • getIconSize

      public Integer getIconSize()
      Default size for icons in the left and right buttons in this NavigationBar.
      Returns:
      Current iconSize value. Default value is null

    • getLeftButton

      public NavigationButton getLeftButton() throws IllegalStateException
      The button displayed to the left of the title in this NavigationBar. By default this will be a NavigationButton with direction set to NavigationDirection.BACK.

      The following passthroughs apply:

      This component is an AutoChild named "leftButton". For an overview of how to use and configure AutoChildren, see Using AutoChildren.

      Returns:
      Current leftButton value. Default value is null
      Throws:
      IllegalStateException - if this widget has not yet been rendered.
      See Also:

    • setLeftButtonIcon

      public NavigationBar setLeftButtonIcon(String leftButtonIcon)
      Icon for the leftButton.

      If this method is called after the component has been drawn/initialized: Setter for leftButtonIcon.
      Parameters:
      leftButtonIcon - new icon for left button. Default value is "[SKIN]back_arrow.png"
      Returns:
      NavigationBar instance, for chaining setter calls
      See Also:

    • getLeftButtonIcon

      public String getLeftButtonIcon()
      Icon for the leftButton.
      Returns:
      Current leftButtonIcon value. Default value is "[SKIN]back_arrow.png"
      See Also:

    • setLeftButtonTitle

      public NavigationBar setLeftButtonTitle(String leftButtonTitle)
      Title for the leftButton.

      If this method is called after the component has been drawn/initialized: Setter for leftButtonTitle.
      Parameters:
      leftButtonTitle - new title HTML for the left button. Default value is null
      Returns:
      NavigationBar instance, for chaining setter calls
      See Also:

    • getLeftButtonTitle

      public String getLeftButtonTitle()
      Title for the leftButton.
      Returns:
      Current leftButtonTitle value. Default value is null
      See Also:

    • setMaxCenterOffset

      public NavigationBar setMaxCenterOffset(int maxCenterOffset) throws IllegalStateException
      Maximum amount in pixels that the title will be placed off center in an effort to avoid clipping it - see title.
      Parameters:
      maxCenterOffset - New maxCenterOffset value. Default value is 40
      Returns:
      NavigationBar instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getMaxCenterOffset

      public int getMaxCenterOffset()
      Maximum amount in pixels that the title will be placed off center in an effort to avoid clipping it - see title.
      Returns:
      Current maxCenterOffset value. Default value is 40

    • setMiniNavAlign

      public NavigationBar setMiniNavAlign(Alignment miniNavAlign) throws IllegalStateException
      Placement of MiniNavControl, if present:
      • "right" alignment places the miniNav on the far right
      • "center" alignment places the miniNav in the center, or to the right of the title if the title is present
      • "left" alignment will place the miniNav on the left, or to the right of the leftButton if its present.
      Parameters:
      miniNavAlign - New miniNavAlign value. Default value is "right"
      Returns:
      NavigationBar instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getMiniNavAlign

      public Alignment getMiniNavAlign()
      Placement of MiniNavControl, if present:
      • "right" alignment places the miniNav on the far right
      • "center" alignment places the miniNav in the center, or to the right of the title if the title is present
      • "left" alignment will place the miniNav on the left, or to the right of the leftButton if its present.
      Returns:
      Current miniNavAlign value. Default value is "right"

    • getMiniNavControl

      public MiniNavControl getMiniNavControl() throws IllegalStateException
      AutoChild of type MiniNavControl. Not shown by default (see showMiniNavControl). Also, if a customNavControl is provided, then the customNavControl is used instead of an automatically created miniNavControl.

      This component is an AutoChild named "miniNavControl". For an overview of how to use and configure AutoChildren, see Using AutoChildren.

      Returns:
      Current miniNavControl value. Default value is null
      Throws:
      IllegalStateException - if this widget has not yet been rendered.

    • getRightButton

      public NavigationButton getRightButton() throws IllegalStateException
      The button displayed to the right of the title in this NavigationBar. By default this will be a NavigationButton with direction set to "forward".

      The following passthroughs apply:

      This component is an AutoChild named "rightButton". For an overview of how to use and configure AutoChildren, see Using AutoChildren.

      Returns:
      Current rightButton value. Default value is null
      Throws:
      IllegalStateException - if this widget has not yet been rendered.
      See Also:

    • setRightButtonIcon

      public NavigationBar setRightButtonIcon(String rightButtonIcon)
      Icon for the rightButton.

      If this method is called after the component has been drawn/initialized: Setter for rightButtonIcon.
      Parameters:
      rightButtonIcon - new icon for the right button. Default value is null
      Returns:
      NavigationBar instance, for chaining setter calls
      See Also:

    • getRightButtonIcon

      public String getRightButtonIcon()
      Icon for the rightButton.
      Returns:
      Current rightButtonIcon value. Default value is null
      See Also:

    • setRightButtonTitle

      public NavigationBar setRightButtonTitle(String rightButtonTitle)
      Title for the rightButton.

      If this method is called after the component has been drawn/initialized: Setter for rightButtonTitle.
      Parameters:
      rightButtonTitle - new title HTML for the right button. Default value is " "
      Returns:
      NavigationBar instance, for chaining setter calls
      See Also:

    • getRightButtonTitle

      public String getRightButtonTitle()
      Title for the rightButton.
      Returns:
      Current rightButtonTitle value. Default value is " "
      See Also:

    • setShortLeftButtonTitle

      public NavigationBar setShortLeftButtonTitle(String shortLeftButtonTitle)
      Short title to display for the left button title if there is not enough room to show the title for the navigation bar. Setting to null or an empty string ("") will avoid a shortened title ever being used. See title for a full description.

      If this method is called after the component has been drawn/initialized: Setter for shortLeftButtonTitle.
      Parameters:
      shortLeftButtonTitle - new short title HTML. Default value is "Back"
      Returns:
      NavigationBar instance, for chaining setter calls
      See Also:

    • getShortLeftButtonTitle

      public String getShortLeftButtonTitle()
      Short title to display for the left button title if there is not enough room to show the title for the navigation bar. Setting to null or an empty string ("") will avoid a shortened title ever being used. See title for a full description.
      Returns:
      Current shortLeftButtonTitle value. Default value is "Back"
      See Also:

    • setShowLeftButton

      public NavigationBar setShowLeftButton(Boolean showLeftButton)
      If set to false, then the leftButton is not shown.

      If this method is called after the component has been drawn/initialized: Show or hide the leftButton. The leftButton must be a control of this NavigationBar or else it will still be hidden.
      Parameters:
      showLeftButton - if false, then the leftButton will be hidden. If unset or true then the leftButton will be shown as long as it is a member of the controls array. Default value is null
      Returns:
      NavigationBar instance, for chaining setter calls

    • getShowLeftButton

      public Boolean getShowLeftButton()
      If set to false, then the leftButton is not shown.
      Returns:
      Current showLeftButton value. Default value is null

    • setShowMiniNavControl

      public NavigationBar setShowMiniNavControl(boolean showMiniNavControl) throws IllegalStateException
      If set to false, then the miniNavControl is not shown.
      Parameters:
      showMiniNavControl - New showMiniNavControl value. Default value is false
      Returns:
      NavigationBar instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getShowMiniNavControl

      public boolean getShowMiniNavControl()
      If set to false, then the miniNavControl is not shown.
      Returns:
      Current showMiniNavControl value. Default value is false

    • setShowRightButton

      public NavigationBar setShowRightButton(Boolean showRightButton)
      If set to false, then the rightButton is not shown.

      If this method is called after the component has been drawn/initialized: Show or hide the rightButton. The rightButton must be a control of this NavigationBar or else it will still be hidden.
      Parameters:
      showRightButton - if false, then the rightButton will be hidden. If unset or true then the rightButton will be shown as long as it is a member of the controls array. Default value is null
      Returns:
      NavigationBar instance, for chaining setter calls

    • getShowRightButton

      public Boolean getShowRightButton()
      If set to false, then the rightButton is not shown.
      Returns:
      Current showRightButton value. Default value is null

    • setTitle

      public void setTitle(String title)
      The title to display in the center of this navigation bar.

      If there is not enough room for the title with the current titles of the left and right buttons, space will be used as follows:

      • if the title can be fully visible without clipping if it is placed slightly off-center, it will be placed off-center, up to a maximum of maxCenterOffset pixels
      • if that's not enough space, if a shortLeftButtonTitle is provided, it will be used in lieu of the normal left button title
      • if that's still not enough space, the title of the left button will be hidden, leaving only the icon. This will be skipped if either alwaysShowLeftButtonTitle has been set or the button has no icon, which would leave the space blank.
      • if that's still not enough space, the title text will be clipped, showing an ellipsis (where browser support allows this)


      If this method is called after the component has been drawn/initialized: Updates the title for this NavigationBar.
      Overrides:
      setTitle in class Canvas
      Parameters:
      title - new title HTML. Default value is null
      See Also:

    • getTitle

      public String getTitle()
      The title to display in the center of this navigation bar.

      If there is not enough room for the title with the current titles of the left and right buttons, space will be used as follows:

      • if the title can be fully visible without clipping if it is placed slightly off-center, it will be placed off-center, up to a maximum of maxCenterOffset pixels
      • if that's not enough space, if a shortLeftButtonTitle is provided, it will be used in lieu of the normal left button title
      • if that's still not enough space, the title of the left button will be hidden, leaving only the icon. This will be skipped if either alwaysShowLeftButtonTitle has been set or the button has no icon, which would leave the space blank.
      • if that's still not enough space, the title text will be clipped, showing an ellipsis (where browser support allows this)
      Overrides:
      getTitle in class Canvas
      Returns:
      Current title value. Default value is null
      See Also:

    • getTitleLabel

      public Label getTitleLabel() throws IllegalStateException
      The AutoChild label used to display the title in this NavigationBar.

      This component is an AutoChild named "titleLabel". For an overview of how to use and configure AutoChildren, see Using AutoChildren.

      Returns:
      Current titleLabel value. Default value is null
      Throws:
      IllegalStateException - if this widget has not yet been rendered.

    • addDownClickHandler

      public HandlerRegistration addDownClickHandler(DownClickHandler handler)
      Add a downClick handler.

      Notification method fired when the down button on the miniNavControl is clicked.

      Specified by:
      addDownClickHandler in interface HasDownClickHandlers
      Parameters:
      handler - the downClick handler
      Returns:
      HandlerRegistration used to remove this handler

    • addNavigationClickHandler

      public HandlerRegistration addNavigationClickHandler(NavigationClickHandler handler)
      Add a navigationClick handler.

      Notification method fired when the user clicks the NavigationBar.leftButton or NavigationBar.rightButton

      Specified by:
      addNavigationClickHandler in interface HasNavigationClickHandlers
      Parameters:
      handler - the navigationClick handler
      Returns:
      HandlerRegistration used to remove this handler

    • setViewState

      public void setViewState(NavigationBarViewState viewState)
      Sets multiple state attributes of this NavigationBar at once. If this NavigationBar was created with animateStateChanges set to true, then the change-over to the new state attributes will be animated if the direction is either NavigationDirection.FORWARD or NavigationDirection.BACK.
      Parameters:
      viewState - the new view state.

    • setViewState

      public void setViewState(NavigationBarViewState viewState, NavigationDirection direction)
      Sets multiple state attributes of this NavigationBar at once. If this NavigationBar was created with animateStateChanges set to true, then the change-over to the new state attributes will be animated if the direction is either NavigationDirection.FORWARD or NavigationDirection.BACK.
      Parameters:
      viewState - the new view state.
      direction - an optional direction for animation. If not specified or set to NavigationDirection.NONE then the state change will not be animated. The direction should be NavigationDirection.FORWARD for operations that reveal new content and NavigationDirection.BACK for operations that reveal previously-displayed content.

    • addUpClickHandler

      public HandlerRegistration addUpClickHandler(UpClickHandler handler)
      Add a upClick handler.

      Notification method fired when the up button on the miniNavControl is clicked.

      Specified by:
      addUpClickHandler in interface HasUpClickHandlers
      Parameters:
      handler - the upClick handler
      Returns:
      HandlerRegistration used to remove this handler

    • setDefaultProperties

      public static void setDefaultProperties(NavigationBar navigationBarProperties)
      Class level method to set the default properties of this class. If set, then all existing and subsequently created instances of this class will automatically have default properties corresponding to the properties set on the SmartGWT class instance passed to this function before its underlying SmartClient JS object was created. This is a powerful feature that eliminates the need for users to create a separate hierarchy of subclasses that only alter the default properties of this class. Can also be used for skinning / styling purposes.

      Note: This method is intended for setting default attributes only and will affect all instances of the underlying class (including those automatically generated in JavaScript). This method should not be used to apply standard EventHandlers or override methods for a class - use a custom subclass instead. Calling this method after instances have been created can result in undefined behavior, since it bypasses any setters and a class instance may have already examined a particular property and not be expecting any changes through this route.

      Parameters:
      navigationBarProperties - properties that should be used as new defaults when instances of this class are created
      See Also:

    • setControls

      public void setControls(Object... controls)
      Set of controls to show in the navigation bar.

      The standard set of controls included by default are NavigationBarControls.LEFT_BUTTON, NavigationBarControls.TITLE_LABEL, NavigationBarControls.RIGHT_BUTTON.

      Developers may modify the controls to include any Canvases in addition to these standard controls and they will be displayed in the navigation bar.

      Parameters:
      controls - to display in the navigation bar.
      See Also:

    • setLogicalStructure

      public LogicalStructureObject setLogicalStructure(NavigationBarLogicalStructure s)
      Setter implementing the LogicalStructure interface, which supports Eclipse's logical structure debugging facility.

    • getLogicalStructure

      public LogicalStructureObject getLogicalStructure()
      Getter implementing the LogicalStructure interface, which supports Eclipse's logical structure debugging facility.
      Specified by:
      getLogicalStructure in interface LogicalStructure
      Overrides:
      getLogicalStructure in class HLayout