[]
DEMOS DOCS API PRICING
FREE TRIAL
(Showing Draft Content)

ValueSortField

Class ValueSortField

java.lang.Object
com.grapecity.documents.excel.SortFieldBase
com.grapecity.documents.excel.ValueSortField
All Implemented Interfaces:
ISortField, IValueSortField
public class ValueSortField extends SortFieldBase implements IValueSortField
Represents a sort field that sorts data by cell values.

Use this class to define value-based sorting in ascending order, descending order, or by a custom value list. A ValueSortField also lets you control how text values are treated during sorting through SortDataOption.


 worksheet.getRange("A1:A4").setValue(new Object[][] {
     {"10"},
     {"2"},
     {"30"},
     {"4"}
 });
 ValueSortField sortField = new ValueSortField(worksheet.getRange("A1:A4"), SortOrder.Ascending);
 sortField.setDataOption(SortDataOption.TextAsNumbers);

  • Constructor Details

    • ValueSortField

      public ValueSortField(IRange key)
      Creates a value sort field for the specified key range. The sort order defaults to Ascending. 
      
 worksheet.getRange("A1:B4").setValue(new Object[][] {
     {2, "B"}, {1, "C"}, {1, "A"}, {3, "D"}
 });
 ValueSortField sortField = new ValueSortField(worksheet.getRange("A1:A4"));
 worksheet.getRange("A1:B4").sort(SortOrientation.Columns, false, sortField);
      Parameters:
      key - The range that provides the values used as the sort key. Must not be null.

    • ValueSortField

      public ValueSortField(IRange key, SortOrder order)
      Creates a value sort field for the specified key range and sort order.

      Use this constructor with IRange.sort(SortOrientation,boolean,IValueSortField...) to sort a range by values.

      
 IRange range = worksheet.getRange("A1:B4");
 range.setValue(new Object[][] {
     {2, "g"},
     {1, "z"},
     {1, "a"},
     {3, "b"}
 });
 ValueSortField sortField = new ValueSortField(worksheet.getRange("A1:A4"), SortOrder.Descending);
 range.sort(SortOrientation.Columns, false, sortField);
      Parameters:
      key - The range that provides the values used as the sort key.
      order - The sort order to apply to the key range.

    • ValueSortField

      public ValueSortField(IRange key, String customValues)
      Creates a value sort field that uses a custom sort list.

      Use this constructor to sort by a user-defined value sequence instead of the normal ascending or descending order. The custom list string can contain values such as 3,2,5,1 or quoted text entries such as "\"High\", \"Medium\", \"Low\"".

      
 worksheet.getRange("A1:B3").setValue(new Object[][] {
     {"Medium", "Review"},
     {"Low", "Archive"},
     {"High", "Deploy"}
 });
 ValueSortField sortField = new ValueSortField(worksheet.getRange("A1:A3"), "\"High\", \"Medium\", \"Low\"");
 worksheet.getRange("A1:B3").sort(SortOrientation.Columns, false, sortField);
      Parameters:
      key - The range that provides the sort key.
      customValues - The custom list string that defines the sort order.

  • Method Details

    • getDataOption

      public final SortDataOption getDataOption()
      Gets the data option of the sort field.

      The data option specifies how text values are treated during sorting, such as sorting text normally or sorting text as numbers. Use setDataOption(SortDataOption) to change this setting.

      
 ValueSortField sortField = new ValueSortField(worksheet.getRange("A2:A5"), SortOrder.Ascending);
 sortField.setDataOption(SortDataOption.TextAsNumbers);
 SortDataOption dataOption = sortField.getDataOption();
      Specified by:
      getDataOption in interface IValueSortField
      Returns:
      The data option of the sort field.

    • setDataOption

      public final void setDataOption(SortDataOption value)
      Sets the data option of the sort field.

      Use this method to control how text values are treated during sorting. For example, SortDataOption.TextAsNumbers sorts text values as numeric data.

      
 ValueSortField sortField = new ValueSortField(worksheet.getRange("A2:A5"), SortOrder.Ascending);
 sortField.setDataOption(SortDataOption.TextAsNumbers);
      Specified by:
      setDataOption in interface IValueSortField
      Parameters:
      value - The data option to apply to the sort field.

    • getOrder

      public final SortOrder getOrder()
      Gets the sort order.

      Returns the SortOrder currently configured for this value sort field. Use getCustomValues() to inspect whether the field is configured with a custom value list.

      
 worksheet.getRange("A1:A4").setValue(new Object[][] {{3}, {1}, {4}, {2}});
 ValueSortField sortField = new ValueSortField(worksheet.getRange("A1:A2"), SortOrder.Descending);
 SortOrder order = sortField.getOrder();
      Specified by:
      getOrder in interface IValueSortField
      Returns:
      The current sort order for this value sort field.

    • setOrder

      public final void setOrder(SortOrder value)
      Sets the sort order. 
      
 ValueSortField sortField = new ValueSortField(worksheet.getRange("A1:A4"), SortOrder.Ascending);
 sortField.setOrder(SortOrder.Descending);
 SortOrder order = sortField.getOrder();
      Specified by:
      setOrder in interface IValueSortField
      Parameters:
      value - The sort order.

    • getCustomValues

      public final String getCustomValues()
      Gets the custom value list, such as 3,2,5,1.

      If this property is not an empty string, the sort order is determined by the custom values list.

      
 worksheet.getRange("A1:A5").setValue(new Object[][] {
     {"Value"},
     {3},
     {2},
     {5},
     {1}
 });
 ValueSortField sortField = new ValueSortField(worksheet.getRange("A2:A5"), "3,2,5,1");
 String customValues = sortField.getCustomValues();
      Specified by:
      getCustomValues in interface IValueSortField
      Returns:
      The custom value list string. Returns an empty string if no custom sorting values are specified.

    • setCustomValues

      public final void setCustomValues(String value)
      Sets the custom value list, such as 3,2,5,1.

      If this property is not an empty string, the sort order is determined by the custom values list.

      
 worksheet.getRange("A1:A5").setValue(new Object[][] {
     {"Value"},
     {3},
     {2},
     {5},
     {1}
 });
 ValueSortField sortField = new ValueSortField(worksheet.getRange("A2:A5"), "3,2,5,1");
 sortField.setCustomValues("5,3,2,1");
      Specified by:
      setCustomValues in interface IValueSortField
      Parameters:
      value - The custom value list string. Sets an empty string if no custom sorting values are specified.