Package com.smartgwt.client.widgets.layout

Class NavPanel

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.SplitPane
com.smartgwt.client.widgets.layout.NavPanel
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, HasPaneChangedHandlers, HasUpClickHandlers
public class NavPanel extends SplitPane
Provides a list or tree of navigation items, each of which specifies a component to be displayed in a mutually exclusive fashion in the navDeck.

A NavPanel can either have a flat list of NavItems or a hierarchy via NavItem.items - use isTree to explicitly control this.

Because NavPanel extends SplitPane, it automatically shifts between side-by-side vs single panel display on handset-sized devices. Specifically, the navGrid is set as the SplitPane.navigationPane and the navDeck is set as the SplitPane.detailPane.

Note that NavPanel is a fairly simple component to replicate by composing other Smart GWT widgets. If you need a component that looks roughly like a NavPanel but will require lots of visual and behavioral customization, consider using the underlying components directly instead of deeply customizing the NavPanel class. A NavPanel is essentially just a TreeGrid and Deck in a SplitPane, with a recordClick handler to call Deck.setCurrentPane() with a component ID stored as an attribute of each Record.

  • Constructor Details

    • NavPanel

      public NavPanel()

    • NavPanel

      public NavPanel(JavaScriptObject jsObj)

  • Method Details

    • getOrCreateRef

      public static NavPanel 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 SplitPane

    • setAutoOpenItems

      public NavPanel setAutoOpenItems(Boolean autoOpenItems) throws IllegalStateException
      When isTree is true, should all nodes be opened automatically? Set to false to prevent nodes being opened by default.
      Parameters:
      autoOpenItems - New autoOpenItems value. Default value is null
      Returns:
      NavPanel instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getAutoOpenItems

      public Boolean getAutoOpenItems()
      When isTree is true, should all nodes be opened automatically? Set to false to prevent nodes being opened by default.
      Returns:
      Current autoOpenItems value. Default value is null

    • setCurrentItem

      public NavPanel setCurrentItem(NavItem currentItem)
      The current NavItem whose pane is showing in the navDeck. This must be an item of this NavPanel if set.

      If this method is called after the component has been drawn/initialized: Setter for currentItem. Note that currentItemId is also updated by this setter.
      Parameters:
      currentItem - the new currentItem. May be null to hide the current item. If newCurrentItem is a separator or header item, then setCurrentItem() has no effect. Default value is null
      Returns:
      NavPanel instance, for chaining setter calls

    • getCurrentItem

      public NavItem getCurrentItem()
      The current NavItem whose pane is showing in the navDeck. This must be an item of this NavPanel if set.
      Returns:
      Current currentItem value. Default value is null

    • setCurrentItemId

      public NavPanel setCurrentItemId(String currentItemId)
      The ID of the current NavItem whose pane is showing in the navDeck. The NavItem must be an item of this NavPanel if set.

      The ID of a NavItem is the item's NavItem.id if set; otherwise, it is the ID of the item's NavItem.pane, though currentItemId may be initialized to either identifier.

      If this method is called after the component has been drawn/initialized: Setter for currentItemId. Note that currentItem is also updated by this setter and this.currentItemId may be normalized to a different identifier.

      Parameters:
      currentItemId - the ID of the new current item, which may be either the item's NavItem.id or the ID of the item's NavItem.pane. May be null or an empty string to hide the current item. If the item with ID newCurrentItemId is a separator or header item, then setCurrentItemId() has no effect. Default value is null
      Returns:
      NavPanel instance, for chaining setter calls
      See Also:

    • getCurrentItemId

      public String getCurrentItemId()
      The ID of the current NavItem whose pane is showing in the navDeck. The NavItem must be an item of this NavPanel if set.

      The ID of a NavItem is the item's NavItem.id if set; otherwise, it is the ID of the item's NavItem.pane, though currentItemId may be initialized to either identifier.

      Returns:
      Current currentItemId value. Default value is null
      See Also:

    • setDeckStyle

      public NavPanel setDeckStyle(String deckStyle) throws IllegalStateException
      CSS style for the navDeck.
      Parameters:
      deckStyle - New deckStyle value. Default value is null
      Returns:
      NavPanel instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
      See Also:

    • getDeckStyle

      public String getDeckStyle()
      CSS style for the navDeck.
      Returns:
      Current deckStyle value. Default value is null
      See Also:

    • setDefaultToFirstItem

      public NavPanel setDefaultToFirstItem(Boolean defaultToFirstItem)
      Select the first NavItem on initialization if neither currentItemId nor currentItem are provided.
      Parameters:
      defaultToFirstItem - New defaultToFirstItem value. Default value is false
      Returns:
      NavPanel instance, for chaining setter calls

    • getDefaultToFirstItem

      public Boolean getDefaultToFirstItem()
      Select the first NavItem on initialization if neither currentItemId nor currentItem are provided.
      Returns:
      Current defaultToFirstItem value. Default value is false

    • setHeaderStyle

      public NavPanel setHeaderStyle(String headerStyle) throws IllegalStateException
      CSS style used when NavItem.isHeader is set on an item. May be overridden for a specific header item by NavItem.customStyle.
      Parameters:
      headerStyle - New headerStyle value. Default value is "navItemHeader"
      Returns:
      NavPanel instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
      See Also:

    • getHeaderStyle

      public String getHeaderStyle()
      CSS style used when NavItem.isHeader is set on an item. May be overridden for a specific header item by NavItem.customStyle.
      Returns:
      Current headerStyle value. Default value is "navItemHeader"
      See Also:

    • setIsTree

      public NavPanel setIsTree(Boolean isTree) throws IllegalStateException
      Whether the NavItems form a Tree or are just a flat list. If isTree is false, TreeGrid.showOpener will be set false on the navGrid so that space isn't wasted.

      The setting for isTree is defaulted immediately before initial draw, based on whether any NavItem has a list of subitems specified via NavItem.items. If no NavItems are provided before draw, isTree defaults to true. Auto-detection is never attempted again even if all NavItems are replaced.

      Set isTree explicitly if auto-detection doesn't yield the correct result for your application.

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

    • getIsTree

      public Boolean getIsTree()
      Whether the NavItems form a Tree or are just a flat list. If isTree is false, TreeGrid.showOpener will be set false on the navGrid so that space isn't wasted.

      The setting for isTree is defaulted immediately before initial draw, based on whether any NavItem has a list of subitems specified via NavItem.items. If no NavItems are provided before draw, isTree defaults to true. Auto-detection is never attempted again even if all NavItems are replaced.

      Set isTree explicitly if auto-detection doesn't yield the correct result for your application.

      Returns:
      Current isTree value. Default value is null

    • setNavAfterMembers

      public NavPanel setNavAfterMembers(Canvas... navAfterMembers) throws IllegalStateException
      Members to add after the navGrid in the navLayout when the panel is first drawn.
      Parameters:
      navAfterMembers - New navAfterMembers value. Default value is null
      Returns:
      NavPanel instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • setNavBeforeMembers

      public NavPanel setNavBeforeMembers(Canvas... navBeforeMembers) throws IllegalStateException
      Members to add before the navGrid in the navLayout when the panel is first drawn.
      Parameters:
      navBeforeMembers - New navBeforeMembers value. Default value is null
      Returns:
      NavPanel instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getNavDeck

      public Deck getNavDeck() throws IllegalStateException
      The Deck area where components specified via NavItem.pane are displayed.

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

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

    • getNavGrid

      public TreeGrid getNavGrid() throws IllegalStateException
      The TreeGrid used to display NavItems.

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

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

    • setNavItemBaseStyle

      public NavPanel setNavItemBaseStyle(String navItemBaseStyle) throws IllegalStateException
      Pass through to set the basestyle on the navGrid autoChild.
      Parameters:
      navItemBaseStyle - New navItemBaseStyle value. Default value is null
      Returns:
      NavPanel instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
      See Also:

    • getNavItemBaseStyle

      public String getNavItemBaseStyle()
      Pass through to set the basestyle on the navGrid autoChild.
      Returns:
      Current navItemBaseStyle value. Default value is null
      See Also:

    • setNavItems

      public NavPanel setNavItems(NavItem... navItems)
      Top-level navigation items to display. You can optionally specify a tree of items using NavItem.items.

      A separator between navigation items can be created by setting NavItem.isSeparator, and a header can be created via NavItem.isHeader.

      Each non-separator and non-header NavItem specifies a component to be displayed in the navDeck via NavItem.pane.

      NavItems can also be individually styled via ListGridRecord._baseStyle or NavItem.customStyle.

      Parameters:
      navItems - New navItems value. Default value is null
      Returns:
      NavPanel instance, for chaining setter calls

    • getNavItems

      public NavItem[] getNavItems()
      Top-level navigation items to display. You can optionally specify a tree of items using NavItem.items.

      A separator between navigation items can be created by setting NavItem.isSeparator, and a header can be created via NavItem.isHeader.

      Each non-separator and non-header NavItem specifies a component to be displayed in the navDeck via NavItem.pane.

      NavItems can also be individually styled via ListGridRecord._baseStyle or NavItem.customStyle.

      Returns:
      Current navItems value. Default value is null

    • getNavLayout

      public VLayout getNavLayout() throws IllegalStateException
      The layout serving as the navigationPane of this panel. By default it contains only the navGrid, but other members can be added before or after, respectively, via navBeforeMembers and navAfterMembers.

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

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

    • setDefaultProperties

      public static void setDefaultProperties(NavPanel navPanelProperties)
      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:
      navPanelProperties - properties that should be used as new defaults when instances of this class are created
      See Also:

    • setLogicalStructure

      public LogicalStructureObject setLogicalStructure(NavPanelLogicalStructure 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 SplitPane