Package com.smartgwt.client.widgets

Class MultiSortPanel

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.MultiSortPanel
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, HasMembersChangedHandlers
public class MultiSortPanel extends Layout
A widget that allows the user to set up complex sorting arrangements by defining a group of SortSpecifiers.

Each SortSpecifier applies to a single property and direction - so, for instance, in a grid with two columns, year and monthNumber, you could sort first by year in descending order and then by monthNumber in ascending order. This would producing a grid sorted by year from largest (most recent) to smallest (least recent) and, within each year, by monthNumber from smallest (January) to largest (December).

  • Constructor Details

    • MultiSortPanel

      public MultiSortPanel()

    • MultiSortPanel

      public MultiSortPanel(JavaScriptObject jsObj)

  • Method Details

    • getOrCreateRef

      public static MultiSortPanel 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 Layout

    • getAddLevelButton

      public IButton getAddLevelButton() throws IllegalStateException
      Automatically generated IButton providing a mechanism for adding new levels to the sort configuration.

      This component is an com.smartgwt.client.types.AutoChild and as such may be customized via multiSortPanel.addLevelButtonProperties and multiSortPanel.addLevelButtonDefaults.

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

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

    • setAddLevelButtonTitle

      public MultiSortPanel setAddLevelButtonTitle(String addLevelButtonTitle) throws IllegalStateException
      The title-text to appear on the addLevelButton
      Parameters:
      addLevelButtonTitle - New addLevelButtonTitle value. Default value is "Add Level"
      Returns:
      MultiSortPanel instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getAddLevelButtonTitle

      public String getAddLevelButtonTitle()
      The title-text to appear on the addLevelButton
      Returns:
      Current addLevelButtonTitle value. Default value is "Add Level"

    • setAscendingTitle

      public MultiSortPanel setAscendingTitle(String ascendingTitle) throws IllegalStateException
      The title-text to appear in the "direction" field's SelectItem for an "ascending" sort
      Parameters:
      ascendingTitle - New ascendingTitle value. Default value is "Ascending"
      Returns:
      MultiSortPanel instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getAscendingTitle

      public String getAscendingTitle()
      The title-text to appear in the "direction" field's SelectItem for an "ascending" sort
      Returns:
      Current ascendingTitle value. Default value is "Ascending"

    • getCopyLevelButton

      public IButton getCopyLevelButton() throws IllegalStateException
      Automatically generated IButton providing a mechanism for duplicating levels in the sort configuration.

      This component is an com.smartgwt.client.types.AutoChild and as such may be customized via multiSortPanel.copyLevelButtonProperties and multiSortPanel.copyLevelButtonDefaults.

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

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

    • setCopyLevelButtonTitle

      public MultiSortPanel setCopyLevelButtonTitle(String copyLevelButtonTitle) throws IllegalStateException
      The title-text to appear on the copyLevelButton
      Parameters:
      copyLevelButtonTitle - New copyLevelButtonTitle value. Default value is "Copy Level"
      Returns:
      MultiSortPanel instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getCopyLevelButtonTitle

      public String getCopyLevelButtonTitle()
      The title-text to appear on the copyLevelButton
      Returns:
      Current copyLevelButtonTitle value. Default value is "Copy Level"

    • getDeleteLevelButton

      public IButton getDeleteLevelButton() throws IllegalStateException
      Automatically generated IButton providing a mechanism for deleting levels from the sort configuration.

      This component is an com.smartgwt.client.types.AutoChild and as such may be customized via multiSortPanel.deleteLevelButtonProperties and multiSortPanel.deleteLevelButtonDefaults.

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

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

    • setDeleteLevelButtonTitle

      public MultiSortPanel setDeleteLevelButtonTitle(String deleteLevelButtonTitle) throws IllegalStateException
      The title-text to appear on the deleteLevelButton
      Parameters:
      deleteLevelButtonTitle - New deleteLevelButtonTitle value. Default value is "Delete Level"
      Returns:
      MultiSortPanel instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getDeleteLevelButtonTitle

      public String getDeleteLevelButtonTitle()
      The title-text to appear on the deleteLevelButton
      Returns:
      Current deleteLevelButtonTitle value. Default value is "Delete Level"

    • setDescendingTitle

      public MultiSortPanel setDescendingTitle(String descendingTitle) throws IllegalStateException
      The title-text to appear in the "direction" field's SelectItem for a "descending" sort
      Parameters:
      descendingTitle - New descendingTitle value. Default value is "Descending"
      Returns:
      MultiSortPanel instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getDescendingTitle

      public String getDescendingTitle()
      The title-text to appear in the "direction" field's SelectItem for a "descending" sort
      Returns:
      Current descendingTitle value. Default value is "Descending"

    • setDirectionFieldTitle

      public MultiSortPanel setDirectionFieldTitle(String directionFieldTitle) throws IllegalStateException
      The title-text to appear in the header of the "direction" field.
      Parameters:
      directionFieldTitle - New directionFieldTitle value. Default value is "Order"
      Returns:
      MultiSortPanel instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getDirectionFieldTitle

      public String getDirectionFieldTitle()
      The title-text to appear in the header of the "direction" field.
      Returns:
      Current directionFieldTitle value. Default value is "Order"

    • setFields

      public MultiSortPanel setFields(DataSourceField... fields) throws IllegalStateException
      The list of fields which the user can choose to sort by.
      Parameters:
      fields - New fields value. Default value is null
      Returns:
      MultiSortPanel instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getFields

      public DataSourceField[] getFields()
      The list of fields which the user can choose to sort by.
      Returns:
      Current fields value. Default value is null

    • setFirstSortLevelTitle

      public MultiSortPanel setFirstSortLevelTitle(String firstSortLevelTitle) throws IllegalStateException
      The title-text to appear in the first column for the first sort-level.
      Parameters:
      firstSortLevelTitle - New firstSortLevelTitle value. Default value is "Sort by"
      Returns:
      MultiSortPanel instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getFirstSortLevelTitle

      public String getFirstSortLevelTitle()
      The title-text to appear in the first column for the first sort-level.
      Returns:
      Current firstSortLevelTitle value. Default value is "Sort by"

    • setIconBaseStyle

      public MultiSortPanel setIconBaseStyle(String iconBaseStyle) throws IllegalStateException
      A CSS style to apply to images in the Level Up and Level Down 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:
      MultiSortPanel 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 Level Up and Level Down 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 MultiSortPanel setIconSize(Integer iconSize) throws IllegalStateException
      The size for the images in the Level Up and Level Down buttons.
      Parameters:
      iconSize - New iconSize value. Default value is null
      Returns:
      MultiSortPanel instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getIconSize

      public Integer getIconSize()
      The size for the images in the Level Up and Level Down buttons.
      Returns:
      Current iconSize value. Default value is null

    • setInitialSort

      public MultiSortPanel setInitialSort(SortSpecifier... initialSort) throws IllegalStateException
      The initial sort configuration to show in the optionsGrid.
      Parameters:
      initialSort - New initialSort value. Default value is null
      Returns:
      MultiSortPanel instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getInitialSort

      public SortSpecifier[] getInitialSort()
      The initial sort configuration to show in the optionsGrid.
      Returns:
      Current initialSort value. Default value is null

    • setInvalidListPrompt

      public MultiSortPanel setInvalidListPrompt(String invalidListPrompt) throws IllegalStateException
      This is a dynamic string - text within ${...} will be evaluated as JS code when the message is displayed.

      Default value returns

      Columns may only be used once: [some field's title] is used multiple times

      Parameters:
      invalidListPrompt - New invalidListPrompt value. Default value is "Columns may only be used once: '${title}' is used multiple times."
      Returns:
      MultiSortPanel instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created
      See Also:

    • getInvalidListPrompt

      public String getInvalidListPrompt()
      This is a dynamic string - text within ${...} will be evaluated as JS code when the message is displayed.

      Default value returns

      Columns may only be used once: [some field's title] is used multiple times

      Returns:
      Current invalidListPrompt value. Default value is "Columns may only be used once: '${title}' is used multiple times."
      See Also:

    • getLevelDownButton

      public ImgButton getLevelDownButton() throws IllegalStateException
      Automatically generated ImgButton providing a mechanism for moving existing sort-levels down in the sort configuration.

      This component is an com.smartgwt.client.types.AutoChild and as such may be customized via multiSortPanel.levelDownButtonProperties and multiSortPanel.levelDownButtonDefaults.

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

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

    • setLevelDownButtonTitle

      public MultiSortPanel setLevelDownButtonTitle(String levelDownButtonTitle) throws IllegalStateException
      The hover-prompt for the Level Down button.
      Parameters:
      levelDownButtonTitle - New levelDownButtonTitle value. Default value is "Move Level Down"
      Returns:
      MultiSortPanel instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getLevelDownButtonTitle

      public String getLevelDownButtonTitle()
      The hover-prompt for the Level Down button.
      Returns:
      Current levelDownButtonTitle value. Default value is "Move Level Down"

    • getLevelUpButton

      public ImgButton getLevelUpButton() throws IllegalStateException
      Automatically generated ImgButton providing a mechanism for moving existing sort-levels up in the sort configuration.

      This component is an com.smartgwt.client.types.AutoChild and as such may be customized via multiSortPanel.levelUpButtonProperties and multiSortPanel.levelUpButtonDefaults.

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

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

    • setLevelUpButtonTitle

      public MultiSortPanel setLevelUpButtonTitle(String levelUpButtonTitle) throws IllegalStateException
      The hover-prompt for the Level Up button.
      Parameters:
      levelUpButtonTitle - New levelUpButtonTitle value. Default value is "Move Level Up"
      Returns:
      MultiSortPanel instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getLevelUpButtonTitle

      public String getLevelUpButtonTitle()
      The hover-prompt for the Level Up button.
      Returns:
      Current levelUpButtonTitle value. Default value is "Move Level Up"

    • setMaxLevels

      public MultiSortPanel setMaxLevels(Integer maxLevels) throws IllegalStateException
      The maximum number of levels of sorting that can be applied. Since each sort-property or field-name can be used only once in a given multi-sort operation, if no maxLevels value or a value larger than the total number of available properties is specified, it will default to the total number of available properties.
      Parameters:
      maxLevels - New maxLevels value. Default value is null
      Returns:
      MultiSortPanel instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getMaxLevels

      public Integer getMaxLevels()
      The maximum number of levels of sorting that can be applied. Since each sort-property or field-name can be used only once in a given multi-sort operation, if no maxLevels value or a value larger than the total number of available properties is specified, it will default to the total number of available properties.
      Returns:
      Current maxLevels value. Default value is null

    • getOptionsGrid

      public ListGrid getOptionsGrid() throws IllegalStateException
      Automatically generated ListGrid allowing the user to configure a set of SortSpecifiers.

      This component is an com.smartgwt.client.types.AutoChild and as such may be customized via multiSortPanel.optionsGridProperties and multiSortPanel.optionsGridDefaults.

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

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

    • setOtherSortLevelTitle

      public MultiSortPanel setOtherSortLevelTitle(String otherSortLevelTitle) throws IllegalStateException
      The title-text to appear in the first column for all sort-levels other than the first.
      Parameters:
      otherSortLevelTitle - New otherSortLevelTitle value. Default value is "Then by"
      Returns:
      MultiSortPanel instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getOtherSortLevelTitle

      public String getOtherSortLevelTitle()
      The title-text to appear in the first column for all sort-levels other than the first.
      Returns:
      Current otherSortLevelTitle value. Default value is "Then by"

    • setPropertyFieldTitle

      public MultiSortPanel setPropertyFieldTitle(String propertyFieldTitle) throws IllegalStateException
      The title-text to appear in the header of the "property" field.
      Parameters:
      propertyFieldTitle - New propertyFieldTitle value. Default value is "Column"
      Returns:
      MultiSortPanel instance, for chaining setter calls
      Throws:
      IllegalStateException - this property cannot be changed after the component has been created

    • getPropertyFieldTitle

      public String getPropertyFieldTitle()
      The title-text to appear in the header of the "property" field.
      Returns:
      Current propertyFieldTitle value. Default value is "Column"

    • getNumLevels

      public int getNumLevels()
      Return the number of levels of sorting that have been configured.
      Returns:
      The number of levels of sorting that have been configured

    • getSort

      public SortSpecifier[] getSort()
      Returns all configured sorting levels, as an array of SortSpecifiers.
      Returns:
      the SortSpecifiers for all configured sorting levels

    • getSortLevel

      public SortSpecifier getSortLevel(int levelNum)
      Return a SortSpecifier object for the requested levelNum.
      Parameters:
      levelNum - The index of the level to return a SortSpecifier for
      Returns:
      A SortSpecifier representing the requested levelNum

    • sortChanged

      public void sortChanged(SortSpecifier... sortLevels)
      Fired whenever the sort configuration changes. The single parameter is an array of SortSpecifiers that represent the list of sort-levels as they appear after whatever change has occurred.
      Parameters:
      sortLevels - The current sort configuration, after any changes

    • validate

      public boolean validate()
      Validate that no two SortSpecifiers sort on the same property.
      Returns:
      True if validation succeeds, false if any property is used twice

    • setDefaultProperties

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

    • setLogicalStructure

      public LogicalStructureObject setLogicalStructure(MultiSortPanelLogicalStructure 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 Layout