Package io.keikai.axyra.sheets

Class Cell

java.lang.Object
io.keikai.axyra.sheets.Cell
public final class Cell extends Object
One cell of a sheet: a lightweight (sheet, row, column) view, 0-based, that holds no native resource. Get one with Sheet.cell(int, int).

Each accessor makes one or more engine calls; setDate(java.time.LocalDate) makes several. For more than a few cells, use the bulk methods of Range: Range.values(), Range.setValues(io.keikai.axyra.sheets.CellValue[][]), Range.setNumbers(double[]) and Range.setFormulas(java.lang.String[][]) make one engine call for the whole rectangle. 


 Cell c = sheet.cell(0, 0);                 // A1
 c.setValue(CellValue.number(42));
 sheet.cell(0, 1).setFormula("A1*2");       // B1
 CellValue result = sheet.cell(0, 1).value(); // 84
 String shown = c.formattedText();          // "42"

Creating a cell off the grid throws IndexOutOfBoundsException.

  • Method Details

    • row

      public int row()
      The 0-based row index.

    • col

      public int col()
      The 0-based column index.

    • value

      public CellValue value()
      Returns the cell's value. A formula cell returns its current result; pending writes are recalculated first. For many cells, use Range.values().
      Returns:
      the value; CellValue.BLANK for an empty cell, never null

    • formattedText

      public String formattedText()
      The cell's display text: its value rendered through the cell style's number format under the workbook display locale (Workbook.setLocale(java.lang.String); default en-US). Blank cells return an empty string.
      Returns:
      the formatted text, never null

    • setValue

      public void setValue(CellValue value)
      Sets this cell's value and drops any formula. The cell keeps its style, comment and hyperlink. CellValue.BLANK or null clears the value. For many cells, use Range.setValues(io.keikai.axyra.sheets.CellValue[][]).
      Parameters:
      value - the new value, or null for blank
      Throws:
      IllegalArgumentException - if value is a CellValue.Array

    • setDate

      public void setDate(LocalDate date)
      Sets a date. The value becomes the Excel serial for date in the workbook's date system (1900 or 1904), and any formula is dropped. When the cell's number format is General, it becomes yyyy-mm-dd; any other format is kept. In the 1900 system, a date before 1900-03-01 gets a serial one greater than Excel's, because Excel counts the non-existent 1900-02-29. Several engine calls: the value write, a style read and, when the format changes, a style write.
      Parameters:
      date - the date; must not be null

    • setDateTime

      public void setDateTime(LocalDateTime dateTime)
      Sets a date and time. The serial counts days in the workbook's date system, plus the time of day as a fraction; seconds are kept and fractions of a second are dropped. Any formula is dropped. When the cell's number format is General, it becomes yyyy-mm-dd hh:mm:ss; any other format is kept. Several engine calls, as for setDate(java.time.LocalDate).
      Parameters:
      dateTime - the date and time, without a time zone; must not be null

    • dateValue

      public LocalDate dateValue()
      Returns the cell's value as a date: the whole-day part of the serial, in the workbook's date system. The number format is not checked, so any number converts.
      Returns:
      the date, or null when the value is not a number

    • dateTimeValue

      public LocalDateTime dateTimeValue()
      Returns the cell's value as a date and time, in the workbook's date system, with the day fraction rounded to the nearest second. The number format is not checked, so any number converts.
      Returns:
      the date and time, or null when the value is not a number

    • formula

      public String formula()
      Returns the cell's formula text, without the leading =. It reads the same for a workbook built here and one opened from a file: without array-formula braces and without the _xlfn. prefixes the file format adds to newer functions. For many cells, use Range.formulas().
      Returns:
      the formula, or null when the cell has no formula

    • setFormula

      public void setFormula(String formula)
      Sets this cell's formula. A leading = is optional; an empty string clears the formula and value. The cell keeps its style, comment and hyperlink. A formula that returns an array spills from this cell, as in Excel 365. For many cells, use Range.setFormulas(java.lang.String[][]) or Range.setFormula(java.lang.String).
      Parameters:
      formula - the formula in en-US form; must not be null
      Throws:
      AxyraFormulaException - if the formula does not parse; the cell is not changed
      NullPointerException - if formula is null

    • setFormulaLocalized

      public void setFormulaLocalized(String formula, String locale)
      Set the cell's formula written in a locale's display form — translated function names (e.g. German SUMME, French SOMME) and the ; argument separator. It is translated to the en-US canonical form (English names, , separator) before storage. locale is a language tag such as "de" or "fr-FR"; an unknown locale stores the formula unchanged. Function names inside string literals are never translated. A leading = is optional.

      The language part of the tag picks the function names. German, French, Spanish, Italian, Portuguese and Dutch are translated, names with non-ASCII letters such as ZÄHLENWENN included; any other language is stored unchanged. A number's decimal comma becomes a period (1,5 is stored as 1.5), except for es-MX, es-US, es-419, de-CH, de-LI and it-CH, which write a period. Every ; outside a string literal or a quoted sheet name becomes ,, including the row separator of an array constant.

      Parameters:
      formula - the formula in the locale's display form
      locale - a language tag such as "de" or "fr-FR"
      Throws:
      AxyraFormulaException - if the translated formula does not parse

    • formulaLocalized

      public String formulaLocalized(String locale)
      The cell's formula rendered in locale's display form (translated function names + ; separator), or null for a non-formula cell. The inverse of setFormulaLocalized(java.lang.String, java.lang.String), with the same languages; any other language returns the en-US form.
      Parameters:
      locale - a language tag such as "de" or "fr-FR"
      Returns:
      the localized formula without a leading =, or null when the cell has no formula

    • clear

      public void clear()
      Clears this cell's value and formula. The style, comment and hyperlink stay; see removeComment() and removeHyperlink().

    • setRichText

      public void setRichText(RichText richText)
      Sets this cell to rich text: one string with per-run font overrides. Any formula is dropped; the cell keeps its style, comment and hyperlink. The plain value is the runs' text joined. Read it back with richText().
      Parameters:
      richText - the text runs; must not be null

    • richText

      public RichText richText()
      Returns the cell's rich text with per-run formatting. The returned value can be passed back to setRichText(io.keikai.axyra.sheets.content.RichText) unchanged.
      Returns:
      a snapshot of the runs, or null when the cell is not rich text

    • richRunCount

      public int richRunCount()
      Returns the number of rich-text runs in this cell, or 0 when the cell is not rich text. Use Range.contentFlags() to find rich-text cells in bulk.

    • style

      public CellStyle style()
      Returns the cell's resolved style: the workbook default style for a cell that has none. Two engine calls.
      Returns:
      a snapshot; edit it with toBuilder() and pass it to setStyle(io.keikai.axyra.sheets.style.CellStyle)

    • setStyle

      public void setStyle(CellStyle style)
      Replaces this cell's style with style. Attributes that style leaves unset take their defaults; they are not merged with the old style. To change one attribute, start from style().toBuilder(). For many cells, use Range.setStyle(io.keikai.axyra.sheets.style.CellStyle).
      Parameters:
      style - the style to apply; must not be null

    • comment

      public Comment comment()
      Returns the cell's plain-text comment (Excel's note). Threaded comments are read with threadedComments().
      Returns:
      a snapshot of the author and text, or null when the cell has no note

    • setComment

      public void setComment(String author, String text)
      Attaches a plain-text comment (Excel's note) to this cell, or replaces the existing one. A replaced note keeps its box size, visibility, fill and text alignment; set them with setCommentLayout(double, double, boolean). The cell's value is not changed. For per-run fonts use setRichComment(java.lang.String, io.keikai.axyra.sheets.content.CommentRun...); for an Excel 365 conversation use addThreadedComment(java.lang.String, java.lang.String).
      Parameters:
      author - the author name shown with the note
      text - the note text

    • setCommentLayout

      public boolean setCommentLayout(double widthPt, double heightPt, boolean visible)
      Sets the box of this cell's existing note: its size and whether it stays visible without hovering (Excel's "Show Comment"). Imported note geometry is regenerated from these values on the next save. Does nothing when the cell has no note.
      Parameters:
      widthPt - box width in points (1/72 inch)
      heightPt - box height in points (1/72 inch)
      visible - true to show the note at all times
      Returns:
      true if the cell had a note, false otherwise

    • setComment

      public void setComment(Comment comment)
      Attaches or replaces this cell's plain-text comment (note) with the author and text of comment. Same as setComment(String, String).
      Parameters:
      comment - the note; must not be null

    • setRichComment

      public void setRichComment(String author, CommentRun... runs)
      Attaches a rich-text comment (note) to this cell, or replaces the existing one. Each CommentRun carries per-run font overrides (ECMA-376 Part 1 §18.7.7). The note's plain Comment.text() becomes the run texts joined. Use setComment(String, String) for plain text.
      Parameters:
      author - the author name shown with the note
      runs - the text runs, at least one
      Throws:
      AxyraException - when no runs are given or a run has empty text

    • commentRuns

      public List<CommentRun> commentRuns()
      Returns the rich-text runs of this cell's note.
      Returns:
      a new list of runs; empty for a plain-text note, or null when the cell has no note

    • removeComment

      public void removeComment()
      Removes this cell's plain-text comment (note), if any. Threaded comments are removed with removeThreadedComment(java.lang.String). The value and style are not changed.

    • threadedComments

      public List<ThreadedComment> threadedComments()
      Returns this cell's Excel 365 comment threads. Each root ThreadedComment carries its replies.
      Returns:
      a new list; empty when the cell has no thread

    • addThreadedComment

      public String addThreadedComment(String author, String text)
      Starts a new Excel 365 comment thread on this cell. The author is added to the workbook's list of persons when new. Use setComment(String, String) for a classic note.
      Parameters:
      author - the author name
      text - the comment text
      Returns:
      the generated comment id, a GUID in braces; pass it to addThreadedReply(java.lang.String, java.lang.String, java.lang.String)

    • addThreadedReply

      public String addThreadedReply(String parentId, String author, String text)
      Reply to the thread containing parentId (a root or reply id; replies attach to the thread root, like Excel).

      The id is looked up on the whole sheet, not only on this cell.

      Parameters:
      parentId - the id of a comment in the thread
      author - the author name
      text - the reply text
      Returns:
      the new reply id, or null when no comment on this sheet has parentId

    • setThreadedCommentResolved

      public boolean setThreadedCommentResolved(String id, boolean resolved)
      Resolves or reopens the thread containing id.

      The id is looked up on the whole sheet, not only on this cell.

      Parameters:
      id - the id of a comment in the thread
      resolved - true to resolve, false to reopen
      Returns:
      true if a comment on this sheet has id

    • removeThreadedComment

      public boolean removeThreadedComment(String id)
      Remove the comment with id — a root id removes its whole thread, a reply id removes just that reply.

      The id is looked up on the whole sheet, not only on this cell.

      Parameters:
      id - the id of the comment to remove
      Returns:
      true if a comment was removed

    • hyperlink

      public Hyperlink hyperlink()
      Returns the cell's hyperlink. Use Range.contentFlags() to find linked cells in bulk.
      Returns:
      a snapshot of the link, or null when the cell has none

    • setHyperlink

      public void setHyperlink(String url)
      Attaches a hyperlink to this cell, or replaces the existing one. Same as setHyperlink(Hyperlink.url(url)). The cell's value is not changed, so set the value as well when the cell is empty.
      Parameters:
      url - the link address: a URL, a file path or an in-workbook reference such as "Sheet2!A1"

    • setHyperlink

      public void setHyperlink(Hyperlink link)
      Attaches a hyperlink to this cell, or replaces the existing one. The cell's value is not changed: the link's display text is stored with the link but is not written into the cell, so set the value as well when the cell is empty. The address may be a URL, a file path or an in-workbook reference such as "Sheet2!A1"; its kind is detected from the text.
      Parameters:
      link - the link; must not be null

    • removeHyperlink

      public void removeHyperlink()
      Removes this cell's hyperlink, if any. The value and style are not changed. To remove many, use Range.clearHyperlinks().