Package io.keikai.range

Interface SRange

All Known Implementing Classes:
PasteRangeImpl, RangeImpl
public interface SRange
The main API to manipulate Spreadsheet's book model. It may represent one or more cells, a row, a column, or a selection of a block of cells. You can use this class to perform most user operations.
Since:
3.5.0
Author:
dennis

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static enum 
    SRange.ApplyBorderType
     
    static enum 
    SRange.AutoFilterOperation
     
    static enum 
    SRange.DeleteShift
    Shift direction of delete api
    static enum 
    SRange.FillType
     
    static enum 
    SRange.InsertCopyOrigin
    Copy origin format/style of insert
    static enum 
    SRange.InsertShift
    Shift direction of insert api
    static enum 
    SRange.PasteOperation
     
    static enum 
    SRange.PasteType
     
    static enum 
    SRange.SheetVisible
     
    static enum 
    SRange.SortDataOption
     

  • Method Summary

    Modifier and Type
    Method
    Description
    SChart
    addChart(ViewAnchor anchor, SChart.ChartType type, SChart.ChartGrouping grouping, SChart.ChartLegendPosition pos, boolean isThreeD)
    Add a chart into the sheet of this Range
    SChart
    addChart(String name, ViewAnchor anchor, SChart.ChartType type, SChart.ChartGrouping grouping, SChart.ChartLegendPosition pos, boolean isThreeD)
    Add a chart into the sheet of this Range
    SPicture
    addPicture(ViewAnchor anchor, byte[] image, SPicture.Format format)
    Add a picture into the sheet of this Range
    void
    applyAutoFilter()
    Apply the autofilter with the old condition and current cell values
    void
    clearAll()
    Clear data contains, style and unmerge this range
    void
    clearCellStyles()
    Clear the cell styles of this Range
    void
    clearContents()
    Clears the data from this Range.
    void
    clearOutlineLevel()
    Clears all outline level for all groups that intersect with the range.
    void
    clearTrace()
    Clears the tracing of this range.
    SSheet
    cloneSheet(String name)
    Clone sheet as specified in this Range.
    SSheet
    cloneSheetFrom(String name, SSheet sheet)
    Clone from the specified source sheet to the owner book of this range.
    SSheet
    cloneSheetFrom(String name, SSheet sheet, boolean valueOnly)
    Clone from the specified source sheet to the owner book of this range.
    void
    collapse()
    Collapses one group by matching with the 1st selected area of this Range in rows or columns.
    SRange
    copy(SRange dstRange)
    Copy data from this range to the specified destination range.
    SRange
    copy(SRange dstRange, boolean cut)
    cut the selected range and paste to destination range.
    void
    createName(String nameName)
    Create a SName that refer to this range.
    SSheet
    createSheet(String name)
    Create sheet of this book as specified in this Range.
    void
    delete(SRange.DeleteShift shift)
    Delete cells of this Range.
    void
    deleteChart(SChart chart)
    Delete an existing chart from the sheet of this Range.
    void
    deletePicture(SPicture picture)
    Delete an existing picture from the sheet of this Range.
    void
    deleteSheet()
    Delete sheet of this Range.
    void
    deleteValidation()
    Delete the SDataValidation associated in the specified range.
    SAutoFilter
    enableAutoFilter(boolean enable)
    Enable the auto filter and return it, get null if you disable it.
    SAutoFilter
    enableAutoFilter(int field, SAutoFilter.FilterOp filterOp, Object criteria1, Object criteria2, Boolean showButton)
    Filters a list specified by this Range and returns an AutoFilter object.
    void
    expand()
    Expands one group by matching with the 1st selected area of this Range in rows or columns.
    void
    fill(SRange dstRange, SRange.FillType fillType)
    Perform an auto fill on the specified destination Range.
    void
    fillDown()
    Fills down from the top cells of this Range to the rest of this Range.
    void
    fillLeft()
    Fills left from the rightmost cells of this Range to the rest of this Range.
    void
    fillRight()
    Fills right from the leftmost cells of this Range to the rest of this Range.
    void
    fillUp()
    Fills up from the bottom cells of this Range to the rest of this Range.
    SRange
    findAutoFilterRange()
    To find a range of cells for applying auto filter according to this range.
    SBook
    getBook()
    Returns the associated SBook of this range.
    SBookSeries
    getBookSeries()
    Returns the associated SBookSeries of this range.
    String
    getCellDataFormat()
    Gets the first(top-left) cell's format, if the cell's format is the special LOCALE aware format (such as m/d/yyyy), it transfer the format by LOCALE(e.g m/d/yyyy will transfer to yyyy/m/d in TW locale)
    String
    getCellFormatText()
    Gets the first(top-left) cell's formatted text, if the cell's format is the special LOCALE aware format (such as m/d/yyyy), it will formats the value by transferred format (e.g m/d/yyyy will transfer to yyyy/m/d in TW locale)
    SCellStyle
    getCellStyle()
    Gets the first(top-left) cell's style
    int
    getColumn()
    Returns the number of the 1st column of the 1st area in this Range(0-based; i.e.
    List<SRange>
    getColumnGroups()
    Returns all group ranges for columns, which intersect with this range.
    List<SRange>
    getColumnGroups(int outlineLevel)
    Returns all group ranges matched the given outline level for columns, which intersect with this range.
    List<SRange>
    getColumnGroups(int fromOutlineLevel, int toOutlineLevel)
    Returns all group ranges matched between fromOutlineLevel and toOutlineLevel for columns, which intersect with this range.
    SRange
    getColumns()
    Returns a SRange that represent columns of the 1st selected area of this Range.
    String
    getCommentRichText()
    Return the comment rich edit text of the left top cell of this Range.
    CellRegion
    getDataRegion()
    Returns the region which contains data(including chart, picture, and fills) in the sheet of this Range; return null if empty sheet.
    Set<SRange>
    getDependents()
    Returns all Range(s) that are the direct or indirect dependents of this cell Range.
    Set<SRange>
    getDirectDependents()
    Returns Range(s) that are the direct dependents of this cell Range.
    Set<SRange>
    getDirectPrecedents()
    Returns Range(s) that are the direct precedents of this cell Range.
    String
    getEditText()
    Return the edit text of this Range.
    SHyperlink
    getHyperlink()
    Returns the hyperlink of this Range.
    int
    getLastColumn()
    Returns the number of the last column of the 1st area in this Range(0-based; i.e.
    int
    getLastRow()
    Returns the number of the last row of the 1st area in this Range(0-based; i.e. row1 return 0)
    ReadWriteLock
    getLock()
     
    CellRegion
    getMergedRegion()
    Returns the merged region of the left top cell of this Range if any; otherwise, returns null if not a merged region.
    SRange
    getOffset(int rowOffset, int colOffset)
    Returns a SRange that represents a range that offset from this Range.
    SFont
    getOrCreateFont(SFont.Boldweight boldweight, String htmlColor, int fontHeight, String fontName, boolean italic, boolean strikeout, SFont.TypeOffset typeOffset, SFont.Underline underline)
    Get font if exists or create font if not exists from the book of this range and return it.
    int
    getOutlineLevel()
    Returns the outline level of the group by matching with the 1st selected area of this Range in rows or columns.
    Set<SRange>
    getPrecedents()
    Returns all Range(s) that are the direct or indirect precedents of this cell Range.
    String
    getRichText()
    Return the rich edit text of the left top cell of this Range.
    int
    getRow()
    Returns the number of the 1st row of the 1st area in this Range(0-based; i.e. row1 return 0)
    List<SRange>
    getRowGroups()
    Returns all group ranges for rows, which intersect with this range.
    List<SRange>
    getRowGroups(int outlineLevel)
    Returns all group ranges matched the given outline level for rows, which intersect with this range.
    List<SRange>
    getRowGroups(int fromOutlineLevel, int toOutlineLevel)
    Returns all group ranges matched between fromOutlineLevel and toOutlineLevel for rows, which intersect with this range.
    SRange
    getRows()
    Returns a SRange that represent rows of the 1st selected area of this Range.
    SSheet
    getSheet()
    Returns associate SSheet of this range.
    SSheetProtection
    getSheetProtection()
    Gets SSheetProtection protection options that tells what are allowed operations for the protected sheet of the first region of this range.
    List<SDataValidation>
    getValidations()
    Gets SDataValidations associated with this range; if more than one validation is present, will return at most two.
    Object
    getValue()
    Returns left top cell value of this Range.
    List<Object>
    getValues()
    Returns all cell values from left to right and top to bottom of this Range in one dimension list.
    void
    group()
    Groups the rows or columns by matching the range, which increases their outline level.
    void
    insert(SRange.InsertShift shift, SRange.InsertCopyOrigin copyOrigin)
    Insert cells of this Range.
    boolean
    isAnyCellProtected()
    Returns whether any cell is protected and locked in this Range.
    boolean
    isCollapsed()
    Returns whether the group by matching with the 1st selected area of this Range in rows or columns, which has collapsed or not.
    boolean
    isCommentVisible()
    Returns whether the comment is always visible at the left top cell of this range; if no comment at the cell, it returns false.
    boolean
    isProtected()
    Gets the first region's protection status; return true if the sheet of the first region is protected and some cells in the region is locked.
    boolean
    isSheetProtected()
    Gets whether the sheet of the first region of this Range is protected.
    boolean
    isSummaryBelow()
    Returns whether to display group summary as below for rows.
    boolean
    isSummaryRight()
    Returns whether to display group summary as right for columns.
    boolean
    isWholeColumn()
    Check if this range cover an entire columns (form 0, and last row to the max available column of a sheet)
    boolean
    isWholeRow()
    Check if this range cover an entire rows (form 0, and last row to the max available row of a sheet)
    boolean
    isWholeSheet()
    Check if this range cover an entire sheet
    void
    merge(boolean across)
    Merge cells of this range into a merged cell.
    void
    move(int nRow, int nCol)
    Move this range to a new place as specified by row offset (negative value to move up; positive value to move down) and column offset(negative value to move left; positive value to move right)
    void
    moveChart(SChart chart, ViewAnchor anchor)
    Move the chart to the new anchor.
    void
    movePicture(SPicture picture, ViewAnchor anchor)
    Update picture anchor.
    void
    notifyChange()
    Notify this range has been changed.
    void
    notifyChange(CellAttribute cellAttr)
    Notify this range has been changed with the specified attribute.
    void
    notifyChange(String[] variables)
    Notify the variables in this range has been changed.
    void
    notifyCustomEvent(String customEventName, Object data, boolean writeLock)
    Send a custom model event to all book's listener, the event name must not conflict with that in ModelEvents
    SRange
    pasteSpecial(SRange dstRange, SRange.PasteType pasteType, SRange.PasteOperation pasteOp, boolean skipBlanks, boolean transpose)
    Pastes to a destination Range from this range.
    void
    protectSheet(String password, boolean allowSelectingLockedCells, boolean allowSelectingUnlockedCells, boolean allowFormattingCells, boolean allowFormattingColumns, boolean allowFormattingRows, boolean allowInsertColumns, boolean allowInsertRows, boolean allowInsertingHyperlinks, boolean allowDeletingColumns, boolean allowDeletingRows, boolean allowSorting, boolean allowFiltering, boolean allowUsingPivotTables, boolean drawingObjects, boolean scenarios)
    Protect a SSheet so that it cannot be modified.
    void
    refresh(boolean includeDependants)
    Evaluate(if not cached), update data model, and refresh UI of this range and its dependent cells if the includeDependents is true.
    void
    refresh(boolean includeDependents, boolean clearCache, boolean enforceEval)
    Update data model and refresh UI of this range and its dependent cells if the argument includeDependents is true.
    void
    resetAutoFilter()
    Reset the autofilter, clear the condition, shows all the hidden row
    void
    setArrayFormula(String txt)
    Set an array formula as input by the end user.
    boolean
    setAutoRefresh(boolean auto)
    Turn on(true)/off(false) of auto refresh of this range and return previous on/off status; default is true.
    void
    setBorders(SRange.ApplyBorderType borderIndex, SBorder.BorderType lineStyle, String color)
    Adds/Remove border of all cells within this range upon the specified border type.
    void
    setCellStyle(SCellStyle style)
    Sets a Style object to this Range.
    void
    setColumnWidth(int widthPx)
    Sets column width in unit of pixel
    void
    setColumnWidth(int widthPx, boolean custom)
    Sets the width(in pixel) of column in this range, it effects to whole column.
    void
    setCommentRichText(String html)
    Set comment rich text into the left top cell of this range; null to delete it.
    void
    setCommentVisible(boolean visible)
    Set comment visibility into the left top cell of this range; if no comment at the cell, it simply ignored.
    void
    setDisplayGridlines(boolean show)
    Sets whether show the gridlines of the sheets in this Range.
    void
    setEditText(String txt)
    Set plain text as input by the end user.
    void
    setFreezePanel(int numOfRow, int numOfColumn)
    Set the freeze panel
    void
    setHidden(boolean hidden)
    Sets whether this rows or columns are hidden(useful only if this Range cover entire column or entire row)
    void
    setHyperlink(SHyperlink.HyperlinkType linkType, String address, String display)
    Sets the hyperlink of this Range
    void
    setNameName(String namename, String newname)
    Set(Rename) the name of the Name(or Table) as specified in this Range(a Book or a Sheet).
    void
    setRichText(String html)
    Set rich text into the left top cell of this range.
    void
    setRowHeight(int heightPx)
    Sets row height in unit of pixel
    void
    setRowHeight(int heightPx, boolean custom)
    Sets the height(in pixel) of row in this range, it effects to whole row.
    void
    setSheetName(String name)
    Set(Rename) the name of the sheet as specified in this Range.
    void
    setSheetOrder(int pos)
    Sets the order of the sheet as specified in this Range.
    void
    setSheetVisible(SRange.SheetVisible visible)
    Set Sheet visibility; can be SheetVisible.VISIBLE, SheetVisible.HIDDEN, and SheetVisible.VERY_HIDDEN.
    void
    setStringValue(String value)
    Save the specified value into this range as a String no matter the value is prefixed with '=' or not.
    void
    setSummaryBelow(boolean summaryBelow)
    Sets to be true to display summary group as below or to be false to display summary group as above for rows.
    void
    setSummaryRight(boolean summaryRight)
    Sets to be true to display summary group as right or to be false to display summary group as left for columns.
    void
    setValidation(SDataValidation.ValidationType validationType, boolean ignoreBlank, SDataValidation.OperatorType operatorType, boolean inCellDropDown, String formula1, String formula2, boolean showInput, String inputTitle, String inputMessage, boolean showError, SDataValidation.AlertStyle alertStyle, String errorTitle, String errorMessage)
    Add if not exist or modify an existing SDataValidation to this range.
    void
    setValue(Object value)
    Set value into this Range.
    void
    setValues(Object... values)
    Set values into this Range from left to right and top to bottom consistently.
    void
    sort(SRange key1, boolean descending1, SRange.SortDataOption dataOption1, SRange key2, boolean descending2, SRange.SortDataOption dataOption2, SRange key3, boolean descending3, SRange.SortDataOption dataOption3, int hasHeader, boolean matchCase, boolean sortByRows)
    Sort this Range according the specified parameters
    void
    traceDependents()
    Trace the precedent of this range.
    void
    tracePrecedents()
    Trace the dependents of this range.
    void
    ungroup()
    Ungroups the rows or columns by matching the range, which decreases their outline level.
    void
    unmerge()
    Un-merge a merged cell in this range to separated cells.
    boolean
    unprotectSheet(String password)
    Removes protection from a sheet.
    void
    updateChart(SChart chart)
    Notify the model that a chart contains change, for example, chart data changes.
    SDataValidation
    validate(String txt)
    Returns whether the plain text input by the end user is valid or not; note the validation only applies to the left-top cell of this Range.

  • Method Details

    • getLock

      ReadWriteLock getLock()

    • getHyperlink

      SHyperlink getHyperlink()
      Returns the hyperlink of this Range.
      Returns:
      hyperlink of this Range

    • getRichText

      String getRichText()
      Return the rich edit text of the left top cell of this Range.
      Returns:
      the rich edit text of this Range.
      Since:
      3.6.0

    • setRichText

      void setRichText(String html)
      Set rich text into the left top cell of this range.
      Since:
      3.6.0

    • getEditText

      String getEditText()
      Return the edit text of this Range.
      Returns:
      the edit text of this Range.

    • setEditText

      void setEditText(String txt)
      Set plain text as input by the end user.
      Parameters:
      txt - the string input by the end user.

    • setArrayFormula

      void setArrayFormula(String txt)
      Set an array formula as input by the end user.
      Parameters:
      txt - the string input by the end user.
      Since:
      6.0.0

    • copy

      SRange copy(SRange dstRange, boolean cut)
      cut the selected range and paste to destination range.
      Parameters:
      dstRange -
      Returns:
      the real destination range.
      Since:
      3.0.0

    • copy

      SRange copy(SRange dstRange)
      Copy data from this range to the specified destination range.
      Parameters:
      dstRange - the destination range.
      Returns:
      the real destination range.

    • pasteSpecial

      SRange pasteSpecial(SRange dstRange, SRange.PasteType pasteType, SRange.PasteOperation pasteOp, boolean skipBlanks, boolean transpose)
      Pastes to a destination Range from this range.
      Parameters:
      dstRange - the destination range to be pasted into.
      pasteType - the part of the range to be pasted.
      pasteOp - the paste operation
      skipBlanks - true to not have blank cells in the ranage to paste into destination Range; default false.
      transpose - true to transpose rows and columns when pasting to this range; default false.
      Returns:
      real destination range that was pasted into.

    • insert

      void insert(SRange.InsertShift shift, SRange.InsertCopyOrigin copyOrigin)
      Insert cells of this Range.
      Parameters:
      shift - can be SRange.InsertShift.DEFAULT, {SRange.InsertShift.DOWN, or SRange.InsertShift.RIGHT.
      copyOrigin - from where to copy the format to the insert area(SRange.InsertCopyOrigin.FORMAT_LEFT_ABOVE / SRange.InsertCopyOrigin.FORMAT_RIGHT_BELOW)

    • delete

      void delete(SRange.DeleteShift shift)
      Delete cells of this Range.
      Parameters:
      shift - can be SRange.DeleteShift.DEFAULT, {SRange.DeleteShift.UP, or SRange.DeleteShift.LEFT.

    • sort

      void sort(SRange key1, boolean descending1, SRange.SortDataOption dataOption1, SRange key2, boolean descending2, SRange.SortDataOption dataOption2, SRange key3, boolean descending3, SRange.SortDataOption dataOption3, int hasHeader, boolean matchCase, boolean sortByRows)
      Sort this Range according the specified parameters
      Parameters:
      key1 - key1 for sorting
      descending1 - true to do descending sort; false to do ascending sort for key1.
      dataOption1 - see numeric String as number or not for key1.
      key2 - key2 for sorting
      descending2 - true to do descending sort; false to do ascending sort for key2.
      dataOption2 - see numeric String as number or not for key2.
      key3 - key3 for sorting
      descending3 - true to do descending sort; false to do ascending sort for key3.
      dataOption3 - see numeric String as number or not for key3.
      hasHeader - whether sort range includes header
      matchCase - true to match the string cases; false to ignore string cases
      sortByRows - true to sort by rows(change columns orders); false to sort by columns(change row orders).

    • merge

      void merge(boolean across)
      Merge cells of this range into a merged cell.
      Parameters:
      across - true to merge cells in each row; default to false.

    • unmerge

      void unmerge()
      Un-merge a merged cell in this range to separated cells.

    • setBorders

      void setBorders(SRange.ApplyBorderType borderIndex, SBorder.BorderType lineStyle, String color)
      Adds/Remove border of all cells within this range upon the specified border type.
      Parameters:
      borderIndex - one of SRange.ApplyBorderType
      lineStyle - border line style, one of SBorder.BorderType
      color - color in HTML format; i.e., #rrggbb.

    • move

      void move(int nRow, int nCol)
      Move this range to a new place as specified by row offset (negative value to move up; positive value to move down) and column offset(negative value to move left; positive value to move right)
      Parameters:
      nRow - how many rows to move this range
      nCol - how many columns to move this range

    • setColumnWidth

      void setColumnWidth(int widthPx)
      Sets column width in unit of pixel
      Parameters:
      widthPx -

    • setRowHeight

      void setRowHeight(int heightPx)
      Sets row height in unit of pixel
      Parameters:
      heightPx -

    • setColumnWidth

      void setColumnWidth(int widthPx, boolean custom)
      Sets the width(in pixel) of column in this range, it effects to whole column.
      Parameters:
      widthPx - width in pixel
      custom - mark it as custom value

    • setRowHeight

      void setRowHeight(int heightPx, boolean custom)
      Sets the height(in pixel) of row in this range, it effects to whole row.
      Parameters:
      heightPx - width in pixel
      custom - mark it as custom value

    • getSheet

      SSheet getSheet()
      Returns associate SSheet of this range.
      Returns:
      associate SSheet of this range.

    • setCellStyle

      void setCellStyle(SCellStyle style)
      Sets a Style object to this Range.
      Parameters:
      style - the style object

    • clearCellStyles

      void clearCellStyles()
      Clear the cell styles of this Range

    • fill

      void fill(SRange dstRange, SRange.FillType fillType)
      Perform an auto fill on the specified destination Range. Note the given destination Range must include this source Range.
      Parameters:
      dstRange - destination range to do the auto fill. Note the given destination Range must include this source Range
      fillType - the fillType

    • clearContents

      void clearContents()
      Clears the data from this Range.

    • fillDown

      void fillDown()
      Fills down from the top cells of this Range to the rest of this Range.

    • fillLeft

      void fillLeft()
      Fills left from the rightmost cells of this Range to the rest of this Range.

    • fillRight

      void fillRight()
      Fills right from the leftmost cells of this Range to the rest of this Range.

    • fillUp

      void fillUp()
      Fills up from the bottom cells of this Range to the rest of this Range.

    • findAutoFilterRange

      SRange findAutoFilterRange()
      To find a range of cells for applying auto filter according to this range. Usually, these two ranges are different. This method searches the filtering range through a specific rules.
      Returns:
      a range of cells for applying auto filter or null if can't find one from this Range.
      Since:
      3.0.0

    • enableAutoFilter

      SAutoFilter enableAutoFilter(int field, SAutoFilter.FilterOp filterOp, Object criteria1, Object criteria2, Boolean showButton)
      Filters a list specified by this Range and returns an AutoFilter object.
      Parameters:
      field - offset of the field on which you want to base the filter on (1-based; i.e. leftmost column in this range is field 1).
      filterOp - , Use FILTEROP_AND and FILTEROP_OR with criteria1 and criterial2 to construct compound criteria.
      criteria1 - "=" to find blank fields, "<>" to find non-blank fields. If null, means ALL. If filterOp == AutoFilter#FILTEROP_TOP10, then this shall specifies the number of items (e.g. "10").
      criteria2 - 2nd criteria; used with criteria1 and filterOP to construct compound criteria.
      showButton - true to show the autoFilter drop-down arrow for the filtered field; false to hide the autoFilter drop-down arrow; null to keep as is.
      Returns:
      the applied AutoFiltering

    • enableAutoFilter

      SAutoFilter enableAutoFilter(boolean enable)
      Enable the auto filter and return it, get null if you disable it.
      Returns:
      the autofilter if enable, or null if disable.

    • resetAutoFilter

      void resetAutoFilter()
      Reset the autofilter, clear the condition, shows all the hidden row

    • applyAutoFilter

      void applyAutoFilter()
      Apply the autofilter with the old condition and current cell values

    • setHidden

      void setHidden(boolean hidden)
      Sets whether this rows or columns are hidden(useful only if this Range cover entire column or entire row)
      Parameters:
      hidden - true to hide this rows or columns

    • setDisplayGridlines

      void setDisplayGridlines(boolean show)
      Sets whether show the gridlines of the sheets in this Range.
      Parameters:
      show - true to show the gridlines; false to not show the gridlines.

    • setHyperlink

      void setHyperlink(SHyperlink.HyperlinkType linkType, String address, String display)
      Sets the hyperlink of this Range
      Parameters:
      linkType - the type of target to link. One of the SHyperlink.HyperlinkType.URL, SHyperlink.HyperlinkType.DOCUMENT, SHyperlink.HyperlinkType.EMAIL, SHyperlink.HyperlinkType.FILE
      address - the address
      display - the text to display link

    • getColumns

      SRange getColumns()
      Returns a SRange that represent columns of the 1st selected area of this Range. Note that only the 1st selected area is considered if this Range is a multiple-selected Range.
      Returns:
      a SRange that represent columns of this Range and contains all rows of the column.

    • getRows

      SRange getRows()
      Returns a SRange that represent rows of the 1st selected area of this Range. Note that only the 1st selected area is considered if this Range is a multiple-selected Range.
      Returns:
      a SRange that represent rows of this Range and contains all columns of the rows.

    • getRow

      int getRow()
      Returns the number of the 1st row of the 1st area in this Range(0-based; i.e. row1 return 0)
      Returns:
      the number of the 1st row of the 1st area in this Range(0-based; i.e. row1 return 0)

    • getColumn

      int getColumn()
      Returns the number of the 1st column of the 1st area in this Range(0-based; i.e. Column A return 0)
      Returns:
      the number of the 1st column of the 1st area in this Range(0-based; i.e. Column A return 0)

    • getLastRow

      int getLastRow()
      Returns the number of the last row of the 1st area in this Range(0-based; i.e. row1 return 0)
      Returns:
      the number of the last row of the 1st area in this Range(0-based; i.e. row1 return 0)

    • getLastColumn

      int getLastColumn()
      Returns the number of the last column of the 1st area in this Range(0-based; i.e. Column A return 0)
      Returns:
      the number of the last column of the 1st area in this Range(0-based; i.e. Column A return 0)

    • setValue

      void setValue(Object value)
      Set value into this Range.
      Parameters:
      value - the value

    • setValues

      void setValues(Object... values)
      Set values into this Range from left to right and top to bottom consistently.
      Parameters:
      values - the values
      Since:
      5.5.0

    • getValue

      Object getValue()
      Returns left top cell value of this Range.
      Returns:
      left top cell value of this Range

    • getValues

      List<Object> getValues()
      Returns all cell values from left to right and top to bottom of this Range in one dimension list.
      Returns:
      all cell values of this Range.

    • getOffset

      SRange getOffset(int rowOffset, int colOffset)
      Returns a SRange that represents a range that offset from this Range.
      Parameters:
      rowOffset - positive means downward; 0 means don't change row; negative means upward.
      colOffset - positive means rightward; 0 means don't change column; negative means leftward.
      Returns:
      a SRange that represents a range that offset from this Range.

    • addChart

      SChart addChart(ViewAnchor anchor, SChart.ChartType type, SChart.ChartGrouping grouping, SChart.ChartLegendPosition pos, boolean isThreeD)
      Add a chart into the sheet of this Range
      Parameters:
      anchor -
      type -
      grouping -
      pos -
      isThreeD -
      Returns:
      the created chart

    • addChart

      SChart addChart(String name, ViewAnchor anchor, SChart.ChartType type, SChart.ChartGrouping grouping, SChart.ChartLegendPosition pos, boolean isThreeD)
      Add a chart into the sheet of this Range
      Parameters:
      name -
      anchor -
      type -
      grouping -
      pos -
      isThreeD -
      Returns:
      the created chart

    • addPicture

      SPicture addPicture(ViewAnchor anchor, byte[] image, SPicture.Format format)
      Add a picture into the sheet of this Range
      Returns:
      the created picture

    • deletePicture

      void deletePicture(SPicture picture)
      Delete an existing picture from the sheet of this Range.
      Parameters:
      picture - the picture to be deleted

    • movePicture

      void movePicture(SPicture picture, ViewAnchor anchor)
      Update picture anchor. Can be used to resize or move a picture.
      Parameters:
      picture - the picture to change
      anchor - the new anchor

    • moveChart

      void moveChart(SChart chart, ViewAnchor anchor)
      Move the chart to the new anchor.
      Parameters:
      chart - the chart to change anchor
      anchor - the new anchor

    • updateChart

      void updateChart(SChart chart)
      Notify the model that a chart contains change, for example, chart data changes.
      Parameters:
      chart - the chart that changes

    • deleteChart

      void deleteChart(SChart chart)
      Delete an existing chart from the sheet of this Range.
      Parameters:
      chart - the chart to be deleted

    • validate

      SDataValidation validate(String txt)
      Returns whether the plain text input by the end user is valid or not; note the validation only applies to the left-top cell of this Range.
      Parameters:
      txt - the string input by the end user.
      Returns:
      null if a valid input to the specified range; otherwise, the DataValidation

    • isAnyCellProtected

      boolean isAnyCellProtected()
      Returns whether any cell is protected and locked in this Range.
      Returns:
      true if any cell is protected and locked in this Range.

    • notifyCustomEvent

      void notifyCustomEvent(String customEventName, Object data, boolean writeLock)
      Send a custom model event to all book's listener, the event name must not conflict with that in ModelEvents
      Parameters:
      customEventName - the event custom event
      data - the data
      writeLock - use write lock when notify , set true if the synchronized book listener will modify the book.

    • deleteSheet

      void deleteSheet()
      Delete sheet of this Range.

    • createSheet

      SSheet createSheet(String name)
      Create sheet of this book as specified in this Range.
      Parameters:
      name - the name of the new created sheet; null would use default "SheetX" name where X is the next sheet number.

    • cloneSheet

      SSheet cloneSheet(String name)
      Clone sheet as specified in this Range.
      Parameters:
      name - the name of the new created sheet; null would use default "SheetX" name where X is the next sheet number.

    • setSheetName

      void setSheetName(String name)
      Set(Rename) the name of the sheet as specified in this Range.
      Parameters:
      name -

    • setSheetOrder

      void setSheetOrder(int pos)
      Sets the order of the sheet as specified in this Range.
      Parameters:
      pos - the position that we want to insert the sheet into (0 based)

    • isWholeRow

      boolean isWholeRow()
      Check if this range cover an entire rows (form 0, and last row to the max available row of a sheet)

    • isWholeColumn

      boolean isWholeColumn()
      Check if this range cover an entire columns (form 0, and last row to the max available column of a sheet)

    • isWholeSheet

      boolean isWholeSheet()
      Check if this range cover an entire sheet

    • notifyChange

      void notifyChange()
      Notify this range has been changed.

    • notifyChange

      void notifyChange(String[] variables)
      Notify the variables in this range has been changed.
      Parameters:
      variables -

    • setFreezePanel

      void setFreezePanel(int numOfRow, int numOfColumn)
      Set the freeze panel
      Parameters:
      numOfRow - the number of row to freeze, 0 means no freeze
      numOfColumn - the number of column to freeze, 0 means no freeze

    • getCellFormatText

      String getCellFormatText()
      Gets the first(top-left) cell's formatted text, if the cell's format is the special LOCALE aware format (such as m/d/yyyy), it will formats the value by transferred format (e.g m/d/yyyy will transfer to yyyy/m/d in TW locale)
      Returns:

    • getCellDataFormat

      String getCellDataFormat()
      Gets the first(top-left) cell's format, if the cell's format is the special LOCALE aware format (such as m/d/yyyy), it transfer the format by LOCALE(e.g m/d/yyyy will transfer to yyyy/m/d in TW locale)
      Returns:

    • getCellStyle

      SCellStyle getCellStyle()
      Gets the first(top-left) cell's style
      Returns:

    • isProtected

      boolean isProtected()
      Gets the first region's protection status; return true if the sheet of the first region is protected and some cells in the region is locked.

    • isSheetProtected

      boolean isSheetProtected()
      Gets whether the sheet of the first region of this Range is protected.
      Returns:

    • clearAll

      void clearAll()
      Clear data contains, style and unmerge this range

    • createName

      void createName(String nameName)
      Create a SName that refer to this range.
      Parameters:
      nameName - name of the SName that you can refer in formulas.

    • protectSheet

      void protectSheet(String password, boolean allowSelectingLockedCells, boolean allowSelectingUnlockedCells, boolean allowFormattingCells, boolean allowFormattingColumns, boolean allowFormattingRows, boolean allowInsertColumns, boolean allowInsertRows, boolean allowInsertingHyperlinks, boolean allowDeletingColumns, boolean allowDeletingRows, boolean allowSorting, boolean allowFiltering, boolean allowUsingPivotTables, boolean drawingObjects, boolean scenarios)
      Protect a SSheet so that it cannot be modified.
      Parameters:
      password - a case-sensitive password for the sheet; null means sheet is not password protected.
      allowSelectingLockedCells - true to allow select locked cells; default to true.
      allowSelectingUnlockedCells - true to allow select unlocked cells; default to true.
      allowFormattingCells - true to allow user to format any cell on the protected sheet; default false.
      allowFormattingColumns - true to allow user to format any columns on the protected sheet; default false.
      allowFormattingRows - true to allow user to format any rows on the protected sheet; default false.
      allowInsertColumns - true to allow user to insert columns on the protected sheet; default false.
      allowInsertRows - true to allow user to insert rows on the protected sheet; default false.
      allowInsertingHyperlinks - true to allow user to insert hyperlinks on the protected sheet; default false.
      allowDeletingColumns - true to allow user to delete columns on the protected sheet; default false.
      allowDeletingRows - true to allow user to delete rows on the protected sheet; default false.
      allowSorting - true to allow user to sort on the protected sheet; default false.
      allowFiltering - true to allow user to set filters on the protected sheet; default false.
      allowUsingPivotTables - true to allow user to use pivot table reports on the protected sheet; default false.
      drawingObjects - true to protect objects; default to false.
      scenarios - true to protect scenarios; default to true.

    • unprotectSheet

      boolean unprotectSheet(String password)
      Removes protection from a sheet. This method has no effect if the sheet isn't protected.
      Parameters:
      password - a case-sensitive password used to unprotect the sheet. If the sheet isn't protected with a password, this argument is ignored. If you omit this argument for a sheet that is protected with a password, you'll be prompted for the password.

    • getSheetProtection

      SSheetProtection getSheetProtection()
      Gets SSheetProtection protection options that tells what are allowed operations for the protected sheet of the first region of this range.
      Returns:

    • setValidation

      void setValidation(SDataValidation.ValidationType validationType, boolean ignoreBlank, SDataValidation.OperatorType operatorType, boolean inCellDropDown, String formula1, String formula2, boolean showInput, String inputTitle, String inputMessage, boolean showError, SDataValidation.AlertStyle alertStyle, String errorTitle, String errorMessage)
      Add if not exist or modify an existing SDataValidation to this range.
      Parameters:
      validationType - the type of this validation
      ignoreBlank - true if blank values are permitted.
      operatorType - the operator for this validation
      inCellDropDown - true if want to display dropdown list for acceptable values.
      formula1 - the value or expression associated with conditional format or data validation.
      formula2 - the 2nd part of a conditional format or data validation. Useful only when operatorType is BETWEEN or NOT_BETWEEN.
      showInput - true to show the input message.
      inputTitle - title for the data-validation input dialog box.
      inputMessage - message for the data-validation input dialog box.
      showError - true to show the error message.
      alertStyle - validation alert style.
      errorTitle - title of the data validation error dialog.
      errorMessage - data validation error message.

    • getValidations

      List<SDataValidation> getValidations()
      Gets SDataValidations associated with this range; if more than one validation is present, will return at most two.
      See Also:

    • deleteValidation

      void deleteValidation()
      Delete the SDataValidation associated in the specified range.

    • getOrCreateFont

      SFont getOrCreateFont(SFont.Boldweight boldweight, String htmlColor, int fontHeight, String fontName, boolean italic, boolean strikeout, SFont.TypeOffset typeOffset, SFont.Underline underline)
      Get font if exists or create font if not exists from the book of this range and return it.
      Returns:
      font of the specified font metrics
      Since:
      3.6.0

    • refresh

      void refresh(boolean includeDependants)
      Evaluate(if not cached), update data model, and refresh UI of this range and its dependent cells if the includeDependents is true.
      Since:
      3.6.0

    • setAutoRefresh

      boolean setAutoRefresh(boolean auto)
      Turn on(true)/off(false) of auto refresh of this range and return previous on/off status; default is true.
      Parameters:
      auto - whether refresh automatically
      Returns:
      previous status
      Since:
      3.6.0

    • refresh

      void refresh(boolean includeDependents, boolean clearCache, boolean enforceEval)
      Update data model and refresh UI of this range and its dependent cells if the argument includeDependents is true. Note that when you set parameter clearCache to true, the cached formula result in data model will be cleared first. If you set parameter enforceEval to true, data model associated with this range will be evaluated immediately; otherwise will be evaluated on demand.
      Since:
      3.7.0

    • setSheetVisible

      void setSheetVisible(SRange.SheetVisible visible)
      Set Sheet visibility; can be SheetVisible.VISIBLE, SheetVisible.HIDDEN, and SheetVisible.VERY_HIDDEN.
      • VISIBLE: the sheet is visible
      • HIDDEN: the sheet is hidden but can be unhidden using UI
      • VERY_HIDDEN: the sheet is hidden but can be unhidden only via this API.
      Since:
      3.7.0
      See Also:

    • getCommentRichText

      String getCommentRichText()
      Return the comment rich edit text of the left top cell of this Range.
      Returns:
      the rich edit text of this Range.
      Since:
      3.7.0

    • setCommentRichText

      void setCommentRichText(String html)
      Set comment rich text into the left top cell of this range; null to delete it.
      Since:
      3.7.0

    • setCommentVisible

      void setCommentVisible(boolean visible)
      Set comment visibility into the left top cell of this range; if no comment at the cell, it simply ignored.
      Parameters:
      visible -
      Since:
      3.7.0

    • isCommentVisible

      boolean isCommentVisible()
      Returns whether the comment is always visible at the left top cell of this range; if no comment at the cell, it returns false.
      Returns:
      Since:
      3.7.0

    • notifyChange

      void notifyChange(CellAttribute cellAttr)
      Notify this range has been changed with the specified attribute.
      Since:
      3.8.0

    • setNameName

      void setNameName(String namename, String newname)
      Set(Rename) the name of the Name(or Table) as specified in this Range(a Book or a Sheet).
      Parameters:
      namename - name of the Name(or Table)
      newname - new name for the Name(or Table)
      Since:
      3.8.0

    • setStringValue

      void setStringValue(String value)
      Save the specified value into this range as a String no matter the value is prefixed with '=' or not.
      Parameters:
      value -
      Since:
      3.8.0

    • getMergedRegion

      CellRegion getMergedRegion()
      Returns the merged region of the left top cell of this Range if any; otherwise, returns null if not a merged region.
      Returns:
      the merged region of the left top cell of this Range if any
      Since:
      3.8.3

    • getDataRegion

      CellRegion getDataRegion()
      Returns the region which contains data(including chart, picture, and fills) in the sheet of this Range; return null if empty sheet.
      Returns:
      the region which contains data(including chart, picture, and fills) in the sheet of this Range; return null if empty sheet.
      Since:
      3.8.3

    • cloneSheetFrom

      SSheet cloneSheetFrom(String name, SSheet sheet)
      Clone from the specified source sheet to the owner book of this range. The book can be different between the owner book of this range and of the specified source sheet.
      Parameters:
      name - the name of the new created sheet; null would try to use the sheet name of the specified source sheet; if the same sheet name already used in the owner book of this range then use default "SheetX" name where X is the next sheet number of the owner book of this range.
      sheet - the source sheet to clone from to the owner book of this range.
      Returns:
      the new created sheet
      Since:
      3.9.0
      See Also:

    • cloneSheetFrom

      SSheet cloneSheetFrom(String name, SSheet sheet, boolean valueOnly)
      Clone from the specified source sheet to the owner book of this range. The book can be different between the owner book of this range and of the specified source sheet.
      Parameters:
      name - the name of the new created sheet; null would try to use the sheet name of the specified source sheet; if the same sheet name already used in the owner book of this range then use default "SheetX" name where X is the next sheet number of the owner book of this range.
      sheet - the source sheet to clone from to the owner book of this range.
      valueOnly - true to copy cell value only
      Returns:
      the new created sheet
      Since:
      6.0.0

    • getDirectPrecedents

      Set<SRange> getDirectPrecedents()
      Returns Range(s) that are the direct precedents of this cell Range. If this Range covers more than one cell, the left-top one is used.
      Returns:
      the direct precedents
      Since:
      5.6.0

    • getPrecedents

      Set<SRange> getPrecedents()
      Returns all Range(s) that are the direct or indirect precedents of this cell Range. If this Range covers more than one cell, the left-top one is used.
      Returns:
      all direct or indirect precedents
      Since:
      5.6.0

    • getDirectDependents

      Set<SRange> getDirectDependents()
      Returns Range(s) that are the direct dependents of this cell Range. If this Range covers more than one cell, the left-top one is used.
      Returns:
      the direct dependents
      Since:
      5.6.0

    • getDependents

      Set<SRange> getDependents()
      Returns all Range(s) that are the direct or indirect dependents of this cell Range. If this Range covers more than one cell, the left-top one is used.
      Returns:
      all direct or indirect dependents
      Since:
      5.6.0

    • getBookSeries

      SBookSeries getBookSeries()
      Returns the associated SBookSeries of this range.
      Returns:
      the associated BookSeries
      Since:
      5.6.0

    • getBook

      SBook getBook()
      Returns the associated SBook of this range.
      Returns:
      the associaed Book
      Since:
      5.6.0

    • tracePrecedents

      void tracePrecedents()
      Trace the dependents of this range.
      Since:
      5.6.0

    • traceDependents

      void traceDependents()
      Trace the precedent of this range.
      Since:
      5.6.0

    • clearTrace

      void clearTrace()
      Clears the tracing of this range.
      Since:
      5.6.0

    • getRowGroups

      List<SRange> getRowGroups()
      Returns all group ranges for rows, which intersect with this range.
      Returns:
      an empty list if not matched.
      Since:
      6.0.0

    • getRowGroups

      List<SRange> getRowGroups(int outlineLevel)
      Returns all group ranges matched the given outline level for rows, which intersect with this range.
      Parameters:
      outlineLevel - a valid value in a range is from 1 to 7 (inclusive).
      Returns:
      an empty list if not matched.
      Since:
      6.0.0

    • getRowGroups

      List<SRange> getRowGroups(int fromOutlineLevel, int toOutlineLevel)
      Returns all group ranges matched between fromOutlineLevel and toOutlineLevel for rows, which intersect with this range.
      Parameters:
      fromOutlineLevel - 1~7 (inclusive)
      toOutlineLevel - 2~8 (exclusive)
      Returns:
      an empty list if not matched.
      Since:
      6.0.0

    • getColumnGroups

      List<SRange> getColumnGroups()
      Returns all group ranges for columns, which intersect with this range.
      Returns:
      an empty list if not matched.
      Since:
      6.0.0

    • getColumnGroups

      List<SRange> getColumnGroups(int outlineLevel)
      Returns all group ranges matched the given outline level for columns, which intersect with this range.
      Parameters:
      outlineLevel - a valid value in a range is from 1 to 7 (inclusive).
      Returns:
      an empty list if not matched.
      Since:
      6.0.0

    • getColumnGroups

      List<SRange> getColumnGroups(int fromOutlineLevel, int toOutlineLevel)
      Returns all group ranges matched between fromOutlineLevel and toOutlineLevel for columns, which intersect with this range.
      Parameters:
      fromOutlineLevel - 1~7 (inclusive)
      toOutlineLevel - 2~8 (exclusive)
      Returns:
      an empty list if not matched.
      Since:
      6.0.0

    • setSummaryBelow

      void setSummaryBelow(boolean summaryBelow)
      Sets to be true to display summary group as below or to be false to display summary group as above for rows.

      Note: One setting to affect whole sheet, if the value is up-side-down against the previous value, it will clear all outline level for rows and columns.

      Default: true

      Parameters:
      summaryBelow - true to display as below for rows.
      Since:
      6.0.0

    • isSummaryBelow

      boolean isSummaryBelow()
      Returns whether to display group summary as below for rows.

      Default: true

      Since:
      6.0.0

    • setSummaryRight

      void setSummaryRight(boolean summaryRight)
      Sets to be true to display summary group as right or to be false to display summary group as left for columns.

      Note: One setting to affect whole sheet, if the value is up-side-down against the previous value, it will clear all outline level for rows and columns.

      Default: true

      Parameters:
      summaryRight - true to display as right for columns.
      Since:
      6.0.0

    • isSummaryRight

      boolean isSummaryRight()
      Returns whether to display group summary as right for columns.

      Default: true

      Since:
      6.0.0

    • collapse

      void collapse()
      Collapses one group by matching with the 1st selected area of this Range in rows or columns. (not affected its descendant).
      Since:
      6.0.0

    • expand

      void expand()
      Expands one group by matching with the 1st selected area of this Range in rows or columns. (not affected its descendant).
      Since:
      6.0.0

    • clearOutlineLevel

      void clearOutlineLevel()
      Clears all outline level for all groups that intersect with the range. 2:4 for rows and C:E for columns

    • isCollapsed

      boolean isCollapsed()
      Returns whether the group by matching with the 1st selected area of this Range in rows or columns, which has collapsed or not. Otherwise, returns false instead.
      Since:
      6.0.0

    • getOutlineLevel

      int getOutlineLevel()
      Returns the outline level of the group by matching with the 1st selected area of this Range in rows or columns. Otherwise, returns 0 instead.
      Since:
      6.0.0

    • group

      void group()
      Groups the rows or columns by matching the range, which increases their outline level.

      Note: The maximum level is up to 7.

      Since:
      6.0.0

    • ungroup

      void ungroup()
      Ungroups the rows or columns by matching the range, which decreases their outline level.

      Note: The minimum level is down to 0.

      Since:
      6.0.0