Working with Navigation

Overview

This guide shows how to move around a loaded workbook: selecting worksheets, resolving cells by name or index, reading merged ranges, and following named ranges and hyperlinks. The entry points are Workbook.getWorksheets(), Worksheet.getCells(), Workbook.getDefinedNames(), and Worksheet.getHyperlinks().

Navigating Worksheets

WorksheetCollection resolves a sheet by zero-based index or by name, and tracks which sheet is active:

import org.aspose.cells_foss.Workbook;
import org.aspose.cells_foss.Worksheet;
import org.aspose.cells_foss.WorksheetCollection;

try (Workbook workbook = new Workbook()) {
    WorksheetCollection sheets = workbook.getWorksheets();
    sheets.add("Summary");
    sheets.add("Detail");

    Worksheet byIndex = sheets.get(1);
    Worksheet byName = sheets.get("Summary");

    sheets.setActiveSheetName("Summary");
    System.out.println("Active sheet: " + sheets.getActiveSheetName());
    System.out.println("Sheet count: " + sheets.getCount());
}

Navigating Cells

Cells.get() resolves a cell either by its A1-style name or by zero-based row/column indices — both return the same Cell:

import org.aspose.cells_foss.Cell;
import org.aspose.cells_foss.Worksheet;
import org.aspose.cells_foss.WorksheetCollection;

WorksheetCollection sheets = workbook.getWorksheets();
Worksheet sheet = sheets.get(0);
Cell byName = sheet.getCells().get("B2");
Cell byIndex = sheet.getCells().get(1, 1); // row 1, column 1 -> B2

Merged Ranges

Merge a block of cells with Cells.merge(), and inspect existing merges through getMergedCells(), which returns a List<CellArea>:

import org.aspose.cells_foss.CellArea;
import org.aspose.cells_foss.Worksheet;
import org.aspose.cells_foss.WorksheetCollection;
import java.util.List;

WorksheetCollection sheets = workbook.getWorksheets();
Worksheet sheet = sheets.get(0);
sheet.getCells().merge(0, 0, 1, 3); // A1:D1

List<CellArea> merged = sheet.getCells().getMergedCells();
for (CellArea area : merged) {
    System.out.println("Merged: row " + area.getFirstRow() + ", col " + area.getFirstColumn()
        + ", rows " + area.getTotalRows() + ", cols " + area.getTotalColumns());
}

Named Ranges

Workbook.getDefinedNames() holds workbook-level named ranges. Each DefinedName pairs a name with a formula (typically a cell reference):

import org.aspose.cells_foss.DefinedNameCollection;
import org.aspose.cells_foss.Workbook;

try (Workbook workbook = new Workbook()) {
    DefinedNameCollection names = workbook.getDefinedNames();
    names.add("TaxRate", "Sheet1!$B$1");

    System.out.println("Defined names: " + names.getCount());
    System.out.println(names.get(0).getName() + " = " + names.get(0).getFormula());
}

Hyperlinks

Worksheet.getHyperlinks() returns the sheet’s HyperlinkCollection. Add a link over a cell range with an address, and optional display text and screen tip:

import org.aspose.cells_foss.HyperlinkCollection;
import org.aspose.cells_foss.Worksheet;
import org.aspose.cells_foss.WorksheetCollection;

WorksheetCollection sheets = workbook.getWorksheets();
Worksheet sheet = sheets.get(0);
HyperlinkCollection links = sheet.getHyperlinks();
links.add("A1", "B1", "https://example.com", "Visit example.com", "Opens in browser");

System.out.println("Hyperlink count: " + links.getCount());
System.out.println("Address: " + links.get(0).getAddress());

Tips and Best Practices

WorksheetCollection.get() is overloaded for both int index and String name — pick whichever is stable in your workflow; sheet order can change if sheets are inserted or removed.
Cells.get(row, column) uses zero-based indices; Cells.get(cellName) uses the familiar A1 notation — both resolve to the same underlying cell.
Check getMergedCells() before writing to a range you did not create yourself — writing into a cell inside an existing merge can produce unexpected results.
A DefinedName with no localSheetIndex set is workbook-scoped; set setLocalSheetIndex() to scope it to a single sheet.

Common Issues

Issue	Cause	Fix
`WorksheetCollection.get(name)` cannot find a sheet	Sheet name mismatch (case or exact text)	Confirm the exact name via `Worksheet.getName()` before lookup
Hyperlink text differs from what was set	`textToDisplay` left at its default	Pass `textToDisplay` explicitly to `HyperlinkCollection.add(...)`
Merged range appears larger than expected	`Cells.merge()` called more than once over overlapping areas	Inspect `getMergedCells()` first to confirm no existing overlap

FAQ

Can I navigate to a cell outside the current merged range?

Yes — Cells.get() resolves any cell address regardless of merge state; only writing inside an existing merge requires care.

Are defined names case-sensitive?

The library stores the name exactly as provided to DefinedNameCollection.add(); treat lookups as case-sensitive unless you control both the writer and reader.

Does removing a worksheet renumber defined names scoped to a sheet?

DefinedName.getLocalSheetIndex() stores a raw sheet index; removing a sheet does not automatically re-point names scoped to a different index, so re-validate sheet-scoped names after structural changes.

API Reference Summary

Class/Method	Description
`WorksheetCollection.get(index)` / `get(name)`	Resolves a `Worksheet`
`WorksheetCollection.setActiveSheetIndex` / `setActiveSheetName`	Sets the active sheet
`Cells.get(cellName)` / `get(row, column)`	Resolves a `Cell`
`Cells.merge(firstRow, firstColumn, totalRows, totalColumns)`	Merges a cell range
`Cells.getMergedCells()`	Returns existing merged `CellArea` ranges
`DefinedNameCollection.add(name, formula)`	Adds a named range
`HyperlinkCollection.add(...)`	Adds a hyperlink over a cell range