Package io.keikai.axyra.sheets

Class Sheet

java.lang.Object
io.keikai.axyra.sheets.Sheet
public final class Sheet extends Object
A worksheet — a lightweight view bound to one tab of a Workbook (it follows the tab when other tabs are inserted, moved or deleted). Holds no native resource; all work goes through the owning Workbook's handle.

Use range(int, int, int, int) for bulk cell access (Range crosses JNI once per rectangle). value(int, int) is a single-cell convenience.

  • Method Summary

    Modifier and Type
    Method
    Description
    String
    activeCell()
    The sheet view's active cell as an A1 reference (<sheetView><selection activeCell>, ECMA-376 §18.3.1.78), or null when the sheet carries no selection at all.
    int
    addChart(Chart chart)
    Add a chart to this sheet; returns the new chart's index.
    int
    addCheckbox(String name, int fromRow, int fromColumn, int toRow, int toColumn, String linkedCell)
    Add a checkbox form control anchored to a two-cell rectangle, optionally bound to a linked cell (A1 ref) reflecting its state.
    void
    addColumnPageBreak(int column)
    Insert a manual page break before column (vertical break).
    int
    addConnector(String preset, int fromRow, int fromCol, int toRow, int toCol)
    Add a connector shape (<xdr:cxnSp>) with the given preset geometry name (e.g.
    int
    addFormControl(FormControl control)
    Add a form control (check box, option button, button, combo box, list box, scroll bar, spin button, edit box, label, group box); returns its index in formControls().
    int
    addLinkedPicture(String target, String format, int r1, int c1, int r2, int c2)
    Add a linked picture over the rectangle (r1,c1)..(r2,c2): the image is referenced by an external target (URL or path) via <a:blip r:link> instead of embedding bytes (ECMA-376 Part 1 §20.1.8.13).
    int
    addPicture(byte[] imageData, String format, int fromRow, int fromColumn, int toRow, int toColumn)
    Insert an image anchored to a two-cell rectangle (0-based cells).
    int
    addPicture(byte[] imageData, String format, int fromRow, int fromColumn, int fromRowOffset, int fromColumnOffset, int toRow, int toColumn, int toRowOffset, int toColumnOffset)
    Insert an image with a full two-cell anchor including EMU offsets.
    int
    addPivotChart(int pivotIndex, String chartType, int fromRow, int fromCol, int toRow, int toCol)
    Add a PivotChart bound to the pivot table at pivotIndex on this sheet, anchored over the given cell rectangle.
    int
    addPivotTable(String name, String location, String sourceRef)
    Create a pivot table at location (A1 anchor) over a source range; returns its index.
    void
    addProtectedRange(String name, String sqref)
    Adds an ungated allow-edit-range.
    void
    addProtectedRange(String name, String sqref, String password)
    Adds an allow-users-to-edit-range (protectedRange — ECMA-376 Part 1 §18.3.1.72): the named range sqref stays editable while the sheet is protected.
    void
    addRowPageBreak(int row)
    Insert a manual page break before row (horizontal break).
    int
    addScenario(String name, String[] cellRefs, String[] values)
    Add a what-if scenario; returns its index.
    int
    addShape(String shapeType, String text, int fromRow, int fromCol, int toRow, int toCol)
    Add a drawing shape (e.g.
    int
    addSparkline(String type, String dataRef, String locationRef)
    Add a sparkline group ("line", "column", or "stacked") that draws dataRef (e.g.
    int
    addTextBox(String text, int fromRow, int fromCol, int toRow, int toCol)
    Add a text box (a rect shape carrying text); returns the new shape's index.
    boolean
    anchorOleObject(int objectIndex, byte[] iconBytes, String iconFormat, int fromRow, int fromCol, int toRow, int toCol)
    Display the workbook-level embedded OLE object at objectIndex (see Workbook.addOleObject(java.lang.String, java.lang.String, byte[])) as an icon on this sheet, anchored over the cell rectangle (fromRow, fromCol)–(toRow, toCol) (0-based, exclusive bottom-right edge like a drawing anchor).
    int
    applyAdvancedFilter(Range listRange, Range criteriaRange, boolean uniqueOnly)
    Run an advanced filter (Excel's Data > Advanced) over listRange in place, hiding the data rows that do not match criteriaRange.
    int
    applyAdvancedFilterCopyTo(Range listRange, Range criteriaRange, Range destination, boolean uniqueOnly)
    Advanced filter in "Copy to another location" mode: instead of hiding source rows, writes the list header plus each matching row (see applyAdvancedFilter(Range, Range, boolean) for the criteria semantics) starting at the top-left cell of destination.
    int
    applyAutoFilter()
    Execute the auto-filter: hides every data row failing any column's criteria and shows the rest.
    boolean
    autoExpandTables(int row, int col, String typedText)
    Apply Excel's type-adjacent table auto-expansion for a data entry at (row, col): typing one row below a table's last data row (inside its column span, no totals row) grows it by one row; typing in the header row one column right of its last column grows it by one column named typedText — unless another table occupies the candidate column.
    Range
    autoFilterRange()
    The filtered block, or null when this sheet has no autofilter.
    void
    autoFitColumn(int col)
    Auto-fit a column's width to its widest cell value.
    void
    autoFitRow(int row)
    Auto-fit a row's height from the default font size.
    byte[]
    backgroundImage()
    The raw bytes of the sheet background image, or null when none.
    String
    backgroundImageFormat()
    The format token (png/jpeg/…) of the sheet background image, or null when none.
    int
    baseColumnWidth()
    The declared baseColWidth basis in characters, or 0 when the sheet does not declare one (the spec default of 8 applies).
    Cell
    cell(int row, int col)
    A single-cell view at (row, col) (0-based).
    ChartView
    chart(int chartIndex)
    A live view of the chart at chartIndex (its position in charts()), with read-back getters and setters that apply immediately.
    List<Chart>
    charts()
    All charts on this sheet.
    void
    clearAutoFilter()
    Remove any auto-filter.
    boolean
    clearBackgroundImage()
    Remove the sheet background image; returns whether one existed.
    void
    clearCharts()
    Remove all charts from this sheet.
    void
    clearColumnFilter(int columnIndex)
    Remove the filter from a single column.
    void
    clearConditionalFormats()
    Remove all conditional-formatting rules from this sheet.
    void
    clearPageBreaks()
    Remove all manual page breaks.
    void
    clearPaperSize()
    Remove the explicit paper-size declaration, so the saved sheet omits the paperSize attribute and consumers use their printer default.
    void
    clearPictures()
    Remove all pictures from this sheet.
    void
    clearValidations()
    Remove all data-validation rules from this sheet.
    int[]
    columnPageBreaks()
    The manual vertical page-break columns.
    CellStyle
    columnStyle(int col)
    The style applied to the entire column — the default for cells in the column that carry no cell-level style (<col style>).
    int
    columnStyleId(int col)
    The column-level style id (an engine-internal dedup index, matching Range.styleIds()), or 0 when the column carries no column-level style.
    double
    columnWidth(int col)
    A column's width in character units.
    List<ConditionalFormat>
    conditionalFormats()
    All conditional-formatting rules on this sheet.
    int[]
    consolidate(int destRow, int destColumn, ConsolidateFunction function, Range... sources)
    Consolidate several equally-shaped source ranges (possibly on other sheets) into this sheet at (destRow, destColumn) using function, aggregating by position.
    boolean
    convertTableToRange(String name)
    Convert the named table back to an ordinary range (Excel's Table Design > Convert to Range): drops the table definition while keeping every cell value in place.
    double
    defaultColumnWidth()
    The sheet's explicit default column width in character units, or 0 when none is declared — column widths then derive from baseColumnWidth().
    double
    defaultRowHeight()
    The sheet's default row height in points — the height of every row without an explicit setRowHeight(int, double) override.
    void
    deleteColumns(int startCol, int count)
    Delete count columns starting at startCol.
    void
    deleteRows(int startRow, int count)
    Delete count rows starting at startRow.
    boolean
    differentFirst()
    Whether the first printed page uses its own header/footer (ECMA-376 §18.3.1.46 differentFirst).
    boolean
    differentOddEven()
    Whether odd and even printed pages use distinct headers/footers (ECMA-376 §18.3.1.46 differentOddEven).
    double
    dyDescent()
    The sheet-level x14ac:dyDescent text-descent hint on <sheetFormatPr>, or 0 when absent.
    String
    evenFooter()
    The even-page footer text, or null (only used when differentOddEven()).
    String
    evenHeader()
    The even-page header text, or null (only used when differentOddEven()).
    int[][]
    find(String text)
    Find all cells whose text matches, as {row, col} pairs.
    int[][]
    find(String text, boolean caseSensitive, boolean matchEntire, boolean wildcard)
    Find with options.
    int[][]
    find(String text, boolean caseSensitive, boolean matchEntire, boolean wildcard, FindFormat format)
    find(String, FindFormat) with the full option set.
    int[][]
    find(String text, FindFormat format)
    Find restricted to cells whose resolved style matches format (Excel's search-by-format) — see FindFormat for the matching semantics.
    int[][]
    findRegex(String pattern)
    Find all cells whose text matches the regular expression pattern (case-insensitive), as {row, col} pairs.
    int[][]
    findRegex(String pattern, boolean caseSensitive)
    findRegex(String) with explicit case sensitivity.
    String
    firstFooter()
    The first-page footer text, or null (only used when differentFirst()).
    String
    firstHeader()
    The first-page header text, or null (only used when differentFirst()).
    int
    firstPageNumber()
    The number printed on the first page, or 0 when unset.
    int
    fitToHeight()
    Pages tall the printout is fitted to (0 = automatic / unlimited); only meaningful when isFitToPage().
    void
    fitToPage(int width, int height)
    Fit the printout to width pages wide by height tall.
    int
    fitToWidth()
    Pages wide the printout is fitted to (0 = automatic / unlimited); only meaningful when isFitToPage().
    String
    footer()
    The page footer text, or null.
    int[]
    formattedColumns()
    The 0-based indexes (ascending) of columns carrying explicit column-level metadata — width, hidden flag, column style or outline.
    int[]
    formattedRows()
    0-based indexes of the rows carrying explicit row-level metadata — a custom height, a hidden flag, or a row style — the row analogue of formattedColumns().
    int
    formControlCount()
     
    List<FormControl>
    formControls()
    All form controls on this sheet, in z-order.
    int
    freezeColumn()
    The frozen column split (columns left are frozen); 0 if none.
    void
    freezePanes(int freezeRow, int freezeCol)
    Freeze rows above freezeRow and columns left of freezeCol.
    int
    freezeRow()
    The frozen row split (rows above are frozen); 0 if none.
    void
    groupColumns(int startCol, int endCol)
    Group columns [startCol, endCol] at outline level 1.
    void
    groupRows(int startRow, int endRow)
    Group rows [startRow, endRow] at outline level 1.
    int
    groupShapes(String name, int... shapeIndexes)
    Group existing shapes into one <xdr:grpSp> container (Excel's "Group").
    boolean
    hasAutoFilter()
     
    boolean
    hasPageSetup()
    Whether the sheet carries a <pageSetup> element (ECMA-376 §18.3.1.63).
    String
    header()
    The page header text (Excel codes like &C, &P allowed), or null.
    byte[]
    headerFooterPictureData(String section)
    The image bytes of the header/footer picture in section, or null.
    <T> int
    importData(int startRow, int startCol, List<T> items)
    Import a collection with default options (header row on, all properties).
    <T> int
    importData(int startRow, int startCol, List<T> items, ImportOptions options)
    Import a collection of Java objects into a range.
    int
    index()
    The 0-based index of this sheet in its workbook — its position NOW.
    void
    insertColumns(int startCol, int count)
    Insert count blank columns before startCol.
    void
    insertRows(int startRow, int count)
    Insert count blank rows before startRow.
    boolean
    isColumnHidden(int col)
     
    boolean
    isColumnWidthCustom(int col)
    Whether the column's width was explicitly authored (via setColumnWidth(int, double) or a <col width> in the source file), as opposed to inheriting the sheet default.
    boolean
    isDefaultRowHeightCustom()
    Whether the default row height is flagged as an explicit, honoured value (the sheetFormatPr customHeight flag).
    boolean
    isFitToPage()
    Whether fit-to-page scaling is active (set by fitToPage(int, int)); when false the sheet prints at pageScale().
    boolean
    isLandscape()
     
    boolean
    isPaperSizeDeclared()
    Whether this sheet explicitly declares a paper size.
    boolean
    isProtected()
    Whether this sheet is protected.
    boolean
    isProtectedWithPassword()
    Whether the sheet's protection carries a password.
    boolean
    isRowHeightCustom(int row)
    Whether the row's height was explicitly authored (via setRowHeight(int, double) or a <row ht> in the source file).
    boolean
    isRowHidden(int row)
     
    List<Range>
    mergedRegions()
    The merged-cell regions on this sheet.
    String
    name()
    The sheet's display name.
    PageMargins
    pageMargins()
    The page margins in inches.
    boolean
    pageOrderOverThenDown()
    Whether pages print over-then-down.
    int
    pageScale()
    The print scale percentage (100 = no scaling).
    int
    paperSize()
    The paper size as its ECMA-376 numeric code (9 = A4 by default).
    int[]
    pictureAnchor(int pictureIndex)
    {fromRow, fromCol, toRow, toCol} anchor of the picture, or an empty array.
    int[]
    pictureAnchorFull(int pictureIndex)
    {fromRow, fromCol, fromRowOffset, fromColOffset, toRow, toCol, toRowOffset, toColOffset} anchor of the picture (EMU offsets included), or an empty array.
    int
    pictureCount()
    Number of pictures on this sheet.
    byte[]
    pictureData(int pictureIndex)
    The raw image bytes of the picture at pictureIndex, or null.
    String
    pictureFormat(int pictureIndex)
    The format token (png/jpeg/…) of the picture at pictureIndex, or null.
    String
    pictureLinkTarget(int pictureIndex)
    The external link target of the picture at pictureIndex, or null when it is an ordinary embedded picture.
    int
    pivotCount()
     
    String
    pivotLocation(int pivotIndex)
    The destination location (e.g.
    String
    pivotName(int pivotIndex)
     
    String
    pivotSource(int pivotIndex)
    The source data reference of the pivot table at pivotIndex.
    PivotTableView
    pivotTable(int pivotIndex)
    A live view of the pivot table at pivotIndex: field areas (row / column / filter / values), aggregation functions, layout, grand totals, and PivotTableView.refresh().
    PivotTableView
    pivotTable(String name)
    A live view of the pivot table named name (exact match first, then case-insensitive).
    String
    printArea()
     
    boolean
    printBlackAndWhite()
    Whether the sheet prints without colour.
    int
    printComments()
    Where cell comments print, as the same code setPrintComments(int) takes.
    boolean
    printDraft()
    Whether the sheet prints in draft quality.
    int
    printErrors()
    How error cells print, as the same code setPrintErrors(int) takes.
    boolean
    printGridlines()
    Whether gridlines are printed (ECMA-376 §18.3.1.65 printOptions/gridLines).
    boolean
    printHeadings()
    Whether row and column headings are printed.
    boolean
    printHorizontallyCentered()
    Whether printed output is centered horizontally on the page (<printOptions horizontalCentered>, ECMA-376 §18.3.1.70).
    int
    printResolution()
    The printer resolution in DPI.
    String
    printTitleColumns()
     
    String
    printTitleRows()
     
    boolean
    printVerticallyCentered()
    Whether printed output is centered vertically on the page (<printOptions verticalCentered>, ECMA-376 §18.3.1.70).
    void
    protect()
    Enable sheet protection (Excel-default allowances).
    void
    protect(String password)
    Enable sheet protection with a password (ISO Write Protection hash, SHA-512 + 100,000 spins per [MS-OFFCRYPTO] §2.4.2.2) and Excel's default allowances.
    void
    protect(String password, SheetProtection options)
    Enable sheet protection with explicit ECMA-376 §18.3.1.85 options and an optional password (null = none).
    List<ProtectedRange>
    protectedRanges()
    The sheet's allow-edit-ranges, in definition order.
    SheetProtection
    protection()
    The protection options (allow semantics), or null when this sheet is not protected.
    Range
    range(int r1, int c1, int r2, int c2)
    A range over the inclusive rectangle (r1,c1)..(r2,c2), 0-based.
    Range
    range(String a1)
    A range parsed from A1 notation, e.g.
    boolean
    removeChart(int chartIndex)
    Remove the chart at chartIndex (its position in charts()); returns whether it existed.
    boolean
    removeConditionalFormat(int formatIndex)
    Remove the conditional-formatting rule at formatIndex (its position in conditionalFormats()); returns whether it existed.
    boolean
    removeFormControl(int controlIndex)
    Remove the form control at controlIndex (its position in formControls()); returns whether it existed.
    boolean
    removeHeaderFooterPicture(String section)
    Remove the header/footer picture in section; returns whether one existed.
    boolean
    removePicture(int pictureIndex)
    Remove the picture at pictureIndex (0-based, the same index used by pictureData(int)); returns whether it existed.
    boolean
    removeProtectedRange(String name)
    Removes the allow-edit-range name; returns whether it existed.
    boolean
    removeShape(int shapeIndex)
    Remove the shape at shapeIndex (0-based, the same index used by shapeType(int)); returns whether it existed.
    boolean
    removeTable(String name)
    Remove the table with the given name; returns whether any matched.
    boolean
    removeValidation(int validationIndex)
    Remove the data-validation rule at validationIndex (its position in validations()); returns whether it existed.
    byte[]
    renderChartToPng(int chartIndex, int width, int height)
    Render the chart at chartIndex to PNG image bytes at the given pixel size, or null if the index is out of range.
    String
    renderChartToSvg(int chartIndex, int width, int height)
    Render the chart at chartIndex to a standalone SVG document at the given pixel size, or null if the index is out of range.
    int
    replaceAll(String find, String replace)
    Replace text in all matching cells; returns the number replaced.
    int
    replaceAll(String find, String replace, boolean caseSensitive, boolean matchEntire, boolean wildcard)
    Replace with options.
    int
    replaceAll(String find, String replace, boolean caseSensitive, boolean matchEntire, boolean wildcard, FindFormat format)
    replaceAll(String, String, FindFormat) with the full option set.
    int
    replaceAll(String find, String replace, FindFormat format)
    Replace restricted to cells whose resolved style matches format — see FindFormat for the matching semantics.
    int
    replaceAllRegex(String pattern, String replacement)
    Replace every match of the regular expression pattern (case-insensitive) with replacement, which may reference capture groups ("$1", "${name}").
    int
    replaceAllRegex(String pattern, String replacement, boolean caseSensitive)
    replaceAllRegex(String, String) with explicit case sensitivity.
    void
    replaceChart(int chartIndex, Chart chart)
    Apply chart's spec onto the chart already at chartIndex, in place, keeping its position in charts().
    boolean
    resizeTable(String name, Range newRange)
    Resize the named table to newRange (Excel's Table Design > Resize Table).
    boolean
    rightToLeft()
    Whether this sheet is displayed right-to-left.
    double
    rowHeight(int row)
    A row's height in points.
    int
    rowOutlineLevel(int row)
    A row's outline level (0 = not grouped).
    int[]
    rowPageBreaks()
    The manual horizontal page-break rows.
    CellStyle
    rowStyle(int row)
    The style applied to the entire row — the default for cells in the row that carry no cell-level style.
    int
    rowStyleId(int row)
    The interned style id applied to the entire row (<row s="N" customFormat="1">), or 0 when the row carries no row-level style.
    int
    scenarioCount()
     
    String
    scenarioName(int scenarioIndex)
     
    int
    scrollColumn()
    The first visible column of an unfrozen view; see scrollRow().
    int
    scrollRow()
    The first visible row of an unfrozen view — the row component of <sheetView topLeftCell> (ECMA-376 Part 1 §18.3.1.87), i.e.
    String
    selectionSqref()
    The selected ranges of the sheet view (<selection sqref>) as a space-separated list, or null when nothing was selected.
    void
    setActiveCell(String cell, String sqref)
    Moves the cursor and the selection.
    void
    setAutoFilter(Range range)
    Define an auto-filter over range (its top row is the filter header).
    void
    setBackgroundImage(byte[] imageData, String format)
    Set the full-sheet background image.
    void
    setBaseColumnWidth(int width)
    Set the baseColWidth basis in characters.
    void
    setColumnColorFilter(int columnIndex, boolean cellColor, Color color)
    Filter a column by cell fill color (or font color when cellColor is false); only rows whose cell matches color survive.
    void
    setColumnCustomFilter(int columnIndex, FilterOperator op, String value)
    A single-condition custom filter on a column.
    void
    setColumnCustomFilter(int columnIndex, FilterOperator op1, String value1, FilterOperator op2, String value2, boolean andJoin)
    A two-condition custom filter; andJoin = true joins with AND, false OR.
    void
    setColumnDateFilter(int columnIndex, boolean includeBlank, DateGroupItem... items)
    A date grouping filter that optionally keeps blank cells too.
    void
    setColumnDateFilter(int columnIndex, DateGroupItem... items)
    A date grouping filter (ECMA-376 §18.3.2.4) on a column: a date cell survives applyAutoFilter() if it falls inside any of items.
    void
    setColumnDynamicFilter(int columnIndex, DynamicFilterType type)
    A dynamic filter (ECMA-376 §18.3.2.5) on a column: today / thisWeek / lastMonth / yearToDate / aboveAverage / ….
    void
    setColumnFilter(int columnIndex, String... values)
    Restrict a column (0-based, relative to the auto-filter range start) to the given values.
    void
    setColumnGroupCollapsed(int startCol, int endCol, boolean collapsed)
    Collapse or expand a grouped column range — the column analogue.
    void
    setColumnHidden(int col, boolean hidden)
    Show or hide a column.
    void
    setColumnsOutlineLevel(int startCol, int endCol, int level)
    Set the outline level 0..7 on columns [startCol, endCol].
    void
    setColumnStyle(int col, CellStyle style)
    Apply a style to the entire column: cells in the column without a cell-level style render with it, exactly like Excel's "format whole column".
    void
    setColumnTop10Filter(int columnIndex, boolean percent, double value, boolean bottom)
    A Top-10 filter (ECMA-376 §18.3.2.10) on a column: keep the top value items — or value percent of the items when percent is true; bottom flips to the smallest values.
    void
    setColumnWidth(int col, double width)
    Set a column's width in Excel character units.
    void
    setDefaultColumnWidth(double width)
    Set the explicit default column width in character units.
    void
    setDefaultRowHeight(double points)
    Set the default row height in points.
    void
    setDefaultRowHeightCustom(boolean custom)
    Set the customHeight flag on the default row height.
    void
    setDifferentFirst(boolean on)
    Set the differentFirst flag.
    void
    setDifferentOddEven(boolean on)
    Set the differentOddEven flag.
    void
    setDyDescent(double dy)
    Set (or clear, with 0) the sheet-level x14ac:dyDescent hint.
    void
    setEvenFooter(String text)
    Set the even-page footer text; null clears it.
    void
    setEvenHeader(String text)
    Set the even-page header text; null clears it.
    void
    setFirstFooter(String text)
    Set the first-page footer text; null clears it.
    void
    setFirstHeader(String text)
    Set the first-page header text; null clears it.
    void
    setFirstPageNumber(int number)
    The number printed on the first page; 0 restores the workbook's own numbering (ECMA-376 §18.3.1.63 firstPageNumber together with useFirstPageNumber).
    void
    setFooter(String text)
    Set the page footer text; null clears it.
    void
    setHeader(String text)
    Set the page header text; null clears it.
    boolean
    setHeaderFooterPicture(String section, byte[] data, String format, double widthPt, double heightPt)
    Place a picture in a header/footer section (ECMA-376 §18.3.1.32 legacyDrawingHF).
    void
    setLandscape(boolean landscape)
    Set landscape (true) or portrait (false) orientation.
    void
    setNumber(int row, int col, double value)
    Set a single numeric cell (0-based).
    void
    setPageMargins(double left, double right, double top, double bottom, double header, double footer)
    Set the six page margins in inches (Excel semantics, ECMA-376 §18.3.1.62 pageMargins).
    void
    setPageMargins(PageMargins m)
    Set the page margins from a PageMargins value — the symmetric counterpart of pageMargins(), so a read–modify–write round-trip needs no unpacking into six positional arguments.
    void
    setPageOrderOverThenDown(boolean overThenDown)
    Whether pages print over-then-down instead of down-then-over (ECMA-376 §18.3.1.63 pageOrder).
    void
    setPageScale(int scalePercent)
    Set the print scale percentage (disables fit-to-page).
    void
    setPaperSize(int paperSize)
    Set the paper size from its ECMA-376 numeric code (§18.18.50 ST_PaperSize): 1 = Letter, 5 = Legal, 8 = A3, 9 = A4, 11 = A5, ….
    boolean
    setPictureLinkTarget(int pictureIndex, String target)
    Repoints a linked picture at a new source.
    void
    setPrintArea(String a1Range)
    Set the print area (A1 range), or null to clear it.
    void
    setPrintBlackAndWhite(boolean on)
    Print without colour (ECMA-376 §18.3.1.63 blackAndWhite).
    void
    setPrintComments(int mode)
    Where cell comments print: 0 not at all, 1 as displayed on the sheet, 2 collected at the end (ECMA-376 §18.3.1.63 cellComments).
    void
    setPrintDraft(boolean on)
    Print in draft quality, omitting graphics (ECMA-376 §18.3.1.63 draft).
    void
    setPrintErrors(int mode)
    How error cells print: 0 as displayed, 1 blank, 2 as a dash, 3 as #N/A (ECMA-376 §18.3.1.70 printOptions/errors).
    void
    setPrintGridlines(boolean on)
    Whether gridlines are printed.
    void
    setPrintHeadings(boolean on)
    Whether row and column headings are printed (ECMA-376 §18.3.1.70 printOptions/headings).
    void
    setPrintHorizontallyCentered(boolean centered)
    Center printed output horizontally on the page.
    void
    setPrintResolution(int dpi)
    The printer resolution in DPI, applied to both axes.
    void
    setPrintTitleColumns(String columnsRange)
    Columns repeated at the left of every printed page (e.g.
    void
    setPrintTitleRows(String rowsRange)
    Rows repeated at the top of every printed page (e.g.
    void
    setPrintVerticallyCentered(boolean centered)
    Center printed output vertically on the page.
    void
    setRightToLeft(boolean rightToLeft)
    Set this sheet's right-to-left display flag.
    void
    setRowGroupCollapsed(int startRow, int endRow, boolean collapsed)
    Collapse or expand a grouped row range (Excel's outline +/- button): hides/shows the detail rows and stamps the collapsed flag on the group's summary row (below the group when the sheet summarizes below).
    void
    setRowHeight(int row, double points)
    Set a row's height in points.
    void
    setRowHidden(int row, boolean hidden)
    Show or hide a row.
    void
    setRowsOutlineLevel(int startRow, int endRow, int level)
    Set the outline level 0..7 on rows [startRow, endRow] (0 ungroups).
    void
    setRowStyle(int row, CellStyle style)
    Apply a style to the entire row: cells in the row without a cell-level style render with it, exactly like Excel's "format whole row".
    boolean
    setScrollPosition(int row, int column)
    Scrolls an unfrozen view so that (row, column) sits at the top left.
    void
    setShapeAltText(int shapeIndex, String text)
    Set (or clear with null) the shape's alternative text.
    void
    setShapeFillColor(int shapeIndex, Color color)
    Set (or clear with null) the shape's solid fill color.
    void
    setShapeFlip(int shapeIndex, boolean flipHorizontal, boolean flipVertical)
    Set the shape's horizontal / vertical flip flags.
    void
    setShapeHyperlink(int shapeIndex, String url)
    Set (or clear with null) the shape's hyperlink URL.
    void
    setShapeLineColor(int shapeIndex, Color color)
    Set (or clear with null) the shape's line (outline) color.
    boolean
    setShapeName(int shapeIndex, String name)
    Renames a shape.
    void
    setShapeRotation(int shapeIndex, double degrees)
    Set the shape's rotation in degrees (clockwise).
    void
    setShapeStyleXml(int shapeIndex, String xml)
    Set (or clear with null) the shape's <xdr:style> theme style-matrix reference from raw inner XML (the lnRef / fillRef / effectRef / fontRef children, without the enclosing <xdr:style> tags).
    void
    setShapeText(int shapeIndex, String text)
    Set (or clear with null) the shape's text body.
    void
    setShowFormulas(boolean on)
    Turn the show-formulas display mode on or off.
    void
    setShowGridlines(boolean on)
    Show or hide the sheet view's gridlines.
    void
    setShowRowColHeaders(boolean on)
    Show or hide the sheet view's row/column headers.
    void
    setShowZeros(boolean on)
    Show zeros as 0, or blank the cells that hold them.
    boolean
    setSourceSheetId(int id)
    Renumbers the sheet's <sheet sheetId>.
    boolean
    setSparklineStyle(int group, SparklineStyle style)
    Replaces the style (colors + point-highlight flags) of the group-th sparkline group — the styling counterpart of addSparkline(java.lang.String, java.lang.String, java.lang.String); read the current state back via sparklines() and SparklineGroup.style().
    void
    setSummaryBelow(boolean below)
    Sets whether row-group summaries sit below their detail rows.
    void
    setSummaryRight(boolean right)
    Sets whether column-group summaries sit right of their detail columns.
    void
    setTabColor(Color color)
    Set the sheet tab color; null clears it.
    boolean
    setTableColumnTotals(String tableName, String columnName, TotalsRowFunction function)
    Set the totals-row aggregation of one column of the named table (ECMA-376 §18.18.92 ST_TotalsRowFunction).
    boolean
    setTableColumnTotals(String tableName, String columnName, TotalsRowFunction function, String label, String formula)
    Full form: function may be null (label only); label becomes totalsRowLabel; formula is required for TotalsRowFunction.CUSTOM and ignored otherwise.
    boolean
    setTableHeaderRow(String tableName, boolean shown)
    Show or hide the named table's header row (ECMA-376 §18.5.1.2 headerRowCount: 1 = header present, 0 = headerless).
    boolean
    setTableStyle(String tableName, TableStyleInfo style)
    Replace the style binding (ECMA-376 §18.5.1.20 tableStyleInfo) of the named table; returns whether the table matched.
    boolean
    setTableTotalsRow(String tableName, boolean shown)
    Show or hide the named table's totals row (ECMA-376 §18.5.1.2 totalsRowCount).
    void
    setViewType(String view)
    Sets the view the tab opens in.
    void
    setVisibility(Visibility visibility)
    Set this sheet's visibility.
    void
    setZoom(int percent)
    Set the sheet view zoom percentage.
    String
    shapeAltText(int shapeIndex)
    The shape's alternative text (cNvPr/@descr), or null.
    int[]
    shapeAnchor(int shapeIndex)
    {fromRow, fromCol, toRow, toCol}, or an empty array when out of range.
    int
    shapeCount()
    Number of shapes on this sheet.
    Color
    shapeFillColor(int shapeIndex)
    The shape's solid fill color, or null (no / non-RGB fill).
    boolean[]
    shapeFlip(int shapeIndex)
    {flipHorizontal, flipVertical}, or an empty array when out of range.
    String
    shapeHyperlink(int shapeIndex)
    The hyperlink URL attached to the shape via DrawingML hlinkClick, or null when the shape has no hyperlink.
    Color
    shapeLineColor(int shapeIndex)
    The shape's line (outline) color, or null.
    String
    shapeName(int shapeIndex)
    The shape's drawing name (<xdr:cNvPr name>, ECMA-376 Part 1 §20.5.2.16) — what Excel shows in the Name Box and what a macro uses to address the shape.
    double
    shapeRotation(int shapeIndex)
    The shape's rotation in degrees (clockwise).
    String
    shapeStyleXml(int shapeIndex)
    The raw inner XML of the shape's <xdr:style> theme style-matrix reference (the lnRef / fillRef / effectRef / fontRef children), or null when the shape has no such block.
    String
    shapeText(int shapeIndex)
    The shape's text body, or null.
    String
    shapeType(int shapeIndex)
    The geometry token of the shape at shapeIndex (e.g.
    SheetType
    sheetType()
    What kind of tab this is — worksheet, chartsheet, dialog sheet or (international) Excel-4.0 macro sheet.
    boolean
    showFormulas()
    Whether the grid shows formula text instead of evaluated results (<sheetView showFormulas>).
    boolean
    showGridlines()
    Whether the sheet VIEW draws gridlines (<sheetView showGridLines>, ECMA-376 §18.3.1.87).
    boolean
    showRowColHeaders()
    Whether the sheet VIEW draws the row/column headers (showRowColHeaders).
    boolean
    showScenario(int scenarioIndex)
    Apply a scenario (writes its changing-cell values); returns whether it existed.
    boolean
    showZeros()
    Whether a zero-valued cell shows 0 or shows blank (<sheetView showZeros>, ECMA-376 §18.3.1.87).
    int
    smartArtCount()
    Number of SmartArt diagrams anchored on this sheet.
    List<SmartArt>
    smartArts()
    The SmartArt diagrams anchored on this sheet (read-only descriptors: layout family, anchor, visible node texts).
    void
    sortByColor(Range range, int sortColumnIndex, boolean cellColor, boolean hasHeader, Color... colors)
    Sort the rows of range by cell fill color (or font color when cellColor is false) at sortColumnIndex (0-based, relative to the range start).
    int
    sourceSheetId()
    The workbook-level id this sheet arrived with (<sheet sheetId> in xl/workbook.xml), or 0 for a sheet created in this session — the writer allocates an id for those on save.
    int
    sparklineGroupCount()
    Number of sparkline groups on this sheet.
    List<SparklineGroup>
    sparklines()
    All sparkline groups on this sheet (ECMA-376 Part 4 §18.3.1.32, x14:sparklineGroups): the group type, basic marker/highlight style, series color and each sparkline's data range and draw location.
    int
    splitColumn()
    The split column (0 when unsplit), mirroring freezeColumn().
    void
    splitPanes(int splitRow, int splitColumn)
    Split the view into scrollable panes at (splitRow, splitColumn) (0 = no split on that axis).
    int
    splitRow()
    The split row (rows split below it; 0 when unsplit), mirroring freezeRow().
    int
    subtotal(int firstRow, int lastRow, int groupColumn, boolean hasHeaders, SubtotalFunction function, int... subtotalColumns)
    Insert subtotals into [firstRow, lastRow] as above.
    int
    subtotal(int firstRow, int lastRow, int groupColumn, SubtotalFunction function, int... subtotalColumns)
    Insert subtotals into the sorted data block [firstRow, lastRow]: after each run of equal values in groupColumn, a summary row of function over subtotalColumns is inserted (plus a grand total).
    boolean
    summaryBelow()
    Whether a row group's summary row sits below its detail rows (<outlinePr summaryBelow>, ECMA-376 §18.3.1.61).
    boolean
    summaryRight()
    Whether a column group's summary column sits right of its detail columns (<outlinePr summaryRight>).
    Color
    tabColor()
    The tab color as a typed Color, or null when the tab has no color.
    List<Table>
    tables()
    All tables (ListObjects) on this sheet, with style and totals state.
    int
    textToColumns(String srcRange, int destRow, int destColumn, String delimiters, boolean treatConsecutiveAsOne)
    Text to Columns with an explicit destination: fields of source row i land at (destRow + i, destColumn...).
    int
    textToColumns(String srcRange, String delimiters)
    Text to Columns (Excel's delimited mode) splitting in place: each text cell of the one-column srcRange (e.g.
    int
    textToColumns(String srcRange, String delimiters, boolean treatConsecutiveAsOne)
    Text to Columns splitting in place, optionally treating a run of consecutive delimiters as one split point (Excel's "treat consecutive delimiters as one", useful for space-aligned text).
    void
    unfreeze()
    Remove any frozen panes.
    boolean
    ungroupShapes(int shapeIndex)
    Dissolve a group created by groupShapes(java.lang.String, int...): members return to standalone emission and the group entry is removed.
    String
    uniqueId()
    The sheet's revision GUID as stored in the source file (Excel's xr:uid on the sheet part root), braces included — for example "{B9A12774-C2A8-4D3E-B631-D37318C68856}".
    void
    unprotect()
    Disable sheet protection (ignores any password).
    boolean
    unprotect(String password)
    Disable sheet protection after verifying password against the stored hash (ISO hash, or the legacy 16-bit password attribute of transitional files).
    boolean
    updateFormControl(int controlIndex, FormControl control)
    Replace the form control at controlIndex (its position in formControls()) — read one, tweak it via FormControl.toBuilder(), write it back.
    Range
    usedRange()
    The used-cell bounding range, or null if the sheet is empty.
    List<Validation>
    validations()
    All data-validation rules on this sheet.
    CellValue
    value(int row, int col)
    The value of a single cell (0-based).
    boolean
    verifyProtectedRangePassword(String name, String password)
    Verifies the password of the allow-edit-range name.
    boolean
    verifyProtectionPassword(String password)
    Whether password matches the sheet's stored hash, leaving the protection in place either way.
    String
    viewType()
    Which view the tab opens in (<sheetView view>, ECMA-376 §18.3.1.87): "normal", "pageBreakPreview" or "pageLayout".
    Visibility
    visibility()
    This sheet's visibility (visible / hidden / very-hidden).
    int
    zoom()
    The sheet view zoom percentage (100 by default).

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • name

      public String name()
      The sheet's display name.

    • index

      public int index()
      The 0-based index of this sheet in its workbook — its position NOW. A Sheet is bound to its tab, not to a position: after Workbook.insertSheet(int, java.lang.String), Workbook.moveSheet(int, int) or a delete of another sheet it keeps referring to the same tab.
      Throws:
      IllegalStateException - if this sheet has been deleted

    • visibility

      public Visibility visibility()
      This sheet's visibility (visible / hidden / very-hidden).

    • setVisibility

      public void setVisibility(Visibility visibility)
      Set this sheet's visibility. VERY_HIDDEN hides it from the UI too.

    • sheetType

      public SheetType sheetType()
      What kind of tab this is — worksheet, chartsheet, dialog sheet or (international) Excel-4.0 macro sheet.

      Classification only: the engine models worksheet content, so a non-worksheet tab reads back with an empty grid, and the kind is not preserved when the workbook is saved.

    • uniqueId

      public String uniqueId()
      The sheet's revision GUID as stored in the source file (Excel's xr:uid on the sheet part root), braces included — for example "{B9A12774-C2A8-4D3E-B631-D37318C68856}". null when the source declared none (files written before Excel 2014, and dialog sheets).

      Read-only: the value is not written back on save.

    • rightToLeft

      public boolean rightToLeft()
      Whether this sheet is displayed right-to-left.

    • setRightToLeft

      public void setRightToLeft(boolean rightToLeft)
      Set this sheet's right-to-left display flag.

    • tabColor

      public Color tabColor()
      The tab color as a typed Color, or null when the tab has no color. RGB, theme (with tint), and legacy indexed tab colors are all surfaced — inspect the kind with Color.isTheme() etc.

    • setTabColor

      public void setTabColor(Color color)
      Set the sheet tab color; null clears it. RGB, theme, and indexed colors are all accepted (an Color.auto() color clears it, since a tab has no automatic color).

    • header

      public String header()
      The page header text (Excel codes like &C, &P allowed), or null.

    • setHeader

      public void setHeader(String text)
      Set the page header text; null clears it.

    • footer

      public String footer()
      The page footer text, or null.

    • setFooter

      public void setFooter(String text)
      Set the page footer text; null clears it.

    • firstHeader

      public String firstHeader()
      The first-page header text, or null (only used when differentFirst()).

    • setFirstHeader

      public void setFirstHeader(String text)
      Set the first-page header text; null clears it.

    • firstFooter

      public String firstFooter()
      The first-page footer text, or null (only used when differentFirst()).

    • setFirstFooter

      public void setFirstFooter(String text)
      Set the first-page footer text; null clears it.

    • differentFirst

      public boolean differentFirst()
      Whether the first printed page uses its own header/footer (ECMA-376 §18.3.1.46 differentFirst). When true, the odd/default header/footer is suppressed on page 1 in favor of the first-page variant — e.g. no page number on a cover page.

    • setDifferentFirst

      public void setDifferentFirst(boolean on)
      Set the differentFirst flag.

    • evenHeader

      public String evenHeader()
      The even-page header text, or null (only used when differentOddEven()).

    • setEvenHeader

      public void setEvenHeader(String text)
      Set the even-page header text; null clears it.

    • evenFooter

      public String evenFooter()
      The even-page footer text, or null (only used when differentOddEven()).

    • setEvenFooter

      public void setEvenFooter(String text)
      Set the even-page footer text; null clears it.

    • differentOddEven

      public boolean differentOddEven()
      Whether odd and even printed pages use distinct headers/footers (ECMA-376 §18.3.1.46 differentOddEven). When true, the even-page variant prints on pages 2, 4, 6, … and the odd/default variant on pages 1, 3, 5, … — e.g. mirrored margins in a bound document.

    • setDifferentOddEven

      public void setDifferentOddEven(boolean on)
      Set the differentOddEven flag.

    • range

      public Range range(int r1, int c1, int r2, int c2)
      A range over the inclusive rectangle (r1,c1)..(r2,c2), 0-based.

    • range

      public Range range(String a1)
      A range parsed from A1 notation, e.g. "A1" or "A1:C10".

    • cell

      public Cell cell(int row, int col)
      A single-cell view at (row, col) (0-based).

    • value

      public CellValue value(int row, int col)
      The value of a single cell (0-based). Convenience — one JNI crossing; use range(int, int, int, int) for bulk work.

    • setNumber

      public void setNumber(int row, int col, double value)
      Set a single numeric cell (0-based). The value only: the cell keeps its style, comment and hyperlink, as with Cell.setValue. One JNI crossing.

    • importData

      public <T> int importData(int startRow, int startCol, List<T> items, ImportOptions options)
      Import a collection of Java objects into a range. Each element becomes one row starting at (startRow, startCol); the object's properties become columns. Properties are discovered by reflection — Java records first (component order), else JavaBean getters (getX/isX, ordered by property name), else public instance fields (declared order). An element that is a Map is a row keyed by column name: its keys become the columns, in the order they are first met across the rows (pass ImportOptions.columns or use a LinkedHashMap for a fixed order), and a missing key leaves its cell blank. Values map to CellValue: numbers stay numeric, Boolean to bool, CharSequence to text, LocalDate/LocalDateTime/Date to Excel date serials, null to blank, anything else to its toString().

      Rows are written through the bulk Range.setValues(io.keikai.axyra.sheets.CellValue[][]) path in chunks (one JNI crossing per chunk).

      Parameters:
      items - the objects to import; must all be the same class as the first element, or all be maps
      options - column selection, header, labels, and header style; when null, ImportOptions.defaults() apply
      Returns:
      the number of rows written, including the header row when enabled
      Throws:
      AxyraException - if items is null, the elements are of mixed types, an element is a plain value (a string, number, date, collection or array) rather than a row, or an options.columns() name is unknown

    • importData

      public <T> int importData(int startRow, int startCol, List<T> items)
      Import a collection with default options (header row on, all properties).

    • insertRows

      public void insertRows(int startRow, int count)
      Insert count blank rows before startRow.

    • deleteRows

      public void deleteRows(int startRow, int count)
      Delete count rows starting at startRow.

    • insertColumns

      public void insertColumns(int startCol, int count)
      Insert count blank columns before startCol.

    • deleteColumns

      public void deleteColumns(int startCol, int count)
      Delete count columns starting at startCol.

    • setRowHeight

      public void setRowHeight(int row, double points)
      Set a row's height in points.

    • rowHeight

      public double rowHeight(int row)
      A row's height in points.

    • isRowHeightCustom

      public boolean isRowHeightCustom(int row)
      Whether the row's height was explicitly authored (via setRowHeight(int, double) or a <row ht> in the source file). This distinction matters to Excel: a row without an explicit height auto-fits to its content font when the file opens, while an explicit height stays fixed — even when its value equals defaultRowHeight().

    • setColumnWidth

      public void setColumnWidth(int col, double width)
      Set a column's width in Excel character units.

    • columnWidth

      public double columnWidth(int col)
      A column's width in character units.

    • defaultRowHeight

      public double defaultRowHeight()
      The sheet's default row height in points — the height of every row without an explicit setRowHeight(int, double) override. 15 for a freshly created sheet; 0 when a loaded sheet declares no default at all (Excel then uses its font-derived default).

    • setDefaultRowHeight

      public void setDefaultRowHeight(double points)
      Set the default row height in points. Pass 0 to clear the declaration so the saved sheet carries no explicit default.

    • isDefaultRowHeightCustom

      public boolean isDefaultRowHeightCustom()
      Whether the default row height is flagged as an explicit, honoured value (the sheetFormatPr customHeight flag).

    • setDefaultRowHeightCustom

      public void setDefaultRowHeightCustom(boolean custom)
      Set the customHeight flag on the default row height.

    • defaultColumnWidth

      public double defaultColumnWidth()
      The sheet's explicit default column width in character units, or 0 when none is declared — column widths then derive from baseColumnWidth(). A freshly created sheet reports Excel's stock 8.43. columnWidth(int) on an untouched column always returns the effective width, whichever way it is declared.

    • setDefaultColumnWidth

      public void setDefaultColumnWidth(double width)
      Set the explicit default column width in character units. Pass 0 to clear the declaration (widths then fall back to the baseColWidth basis).

    • baseColumnWidth

      public int baseColumnWidth()
      The declared baseColWidth basis in characters, or 0 when the sheet does not declare one (the spec default of 8 applies).

    • setBaseColumnWidth

      public void setBaseColumnWidth(int width)
      Set the baseColWidth basis in characters. Pass 0 to clear the declaration.

    • formattedColumns

      public int[] formattedColumns()
      The 0-based indexes (ascending) of columns carrying explicit column-level metadata — width, hidden flag, column style or outline. Columns using pure defaults are not listed; a fresh sheet returns an empty array.

    • formattedRows

      public int[] formattedRows()
      0-based indexes of the rows carrying explicit row-level metadata — a custom height, a hidden flag, or a row style — the row analogue of formattedColumns(). A row with an authored height but no cells (e.g. a top spacer row) is listed here even though a used-cell-rectangle sweep would miss it. Rows using pure defaults are not listed.

    • isColumnWidthCustom

      public boolean isColumnWidthCustom(int col)
      Whether the column's width was explicitly authored (via setColumnWidth(int, double) or a <col width> in the source file), as opposed to inheriting the sheet default.

    • columnStyleId

      public int columnStyleId(int col)
      The column-level style id (an engine-internal dedup index, matching Range.styleIds()), or 0 when the column carries no column-level style.

    • columnStyle

      public CellStyle columnStyle(int col)
      The style applied to the entire column — the default for cells in the column that carry no cell-level style (<col style>). Returns null when the column has none.

    • setColumnStyle

      public void setColumnStyle(int col, CellStyle style)
      Apply a style to the entire column: cells in the column without a cell-level style render with it, exactly like Excel's "format whole column". Pass null to clear.

    • rowStyleId

      public int rowStyleId(int row)
      The interned style id applied to the entire row (<row s="N" customFormat="1">), or 0 when the row carries no row-level style. The row analogue of columnStyleId(int).

    • rowStyle

      public CellStyle rowStyle(int row)
      The style applied to the entire row — the default for cells in the row that carry no cell-level style. Returns null when the row has none.

    • setRowStyle

      public void setRowStyle(int row, CellStyle style)
      Apply a style to the entire row: cells in the row without a cell-level style render with it, exactly like Excel's "format whole row". Pass null to clear.

    • showGridlines

      public boolean showGridlines()
      Whether the sheet VIEW draws gridlines (<sheetView showGridLines>, ECMA-376 §18.3.1.87). Distinct from printGridlines(), which controls printing — dashboards commonly hide the on-screen gridlines while never printing them.

    • setShowGridlines

      public void setShowGridlines(boolean on)
      Show or hide the sheet view's gridlines.

    • showRowColHeaders

      public boolean showRowColHeaders()
      Whether the sheet VIEW draws the row/column headers (showRowColHeaders).

    • setShowRowColHeaders

      public void setShowRowColHeaders(boolean on)
      Show or hide the sheet view's row/column headers.

    • showZeros

      public boolean showZeros()
      Whether a zero-valued cell shows 0 or shows blank (<sheetView showZeros>, ECMA-376 §18.3.1.87). The attribute's default is true, which is what a sheet that never declared one reports.

    • setShowZeros

      public void setShowZeros(boolean on)
      Show zeros as 0, or blank the cells that hold them.

    • showFormulas

      public boolean showFormulas()
      Whether the grid shows formula text instead of evaluated results (<sheetView showFormulas>). A display mode only — the stored values are untouched, so nothing recalculates when it changes.

    • setShowFormulas

      public void setShowFormulas(boolean on)
      Turn the show-formulas display mode on or off.

    • viewType

      public String viewType()
      Which view the tab opens in (<sheetView view>, ECMA-376 §18.3.1.87): "normal", "pageBreakPreview" or "pageLayout". A sheet with no such attribute reports "normal", the value the spec assigns it.

    • setViewType

      public void setViewType(String view)
      Sets the view the tab opens in. "normal" clears the attribute rather than writing it, so a sheet that never had one does not gain a view="normal" it did not carry before.

    • summaryBelow

      public boolean summaryBelow()
      Whether a row group's summary row sits below its detail rows (<outlinePr summaryBelow>, ECMA-376 §18.3.1.61). true is the default. Grouping reads the flag when it places a summary, so flipping it changes where later groups collapse to.

    • setSummaryBelow

      public void setSummaryBelow(boolean below)
      Sets whether row-group summaries sit below their detail rows.

    • summaryRight

      public boolean summaryRight()
      Whether a column group's summary column sits right of its detail columns (<outlinePr summaryRight>). true is the default.

    • setSummaryRight

      public void setSummaryRight(boolean right)
      Sets whether column-group summaries sit right of their detail columns.

    • activeCell

      public String activeCell()
      The sheet view's active cell as an A1 reference (<sheetView><selection activeCell>, ECMA-376 §18.3.1.78), or null when the sheet carries no selection at all.

    • selectionSqref

      public String selectionSqref()
      The selected ranges of the sheet view (<selection sqref>) as a space-separated list, or null when nothing was selected.

    • setActiveCell

      public void setActiveCell(String cell, String sqref)
      Moves the cursor and the selection. sqref may name several space-separated ranges; null selects the active cell alone.

      Any per-pane selection list captured on import is dropped, because it records the old cursor — keeping it would make the saved file reopen at the previous position and silently discard this call.

    • sourceSheetId

      public int sourceSheetId()
      The workbook-level id this sheet arrived with (<sheet sheetId> in xl/workbook.xml), or 0 for a sheet created in this session — the writer allocates an id for those on save.

      Pivot caches, defined names and external links address a sheet by this id rather than by tab position, so it is not index().

    • setSourceSheetId

      public boolean setSourceSheetId(int id)
      Renumbers the sheet's <sheet sheetId>.

      Returns false for 0 — which the writer reads as "unset" and would replace with an allocated id — and for an id another sheet already holds, since sheet ids are unique within a workbook and a duplicate makes the package invalid rather than merely wrong.

    • scrollRow

      public int scrollRow()
      The first visible row of an unfrozen view — the row component of <sheetView topLeftCell> (ECMA-376 Part 1 §18.3.1.87), i.e. where the window is scrolled to. 0 when unscrolled.

      A sheet with frozen panes uses the same attribute to anchor the frozen corner instead, and reports 0 here; read freezeRow() / freezeColumn() for that sheet.

    • scrollColumn

      public int scrollColumn()
      The first visible column of an unfrozen view; see scrollRow().

    • setScrollPosition

      public boolean setScrollPosition(int row, int column)
      Scrolls an unfrozen view so that (row, column) sits at the top left.

      Returns false for a sheet with frozen panes: there the attribute belongs to the frozen corner, so writing a scroll position into it would move the freeze rather than the window.

    • hasPageSetup

      public boolean hasPageSetup()
      Whether the sheet carries a <pageSetup> element (ECMA-376 §18.3.1.63). Presence changes real Excel's print layout both ways — a spurious element flips the default paper to Letter, a missing one shifts the printed body up — so a faithful rebuild reproduces it exactly. Any page-setup setter (orientation, scale, fit-to-page, paper size) marks the element present.

    • dyDescent

      public double dyDescent()
      The sheet-level x14ac:dyDescent text-descent hint on <sheetFormatPr>, or 0 when absent. Excel caches the default font's descent here and uses it when computing the rendered height of height-less rows; a rebuilt sheet that drops the hint can fit a different number of rows per printed page, drifting every page break of a long table.

    • setDyDescent

      public void setDyDescent(double dy)
      Set (or clear, with 0) the sheet-level x14ac:dyDescent hint.

    • setRowHidden

      public void setRowHidden(int row, boolean hidden)
      Show or hide a row.

    • isRowHidden

      public boolean isRowHidden(int row)

    • setColumnHidden

      public void setColumnHidden(int col, boolean hidden)
      Show or hide a column.

    • isColumnHidden

      public boolean isColumnHidden(int col)

    • freezePanes

      public void freezePanes(int freezeRow, int freezeCol)
      Freeze rows above freezeRow and columns left of freezeCol.

    • unfreeze

      public void unfreeze()
      Remove any frozen panes.

    • freezeRow

      public int freezeRow()
      The frozen row split (rows above are frozen); 0 if none.

    • freezeColumn

      public int freezeColumn()
      The frozen column split (columns left are frozen); 0 if none.

    • splitPanes

      public void splitPanes(int splitRow, int splitColumn)
      Split the view into scrollable panes at (splitRow, splitColumn) (0 = no split on that axis). Unlike a freeze, both panes scroll.

    • splitRow

      public int splitRow()
      The split row (rows split below it; 0 when unsplit), mirroring freezeRow().

    • splitColumn

      public int splitColumn()
      The split column (0 when unsplit), mirroring freezeColumn().

    • addRowPageBreak

      public void addRowPageBreak(int row)
      Insert a manual page break before row (horizontal break).

    • addColumnPageBreak

      public void addColumnPageBreak(int column)
      Insert a manual page break before column (vertical break).

    • rowPageBreaks

      public int[] rowPageBreaks()
      The manual horizontal page-break rows.

    • columnPageBreaks

      public int[] columnPageBreaks()
      The manual vertical page-break columns.

    • clearPageBreaks

      public void clearPageBreaks()
      Remove all manual page breaks.

    • mergedRegions

      public List<Range> mergedRegions()
      The merged-cell regions on this sheet.

    • usedRange

      public Range usedRange()
      The used-cell bounding range, or null if the sheet is empty.

    • find

      public int[][] find(String text)
      Find all cells whose text matches, as {row, col} pairs. Sheet-wide.

    • find

      public int[][] find(String text, boolean caseSensitive, boolean matchEntire, boolean wildcard)
      Find with options. Sheet-wide.

    • findRegex

      public int[][] findRegex(String pattern)
      Find all cells whose text matches the regular expression pattern (case-insensitive), as {row, col} pairs. Sheet-wide. An invalid pattern falls back to plain-text matching.

    • findRegex

      public int[][] findRegex(String pattern, boolean caseSensitive)
      findRegex(String) with explicit case sensitivity.

    • find

      public int[][] find(String text, FindFormat format)
      Find restricted to cells whose resolved style matches format (Excel's search-by-format) — see FindFormat for the matching semantics. An empty text with a non-empty format is a format-only find: it returns every cell carrying the format regardless of value type. Sheet-wide.

    • find

      public int[][] find(String text, boolean caseSensitive, boolean matchEntire, boolean wildcard, FindFormat format)
      find(String, FindFormat) with the full option set. Sheet-wide.

    • replaceAll

      public int replaceAll(String find, String replace)
      Replace text in all matching cells; returns the number replaced. Sheet-wide.

    • replaceAll

      public int replaceAll(String find, String replace, boolean caseSensitive, boolean matchEntire, boolean wildcard)
      Replace with options. Sheet-wide.

    • replaceAllRegex

      public int replaceAllRegex(String pattern, String replacement)
      Replace every match of the regular expression pattern (case-insensitive) with replacement, which may reference capture groups ("$1", "${name}"). Returns the number of cells changed. Sheet-wide.

    • replaceAllRegex

      public int replaceAllRegex(String pattern, String replacement, boolean caseSensitive)
      replaceAllRegex(String, String) with explicit case sensitivity.

    • replaceAll

      public int replaceAll(String find, String replace, FindFormat format)
      Replace restricted to cells whose resolved style matches format — see FindFormat for the matching semantics. An empty find text replaces nothing. Returns the number replaced. Sheet-wide.

    • replaceAll

      public int replaceAll(String find, String replace, boolean caseSensitive, boolean matchEntire, boolean wildcard, FindFormat format)
      replaceAll(String, String, FindFormat) with the full option set.

    • textToColumns

      public int textToColumns(String srcRange, String delimiters)
      Text to Columns (Excel's delimited mode) splitting in place: each text cell of the one-column srcRange (e.g. "A1:A10") is split on the delimiters characters and the fields spread rightward from the source column, overwriting existing cells without prompting. Returns the widest row's output column count.
      Parameters:
      delimiters - the set of split characters, e.g. "," or ";\t" — tab, semicolon, comma, and space plus at most one custom character

    • textToColumns

      public int textToColumns(String srcRange, String delimiters, boolean treatConsecutiveAsOne)
      Text to Columns splitting in place, optionally treating a run of consecutive delimiters as one split point (Excel's "treat consecutive delimiters as one", useful for space-aligned text).

    • textToColumns

      public int textToColumns(String srcRange, int destRow, int destColumn, String delimiters, boolean treatConsecutiveAsOne)
      Text to Columns with an explicit destination: fields of source row i land at (destRow + i, destColumn...). The source range must be exactly one column wide (as in Excel).

    • validations

      public List<Validation> validations()
      All data-validation rules on this sheet.

    • clearValidations

      public void clearValidations()
      Remove all data-validation rules from this sheet.

    • removeValidation

      public boolean removeValidation(int validationIndex)
      Remove the data-validation rule at validationIndex (its position in validations()); returns whether it existed.

    • conditionalFormats

      public List<ConditionalFormat> conditionalFormats()
      All conditional-formatting rules on this sheet.

    • clearConditionalFormats

      public void clearConditionalFormats()
      Remove all conditional-formatting rules from this sheet.

    • removeConditionalFormat

      public boolean removeConditionalFormat(int formatIndex)
      Remove the conditional-formatting rule at formatIndex (its position in conditionalFormats()); returns whether it existed.

    • tables

      public List<Table> tables()
      All tables (ListObjects) on this sheet, with style and totals state.

    • removeTable

      public boolean removeTable(String name)
      Remove the table with the given name; returns whether any matched.

    • convertTableToRange

      public boolean convertTableToRange(String name)
      Convert the named table back to an ordinary range (Excel's Table Design > Convert to Range): drops the table definition while keeping every cell value in place. Returns whether the table matched. This is the inverse of Range.createTable(String, String...).

    • resizeTable

      public boolean resizeTable(String name, Range newRange)
      Resize the named table to newRange (Excel's Table Design > Resize Table). The header row must stay where it is, and at least one data row must remain. Columns are remapped by sheet position: kept positions keep their column definitions (totals, formulas); new positions take the header-cell text when present, else a generated unique ColumnN name. Returns whether the resize applied.

    • autoExpandTables

      public boolean autoExpandTables(int row, int col, String typedText)
      Apply Excel's type-adjacent table auto-expansion for a data entry at (row, col): typing one row below a table's last data row (inside its column span, no totals row) grows it by one row; typing in the header row one column right of its last column grows it by one column named typedText — unless another table occupies the candidate column. Only table metadata is adjusted; write the cell value separately. Returns whether any table expanded.

    • smartArtCount

      public int smartArtCount()
      Number of SmartArt diagrams anchored on this sheet.

    • smartArts

      public List<SmartArt> smartArts()
      The SmartArt diagrams anchored on this sheet (read-only descriptors: layout family, anchor, visible node texts). Imported diagrams render in PDF/image output and round-trip on save; authoring is not supported.

    • setTableStyle

      public boolean setTableStyle(String tableName, TableStyleInfo style)
      Replace the style binding (ECMA-376 §18.5.1.20 tableStyleInfo) of the named table; returns whether the table matched. The table part is regenerated on the next save.

    • setTableTotalsRow

      public boolean setTableTotalsRow(String tableName, boolean shown)
      Show or hide the named table's totals row (ECMA-376 §18.5.1.2 totalsRowCount). Showing extends the table range one row down and materializes the configured per-column totals cells (SUBTOTAL formulas / labels), like Excel; hiding shrinks the range back. Returns whether the table matched.

    • setTableHeaderRow

      public boolean setTableHeaderRow(String tableName, boolean shown)
      Show or hide the named table's header row (ECMA-376 §18.5.1.2 headerRowCount: 1 = header present, 0 = headerless). Unlike the totals row, this does NOT resize the table range — the first row of the range is simply re-interpreted as header (shown) or first data row (hidden). A createTable always makes a header-row table, so pass false here to reproduce a headerless source table; otherwise Excel treats the first data row as the header and may refuse to open the file. Returns whether the table matched.

    • setTableColumnTotals

      public boolean setTableColumnTotals(String tableName, String columnName, TotalsRowFunction function)
      Set the totals-row aggregation of one column of the named table (ECMA-376 §18.18.92 ST_TotalsRowFunction). Built-in functions become SUBTOTAL(101..110, Table[Column]) cells when the totals row is shown. Use setTableColumnTotals(String, String, TotalsRowFunction, String, String) for CUSTOM (needs a formula) or a label. Returns whether the table and column matched.

    • setTableColumnTotals

      public boolean setTableColumnTotals(String tableName, String columnName, TotalsRowFunction function, String label, String formula)
      Full form: function may be null (label only); label becomes totalsRowLabel; formula is required for TotalsRowFunction.CUSTOM and ignored otherwise.

    • addChart

      public int addChart(Chart chart)
      Add a chart to this sheet; returns the new chart's index.

    • addPivotChart

      public int addPivotChart(int pivotIndex, String chartType, int fromRow, int fromCol, int toRow, int toCol)
      Add a PivotChart bound to the pivot table at pivotIndex on this sheet, anchored over the given cell rectangle. The pivot must have been refreshed first so its output range is known; the chart's series are derived from that output (one series per data column, categories from the row-label column, grand totals excluded) and the chart carries Excel's pivotSource binding (ECMA-376 §21.2.2.153) so it stays linked to the pivot on open.
      Parameters:
      pivotIndex - the pivot table's index on this sheet
      chartType - a chart type token accepted by Chart.of(java.lang.String) (e.g. "column", "bar", "pie")
      Returns:
      the new chart's index on this sheet, or -1 when the pivot does not exist or has not been refreshed

    • charts

      public List<Chart> charts()
      All charts on this sheet.

    • chart

      public ChartView chart(int chartIndex)
      A live view of the chart at chartIndex (its position in charts()), with read-back getters and setters that apply immediately. Throws AxyraException when out of range.

    • replaceChart

      public void replaceChart(int chartIndex, Chart chart)
      Apply chart's spec onto the chart already at chartIndex, in place, keeping its position in charts().

      The engine overlays the spec rather than swapping the chart out, so detail the spec does not carry survives — per-series trendlines, error bars and data labels when the matching series is silent about them, plus the parts of an imported chart the spec has no field for (3-D view angles, manual layouts, an Excel-2016 extended chart's preserved apparatus, a PivotChart binding). Marks the sheet's drawing dirty, so the saved package carries the edit.

      This is the read–modify–write counterpart of addChart(io.keikai.axyra.sheets.content.Chart): read with charts(), edit through Chart.toBuilder(), write back here. Editing one field at a time through chart(int) does the same thing one round trip at a time.

    • clearCharts

      public void clearCharts()
      Remove all charts from this sheet.

    • removeChart

      public boolean removeChart(int chartIndex)
      Remove the chart at chartIndex (its position in charts()); returns whether it existed.

    • addCheckbox

      public int addCheckbox(String name, int fromRow, int fromColumn, int toRow, int toColumn, String linkedCell)
      Add a checkbox form control anchored to a two-cell rectangle, optionally bound to a linked cell (A1 ref) reflecting its state. Convenience for addFormControl(FormControl) with a FormControl.checkBox(String) spec.

    • formControlCount

      public int formControlCount()

    • addFormControl

      public int addFormControl(FormControl control)
      Add a form control (check box, option button, button, combo box, list box, scroll bar, spin button, edit box, label, group box); returns its index in formControls(). The control's parts (control properties, legacy drawing shape and worksheet registration) are generated on save.

    • formControls

      public List<FormControl> formControls()
      All form controls on this sheet, in z-order.

    • updateFormControl

      public boolean updateFormControl(int controlIndex, FormControl control)
      Replace the form control at controlIndex (its position in formControls()) — read one, tweak it via FormControl.toBuilder(), write it back. Returns whether it existed.

    • removeFormControl

      public boolean removeFormControl(int controlIndex)
      Remove the form control at controlIndex (its position in formControls()); returns whether it existed.

    • addPivotTable

      public int addPivotTable(String name, String location, String sourceRef)
      Create a pivot table at location (A1 anchor) over a source range; returns its index. Its output is built by PivotTableView.refresh() — and, for a pivot created or changed through the API and not refreshed since, automatically before the workbook is saved or rendered.

    • pivotCount

      public int pivotCount()

    • pivotName

      public String pivotName(int pivotIndex)

    • pivotLocation

      public String pivotLocation(int pivotIndex)
      The destination location (e.g. "H1") of the pivot table at pivotIndex.

    • pivotSource

      public String pivotSource(int pivotIndex)
      The source data reference of the pivot table at pivotIndex.

    • pivotTable

      public PivotTableView pivotTable(int pivotIndex)
      A live view of the pivot table at pivotIndex: field areas (row / column / filter / values), aggregation functions, layout, grand totals, and PivotTableView.refresh().
      Throws:
      AxyraException - when pivotIndex is out of range

    • pivotTable

      public PivotTableView pivotTable(String name)
      A live view of the pivot table named name (exact match first, then case-insensitive).
      Throws:
      AxyraException - when no pivot table has that name

    • addScenario

      public int addScenario(String name, String[] cellRefs, String[] values)
      Add a what-if scenario; returns its index.

    • scenarioCount

      public int scenarioCount()

    • scenarioName

      public String scenarioName(int scenarioIndex)

    • showScenario

      public boolean showScenario(int scenarioIndex)
      Apply a scenario (writes its changing-cell values); returns whether it existed.

    • addPicture

      public int addPicture(byte[] imageData, String format, int fromRow, int fromColumn, int toRow, int toColumn)
      Insert an image anchored to a two-cell rectangle (0-based cells). format is png/jpeg/gif/bmp/tiff/emf/wmf/svg/webp.

    • addPicture

      public int addPicture(byte[] imageData, String format, int fromRow, int fromColumn, int fromRowOffset, int fromColumnOffset, int toRow, int toColumn, int toRowOffset, int toColumnOffset)
      Insert an image with a full two-cell anchor including EMU offsets. The offsets carry a sub-cell size that a plain cell rectangle cannot express (e.g. a one-cell-anchored image whose size lives in the to*Offset fields). Use pictureAnchorFull(int) to read them back.

    • pictureCount

      public int pictureCount()
      Number of pictures on this sheet.

    • addLinkedPicture

      public int addLinkedPicture(String target, String format, int r1, int c1, int r2, int c2)
      Add a linked picture over the rectangle (r1,c1)..(r2,c2): the image is referenced by an external target (URL or path) via <a:blip r:link> instead of embedding bytes (ECMA-376 Part 1 §20.1.8.13). Returns the picture index. Use addPicture(byte[], java.lang.String, int, int, int, int) for the usual embedded case.

    • pictureLinkTarget

      public String pictureLinkTarget(int pictureIndex)
      The external link target of the picture at pictureIndex, or null when it is an ordinary embedded picture.

    • setPictureLinkTarget

      public boolean setPictureLinkTarget(int pictureIndex, String target)
      Repoints a linked picture at a new source.

      Returns false for an embedded picture: its bytes live in the package, so giving it a link would leave the file carrying both the image and a reference to another one. Use addLinkedPicture(String, String, int, int, int, int) to add a linked picture in the first place.

    • setHeaderFooterPicture

      public boolean setHeaderFooterPicture(String section, byte[] data, String format, double widthPt, double heightPt)
      Place a picture in a header/footer section (ECMA-376 §18.3.1.32 legacyDrawingHF). section is "LH" / "CH" / "RH" for the left/center/right header, or "LF" / "CF" / "RF" for the footer; width/height are display points. The picture prints where the section's text contains the &G field code — set the header/footer string accordingly, e.g. setHeader("&C&G") for a centered header image. An existing picture in the same section is replaced. Returns whether the section token was valid.

    • headerFooterPictureData

      public byte[] headerFooterPictureData(String section)
      The image bytes of the header/footer picture in section, or null.

    • removeHeaderFooterPicture

      public boolean removeHeaderFooterPicture(String section)
      Remove the header/footer picture in section; returns whether one existed.

    • anchorOleObject

      public boolean anchorOleObject(int objectIndex, byte[] iconBytes, String iconFormat, int fromRow, int fromCol, int toRow, int toCol)
      Display the workbook-level embedded OLE object at objectIndex (see Workbook.addOleObject(java.lang.String, java.lang.String, byte[])) as an icon on this sheet, anchored over the cell rectangle (fromRow, fromCol)–(toRow, toCol) (0-based, exclusive bottom-right edge like a drawing anchor). iconBytes is the image shown on the sheet (iconFormat: "png", "jpeg", "gif", "bmp", "tiff", "emf", "wmf"); double-clicking the icon in Excel opens the embedded content.

      Returns whether the anchor was added — false when the object index does not exist, the icon bytes are empty, or this sheet already carries OLE anchors imported from an opened XLSX (merging authored icons into an imported legacy drawing is not supported).

    • pictureData

      public byte[] pictureData(int pictureIndex)
      The raw image bytes of the picture at pictureIndex, or null.

    • pictureFormat

      public String pictureFormat(int pictureIndex)
      The format token (png/jpeg/…) of the picture at pictureIndex, or null.

    • pictureAnchor

      public int[] pictureAnchor(int pictureIndex)
      {fromRow, fromCol, toRow, toCol} anchor of the picture, or an empty array.

    • pictureAnchorFull

      public int[] pictureAnchorFull(int pictureIndex)
      {fromRow, fromCol, fromRowOffset, fromColOffset, toRow, toCol, toRowOffset, toColOffset} anchor of the picture (EMU offsets included), or an empty array. Pass these eight values to the 10-arg addPicture(byte[], java.lang.String, int, int, int, int) overload to reproduce the image faithfully.

    • clearPictures

      public void clearPictures()
      Remove all pictures from this sheet.

    • removePicture

      public boolean removePicture(int pictureIndex)
      Remove the picture at pictureIndex (0-based, the same index used by pictureData(int)); returns whether it existed.

    • setBackgroundImage

      public void setBackgroundImage(byte[] imageData, String format)
      Set the full-sheet background image. Excel tiles the image behind the cells on screen; it is never printed. format is png/jpeg/gif/bmp/tiff/emf/wmf/svg/webp. Replaces any existing background.

    • backgroundImage

      public byte[] backgroundImage()
      The raw bytes of the sheet background image, or null when none.

    • backgroundImageFormat

      public String backgroundImageFormat()
      The format token (png/jpeg/…) of the sheet background image, or null when none.

    • clearBackgroundImage

      public boolean clearBackgroundImage()
      Remove the sheet background image; returns whether one existed.

    • setLandscape

      public void setLandscape(boolean landscape)
      Set landscape (true) or portrait (false) orientation.

    • isLandscape

      public boolean isLandscape()

    • setPrintArea

      public void setPrintArea(String a1Range)
      Set the print area (A1 range), or null to clear it.

    • printArea

      public String printArea()

    • setPrintTitleRows

      public void setPrintTitleRows(String rowsRange)
      Rows repeated at the top of every printed page (e.g. "$1:$2"); null clears.

    • printTitleRows

      public String printTitleRows()

    • setPrintTitleColumns

      public void setPrintTitleColumns(String columnsRange)
      Columns repeated at the left of every printed page (e.g. "$A:$A"); null clears.

    • printTitleColumns

      public String printTitleColumns()

    • setPrintGridlines

      public void setPrintGridlines(boolean on)
      Whether gridlines are printed.

    • printGridlines

      public boolean printGridlines()
      Whether gridlines are printed (ECMA-376 §18.3.1.65 printOptions/gridLines).

    • setPrintHeadings

      public void setPrintHeadings(boolean on)
      Whether row and column headings are printed (ECMA-376 §18.3.1.70 printOptions/headings). Controls the printout only — distinct from the on-screen heading visibility toggle.

    • setPageOrderOverThenDown

      public void setPageOrderOverThenDown(boolean overThenDown)
      Whether pages print over-then-down instead of down-then-over (ECMA-376 §18.3.1.63 pageOrder).

    • pageOrderOverThenDown

      public boolean pageOrderOverThenDown()
      Whether pages print over-then-down.

    • setPrintBlackAndWhite

      public void setPrintBlackAndWhite(boolean on)
      Print without colour (ECMA-376 §18.3.1.63 blackAndWhite).

    • printBlackAndWhite

      public boolean printBlackAndWhite()
      Whether the sheet prints without colour.

    • setPrintDraft

      public void setPrintDraft(boolean on)
      Print in draft quality, omitting graphics (ECMA-376 §18.3.1.63 draft).

    • printDraft

      public boolean printDraft()
      Whether the sheet prints in draft quality.

    • setPrintErrors

      public void setPrintErrors(int mode)
      How error cells print: 0 as displayed, 1 blank, 2 as a dash, 3 as #N/A (ECMA-376 §18.3.1.70 printOptions/errors).

    • printErrors

      public int printErrors()
      How error cells print, as the same code setPrintErrors(int) takes.

    • setFirstPageNumber

      public void setFirstPageNumber(int number)
      The number printed on the first page; 0 restores the workbook's own numbering (ECMA-376 §18.3.1.63 firstPageNumber together with useFirstPageNumber).

    • firstPageNumber

      public int firstPageNumber()
      The number printed on the first page, or 0 when unset.

    • setPrintComments

      public void setPrintComments(int mode)
      Where cell comments print: 0 not at all, 1 as displayed on the sheet, 2 collected at the end (ECMA-376 §18.3.1.63 cellComments).

    • printComments

      public int printComments()
      Where cell comments print, as the same code setPrintComments(int) takes.

    • setPrintResolution

      public void setPrintResolution(int dpi)
      The printer resolution in DPI, applied to both axes.

    • printResolution

      public int printResolution()
      The printer resolution in DPI.

    • printHeadings

      public boolean printHeadings()
      Whether row and column headings are printed.

    • fitToPage

      public void fitToPage(int width, int height)
      Fit the printout to width pages wide by height tall.

    • isFitToPage

      public boolean isFitToPage()
      Whether fit-to-page scaling is active (set by fitToPage(int, int)); when false the sheet prints at pageScale(). The flag lives in ECMA-376 §18.3.1.70 <pageSetUpPr fitToPage="1"/>.

    • fitToWidth

      public int fitToWidth()
      Pages wide the printout is fitted to (0 = automatic / unlimited); only meaningful when isFitToPage(). ECMA-376 §18.3.1.63 fitToWidth.

    • fitToHeight

      public int fitToHeight()
      Pages tall the printout is fitted to (0 = automatic / unlimited); only meaningful when isFitToPage(). ECMA-376 §18.3.1.63 fitToHeight.

    • setPageScale

      public void setPageScale(int scalePercent)
      Set the print scale percentage (disables fit-to-page).

    • pageScale

      public int pageScale()
      The print scale percentage (100 = no scaling).

    • setPaperSize

      public void setPaperSize(int paperSize)
      Set the paper size from its ECMA-376 numeric code (§18.18.50 ST_PaperSize): 1 = Letter, 5 = Legal, 8 = A3, 9 = A4, 11 = A5, …. Codes below 1 throw AxyraException.

    • paperSize

      public int paperSize()
      The paper size as its ECMA-376 numeric code (9 = A4 by default).

    • isPaperSizeDeclared

      public boolean isPaperSizeDeclared()
      Whether this sheet explicitly declares a paper size. A loaded sheet whose source <pageSetup> carried no paperSize reports false — Excel then prints it on the printer's default paper, whatever paperSize() reports as the engine fallback.

    • clearPaperSize

      public void clearPaperSize()
      Remove the explicit paper-size declaration, so the saved sheet omits the paperSize attribute and consumers use their printer default. Undone by the next setPaperSize(int).

    • printHorizontallyCentered

      public boolean printHorizontallyCentered()
      Whether printed output is centered horizontally on the page (<printOptions horizontalCentered>, ECMA-376 §18.3.1.70).

    • setPrintHorizontallyCentered

      public void setPrintHorizontallyCentered(boolean centered)
      Center printed output horizontally on the page.

    • printVerticallyCentered

      public boolean printVerticallyCentered()
      Whether printed output is centered vertically on the page (<printOptions verticalCentered>, ECMA-376 §18.3.1.70).

    • setPrintVerticallyCentered

      public void setPrintVerticallyCentered(boolean centered)
      Center printed output vertically on the page.

    • setPageMargins

      public void setPageMargins(double left, double right, double top, double bottom, double header, double footer)
      Set the six page margins in inches (Excel semantics, ECMA-376 §18.3.1.62 pageMargins). Negative values throw AxyraException.

    • setPageMargins

      public void setPageMargins(PageMargins m)
      Set the page margins from a PageMargins value — the symmetric counterpart of pageMargins(), so a read–modify–write round-trip needs no unpacking into six positional arguments.

    • pageMargins

      public PageMargins pageMargins()
      The page margins in inches.

    • setZoom

      public void setZoom(int percent)
      Set the sheet view zoom percentage. Excel's valid range is 10–400; anything else throws AxyraException. (The zoom applies to the on-screen view, not printing — use setPageScale(int) for print scaling.)

    • zoom

      public int zoom()
      The sheet view zoom percentage (100 by default).

    • protect

      public void protect()
      Enable sheet protection (Excel-default allowances).

    • protect

      public void protect(String password)
      Enable sheet protection with a password (ISO Write Protection hash, SHA-512 + 100,000 spins per [MS-OFFCRYPTO] §2.4.2.2) and Excel's default allowances. null or empty protects without a password.

    • protect

      public void protect(String password, SheetProtection options)
      Enable sheet protection with explicit ECMA-376 §18.3.1.85 options and an optional password (null = none).

    • unprotect

      public void unprotect()
      Disable sheet protection (ignores any password).

    • unprotect

      public boolean unprotect(String password)
      Disable sheet protection after verifying password against the stored hash (ISO hash, or the legacy 16-bit password attribute of transitional files). Returns true when the sheet ends up unprotected — including when it was not protected or carries no password; returns false (sheet stays protected) on a mismatch.

    • isProtected

      public boolean isProtected()
      Whether this sheet is protected.

    • isProtectedWithPassword

      public boolean isProtectedWithPassword()
      Whether the sheet's protection carries a password.

      Read-only: unlike unprotect(String) this leaves the sheet protected, so a caller can decide whether to prompt without changing the workbook to find out.

    • verifyProtectionPassword

      public boolean verifyProtectionPassword(String password)
      Whether password matches the sheet's stored hash, leaving the protection in place either way.

      Answers true whenever there is no hash to disagree with — both for a sheet protected without a password and for a sheet that is not protected at all. Read as "supplying this password would let you through", which is what a caller gating an unprotect() on it needs; do NOT read it as "this sheet has that password". The two cases are told apart by isProtectedWithPassword(), which is false for both of them.

    • protection

      public SheetProtection protection()
      The protection options (allow semantics), or null when this sheet is not protected.

    • addProtectedRange

      public void addProtectedRange(String name, String sqref, String password)
      Adds an allow-users-to-edit-range (protectedRange — ECMA-376 Part 1 §18.3.1.72): the named range sqref stays editable while the sheet is protected. Pass a password to gate it (stored as an ISO Write Protection hash), or null for an ungated range. Re-adding a range with the same name replaces it.
      Throws:
      AxyraException - when the name or sqref is empty

    • addProtectedRange

      public void addProtectedRange(String name, String sqref)
      Adds an ungated allow-edit-range.

    • removeProtectedRange

      public boolean removeProtectedRange(String name)
      Removes the allow-edit-range name; returns whether it existed.

    • protectedRanges

      public List<ProtectedRange> protectedRanges()
      The sheet's allow-edit-ranges, in definition order.

    • verifyProtectedRangePassword

      public boolean verifyProtectedRangePassword(String name, String password)
      Verifies the password of the allow-edit-range name.

    • setAutoFilter

      public void setAutoFilter(Range range)
      Define an auto-filter over range (its top row is the filter header). The filter is modeled and round-trips to XLSX; note the engine does not itself execute criteria-based row hiding.

    • autoFilterRange

      public Range autoFilterRange()
      The filtered block, or null when this sheet has no autofilter.

      Read counterpart of setAutoFilter(Range): a caller that did not set the filter itself (an imported workbook, for example) needs to know which block the dropdowns cover.

    • hasAutoFilter

      public boolean hasAutoFilter()

    • clearAutoFilter

      public void clearAutoFilter()
      Remove any auto-filter.

    • setColumnFilter

      public void setColumnFilter(int columnIndex, String... values)
      Restrict a column (0-based, relative to the auto-filter range start) to the given values. Takes effect at once, as in Excel: rows that fail are hidden. Every setColumn*Filter and clearColumnFilter(int) re-runs the filter this way.

    • setColumnCustomFilter

      public void setColumnCustomFilter(int columnIndex, FilterOperator op, String value)
      A single-condition custom filter on a column.

    • setColumnCustomFilter

      public void setColumnCustomFilter(int columnIndex, FilterOperator op1, String value1, FilterOperator op2, String value2, boolean andJoin)
      A two-condition custom filter; andJoin = true joins with AND, false OR.

    • setColumnColorFilter

      public void setColumnColorFilter(int columnIndex, boolean cellColor, Color color)
      Filter a column by cell fill color (or font color when cellColor is false); only rows whose cell matches color survive.

    • setColumnTop10Filter

      public void setColumnTop10Filter(int columnIndex, boolean percent, double value, boolean bottom)
      A Top-10 filter (ECMA-376 §18.3.2.10) on a column: keep the top value items — or value percent of the items when percent is true; bottom flips to the smallest values. The threshold is computed from the column data on applyAutoFilter() (non-numeric cells are hidden); ties at the threshold survive.

    • setColumnDynamicFilter

      public void setColumnDynamicFilter(int columnIndex, DynamicFilterType type)
      A dynamic filter (ECMA-376 §18.3.2.5) on a column: today / thisWeek / lastMonth / yearToDate / aboveAverage / …. Date ranges resolve against the current date and the column average is computed on applyAutoFilter().

    • setColumnDateFilter

      public void setColumnDateFilter(int columnIndex, DateGroupItem... items)
      A date grouping filter (ECMA-376 §18.3.2.4) on a column: a date cell survives applyAutoFilter() if it falls inside any of items. Blank cells are hidden; use the includeBlank overload to keep them.

    • setColumnDateFilter

      public void setColumnDateFilter(int columnIndex, boolean includeBlank, DateGroupItem... items)
      A date grouping filter that optionally keeps blank cells too.

    • clearColumnFilter

      public void clearColumnFilter(int columnIndex)
      Remove the filter from a single column.

    • sortByColor

      public void sortByColor(Range range, int sortColumnIndex, boolean cellColor, boolean hasHeader, Color... colors)
      Sort the rows of range by cell fill color (or font color when cellColor is false) at sortColumnIndex (0-based, relative to the range start). Rows are ordered by their color's position in colors; unlisted colors sort last (stable). When hasHeader is true the first row is left in place.

    • applyAutoFilter

      public int applyAutoFilter()
      Execute the auto-filter: hides every data row failing any column's criteria and shows the rest. Returns the number of rows hidden. All filter kinds are evaluated — values, custom, color, Top-10, dynamic (dates resolve against the current date; weeks start on Sunday), and date grouping.

      Setting or clearing a column criterion already runs it; call this to re-run the filter after the data under it changed.

    • applyAdvancedFilter

      public int applyAdvancedFilter(Range listRange, Range criteriaRange, boolean uniqueOnly)
      Run an advanced filter (Excel's Data > Advanced) over listRange in place, hiding the data rows that do not match criteriaRange. Both ranges include a header row; criteria headers are matched to list columns by name. Criteria rows are OR-ed and the cells within one row AND-ed; each criterion cell is empty (no constraint), a comparison (>100, <=50, <>East, =East), or a bare value (numbers match by equality, text "begins with", both honoring */? wildcards). When uniqueOnly is set, duplicate matching rows are also hidden, keeping the first. Returns the number of rows hidden.

    • applyAdvancedFilterCopyTo

      public int applyAdvancedFilterCopyTo(Range listRange, Range criteriaRange, Range destination, boolean uniqueOnly)
      Advanced filter in "Copy to another location" mode: instead of hiding source rows, writes the list header plus each matching row (see applyAdvancedFilter(Range, Range, boolean) for the criteria semantics) starting at the top-left cell of destination. Cells are copied whole (value, style, formula). Returns the number of data rows written (header excluded).

    • groupRows

      public void groupRows(int startRow, int endRow)
      Group rows [startRow, endRow] at outline level 1.

    • setRowGroupCollapsed

      public void setRowGroupCollapsed(int startRow, int endRow, boolean collapsed)
      Collapse or expand a grouped row range (Excel's outline +/- button): hides/shows the detail rows and stamps the collapsed flag on the group's summary row (below the group when the sheet summarizes below).

    • setColumnGroupCollapsed

      public void setColumnGroupCollapsed(int startCol, int endCol, boolean collapsed)
      Collapse or expand a grouped column range — the column analogue.

    • setRowsOutlineLevel

      public void setRowsOutlineLevel(int startRow, int endRow, int level)
      Set the outline level 0..7 on rows [startRow, endRow] (0 ungroups).

    • groupColumns

      public void groupColumns(int startCol, int endCol)
      Group columns [startCol, endCol] at outline level 1.

    • setColumnsOutlineLevel

      public void setColumnsOutlineLevel(int startCol, int endCol, int level)
      Set the outline level 0..7 on columns [startCol, endCol].

    • rowOutlineLevel

      public int rowOutlineLevel(int row)
      A row's outline level (0 = not grouped).

    • autoFitRow

      public void autoFitRow(int row)
      Auto-fit a row's height from the default font size.

    • autoFitColumn

      public void autoFitColumn(int col)
      Auto-fit a column's width to its widest cell value.

    • subtotal

      public int subtotal(int firstRow, int lastRow, int groupColumn, SubtotalFunction function, int... subtotalColumns)
      Insert subtotals into the sorted data block [firstRow, lastRow]: after each run of equal values in groupColumn, a summary row of function over subtotalColumns is inserted (plus a grand total). Data rows get outline level 1. Returns the number of rows inserted.

      Like Excel, the grand total is one SUBTOTAL over the whole data body rather than a SUM of the group summaries: SUBTOTAL ignores the summaries caught inside that span, so the span keeps totalling correctly when a row is later inserted into a group.

      Every row of the block is data — pass hasHeaders to the overload below for Excel's Data > Subtotal behaviour instead.

    • subtotal

      public int subtotal(int firstRow, int lastRow, int groupColumn, boolean hasHeaders, SubtotalFunction function, int... subtotalColumns)
      Insert subtotals into [firstRow, lastRow] as above. With hasHeaders the block follows Excel's Data > Subtotal contract: leading blank rows and the first non-blank row (the header) stay in place and never form a group of their own. With hasHeaders false every row of the block is data. Returns the number of rows inserted.

    • consolidate

      public int[] consolidate(int destRow, int destColumn, ConsolidateFunction function, Range... sources)
      Consolidate several equally-shaped source ranges (possibly on other sheets) into this sheet at (destRow, destColumn) using function, aggregating by position. Returns {rows, columns} written.

    • addSparkline

      public int addSparkline(String type, String dataRef, String locationRef)
      Add a sparkline group ("line", "column", or "stacked") that draws dataRef (e.g. "Sheet1!A1:A10") into the cell locationRef (e.g. "B1").

    • setSparklineStyle

      public boolean setSparklineStyle(int group, SparklineStyle style)
      Replaces the style (colors + point-highlight flags) of the group-th sparkline group — the styling counterpart of addSparkline(java.lang.String, java.lang.String, java.lang.String); read the current state back via sparklines() and SparklineGroup.style(). Returns whether the group index matched.

    • sparklineGroupCount

      public int sparklineGroupCount()
      Number of sparkline groups on this sheet.

    • sparklines

      public List<SparklineGroup> sparklines()
      All sparkline groups on this sheet (ECMA-376 Part 4 §18.3.1.32, x14:sparklineGroups): the group type, basic marker/highlight style, series color and each sparkline's data range and draw location. The read-side counterpart of addSparkline(String, String, String).

    • addShape

      public int addShape(String shapeType, String text, int fromRow, int fromCol, int toRow, int toCol)
      Add a drawing shape (e.g. "rect", "ellipse", "roundRect") with optional text, anchored over the cell rectangle (fromRow,fromCol)..(toRow,toCol).

    • groupShapes

      public int groupShapes(String name, int... shapeIndexes)
      Group existing shapes into one <xdr:grpSp> container (Excel's "Group"). shapeIndexes are this sheet's shape indexes; at least two ungrouped, non-group shapes are required. The members keep their indexes and the group is appended as a new shape entry whose anchor is the members' bounding box. Returns the group's shape index, or -1 when the set is not groupable.

    • ungroupShapes

      public boolean ungroupShapes(int shapeIndex)
      Dissolve a group created by groupShapes(java.lang.String, int...): members return to standalone emission and the group entry is removed. Returns whether shapeIndex was such a group (imported verbatim groups are not dissolvable — their children exist only inside the captured XML).

    • addTextBox

      public int addTextBox(String text, int fromRow, int fromCol, int toRow, int toCol)
      Add a text box (a rect shape carrying text); returns the new shape's index.

    • addConnector

      public int addConnector(String preset, int fromRow, int fromCol, int toRow, int toCol)
      Add a connector shape (<xdr:cxnSp>) with the given preset geometry name (e.g. "straightConnector1", "bentConnector3", "curvedConnector3", "line"), anchored over the cell rectangle (fromRow,fromCol)..(toRow,toCol). The connector shares the shape index space with addShape(java.lang.String, java.lang.String, int, int, int, int); shapeType(int) reports it as "connector:<preset>".

    • shapeCount

      public int shapeCount()
      Number of shapes on this sheet.

    • removeShape

      public boolean removeShape(int shapeIndex)
      Remove the shape at shapeIndex (0-based, the same index used by shapeType(int)); returns whether it existed.

    • shapeType

      public String shapeType(int shapeIndex)
      The geometry token of the shape at shapeIndex (e.g. "rect"). Connector shapes are reported as "connector:<preset>" (e.g. "connector:straightConnector1"); group containers as "group".

    • shapeText

      public String shapeText(int shapeIndex)
      The shape's text body, or null.

    • shapeFillColor

      public Color shapeFillColor(int shapeIndex)
      The shape's solid fill color, or null (no / non-RGB fill).

    • shapeLineColor

      public Color shapeLineColor(int shapeIndex)
      The shape's line (outline) color, or null.

    • shapeStyleXml

      public String shapeStyleXml(int shapeIndex)
      The raw inner XML of the shape's <xdr:style> theme style-matrix reference (the lnRef / fillRef / effectRef / fontRef children), or null when the shape has no such block. The reference is theme-relative, so it round-trips as long as the workbook theme is preserved.

    • shapeRotation

      public double shapeRotation(int shapeIndex)
      The shape's rotation in degrees (clockwise).

    • shapeFlip

      public boolean[] shapeFlip(int shapeIndex)
      {flipHorizontal, flipVertical}, or an empty array when out of range.

    • shapeAnchor

      public int[] shapeAnchor(int shapeIndex)
      {fromRow, fromCol, toRow, toCol}, or an empty array when out of range.

    • setShapeFillColor

      public void setShapeFillColor(int shapeIndex, Color color)
      Set (or clear with null) the shape's solid fill color.

    • setShapeLineColor

      public void setShapeLineColor(int shapeIndex, Color color)
      Set (or clear with null) the shape's line (outline) color.

    • setShapeStyleXml

      public void setShapeStyleXml(int shapeIndex, String xml)
      Set (or clear with null) the shape's <xdr:style> theme style-matrix reference from raw inner XML (the lnRef / fillRef / effectRef / fontRef children, without the enclosing <xdr:style> tags). Pair with shapeStyleXml(int) to carry a theme-relative fill / line / effect / font across a rebuild.

    • setShapeRotation

      public void setShapeRotation(int shapeIndex, double degrees)
      Set the shape's rotation in degrees (clockwise).

    • setShapeText

      public void setShapeText(int shapeIndex, String text)
      Set (or clear with null) the shape's text body.

    • setShapeFlip

      public void setShapeFlip(int shapeIndex, boolean flipHorizontal, boolean flipVertical)
      Set the shape's horizontal / vertical flip flags.

    • shapeHyperlink

      public String shapeHyperlink(int shapeIndex)
      The hyperlink URL attached to the shape via DrawingML hlinkClick, or null when the shape has no hyperlink.

    • setShapeHyperlink

      public void setShapeHyperlink(int shapeIndex, String url)
      Set (or clear with null) the shape's hyperlink URL. Saved as a drawing-level external hyperlink relationship plus the <a:hlinkClick r:id> element on the shape.

    • shapeAltText

      public String shapeAltText(int shapeIndex)
      The shape's alternative text (cNvPr/@descr), or null.

    • setShapeAltText

      public void setShapeAltText(int shapeIndex, String text)
      Set (or clear with null) the shape's alternative text.

    • shapeName

      public String shapeName(int shapeIndex)
      The shape's drawing name (<xdr:cNvPr name>, ECMA-376 Part 1 §20.5.2.16) — what Excel shows in the Name Box and what a macro uses to address the shape. A shape added through this SDK is given a generated one; null when there is no shape at that index.

    • setShapeName

      public boolean setShapeName(int shapeIndex, String name)
      Renames a shape. Returns false for an empty name or an index with no shape — a blank cNvPr/@name would leave the shape unreachable from both the Name Box and any macro.

    • renderChartToPng

      public byte[] renderChartToPng(int chartIndex, int width, int height)
      Render the chart at chartIndex to PNG image bytes at the given pixel size, or null if the index is out of range.

    • renderChartToSvg

      public String renderChartToSvg(int chartIndex, int width, int height)
      Render the chart at chartIndex to a standalone SVG document at the given pixel size, or null if the index is out of range.

      The vector counterpart of renderChartToPng(int, int, int): text comes out as <text> and the plot as paths, so the picture scales and prints at whatever resolution it is put on. The vector path draws the classic chart families (bar, column, line, pie, doughnut, scatter, area, radar, bubble, stock); another family produces a document with the frame and a comment naming the type rather than a drawing of it, so render those to PNG.