XlsName module

class XlsName.XlsName

Bases: XlsObject, INamedRange, IXLSRange

Represents a named range or defined name in an Excel workbook.

This class extends XlsObject and implements INamedRange and IXLSRange interfaces to provide functionality for working with named ranges, including accessing and manipulating range properties, formatting, and cell values.

Activate

Activates the named range and optionally scrolls to it.

Parameters:: scroll (bool) – True to scroll the worksheet to display the range; otherwise, False.
Returns:: The activated range.
Return type:: IXLSRange

AddComment() → ICommentShape

Adds a comment to the named range.

Returns:: The newly added comment.
Return type:: ICommentShape

AutoFitColumns(): Automatically adjusts the width of columns in the named range to fit their contents.

AutoFitRows(): Automatically adjusts the height of rows in the named range to fit their contents.

property BooleanValue: bool

Gets or sets the boolean value of the named range.

Returns:: The boolean value.
Return type:: bool

BorderAround

Adds a border around the named range using default line style and color.

This method applies a standard border around the outer edges of the named range.

BorderInside

Adds inside borders to the named range using default line style and color.

This method applies borders to the inner cell boundaries of the named range.

BorderNone()

Removes all borders from the named range.

This method clears both outside and inside borders from the range.

property Borders: IBorders

Gets the borders collection for the named range.

Returns:: The collection of borders.
Return type:: IBorders

property BuiltInStyle: BuiltInStyles

Gets or sets the built-in style for the named range.

Returns:: The built-in style.
Return type:: BuiltInStyles

property CellStyleName: str

Gets the name of the cell style applied to the named range.

Returns:: The name of the cell style applied to the named range.
Return type:: str

Clear

Clears specified aspects of the cells in the named range.

Parameters:: option (ExcelClearOptions) – The options specifying what to clear.

ClearContents()

Clears the contents of the cells in the named range.

This method removes values but leaves formatting intact.

Clone

Creates a copy of this named range with the specified parent object.

Parameters:: parent (SpireObject) – The parent object for the cloned range.
Returns:: The cloned named range.
Return type:: SpireObject

CollapseGroup(groupBy: GroupByType)

Collapses a group of rows or columns in the named range.

Parameters:: groupBy (GroupByType) – Specifies whether to collapse by rows or columns.

property Column: int

Gets the column index of the first cell in the named range.

Returns:: The zero-based column index.
Return type:: int

property ColumnGroupLevel: int

Gets the outline level for columns in the named range.

Returns:: The column group level.
Return type:: int

property ColumnWidth: float

Gets or sets the width of columns in the named range.

Returns:: The column width in characters.
Return type:: float

property Columns: ListXlsRanges

Gets the collection of columns in the named range.

Returns:: The collection of columns in the named range.
Return type:: ListXlsRanges

property Comment: ICommentShape

Gets the comment associated with the named range.

Returns:: The comment object.
Return type:: ICommentShape

property ConditionalFormats: ConditionalFormats

Gets the collection of conditional formats applied to the named range.

Returns:: The collection of conditional formats.
Return type:: ConditionalFormats

ConvertFullRowColumnName(version: ExcelVersion)

Converts the named range to a full row or column reference based on Excel version.

This method adjusts the named range reference to cover entire rows or columns according to the specified Excel version’s format.

Parameters:: version (ExcelVersion) – The Excel version to use for the conversion.

CopyTo(destination: IXLSRange) → IXLSRange

Copies the content and formatting of the named range to a destination range.

Parameters:: destination (IXLSRange) – The destination range to copy to.
Returns:: The destination range after the copy operation.
Return type:: IXLSRange

property Count: int

Gets the number of cells in the named range.

Returns:: The count of cells.
Return type:: int

property DataValidation: Validation

Gets the data validation rules applied to the named range.

Returns:: The data validation rules.
Return type:: Validation

property DateTimeValue: DateTime

Gets or sets the date/time value of the named range.

Returns:: The date/time value.
Return type:: DateTime

Delete()

Deletes the named range from the workbook.

This method removes the named range definition but does not affect the cells it refers to.

property EndCell: IXLSRange

Gets the cell at the bottom-right corner of the named range.

Returns:: The end cell of the named range.
Return type:: IXLSRange

property EntireColumn: IXLSRange

Gets a range representing all cells in the columns of the named range.

Returns:: The range representing the entire columns.
Return type:: IXLSRange

property EntireRow: IXLSRange

Gets a range representing all cells in the rows of the named range.

Returns:: The range representing the entire rows.
Return type:: IXLSRange

property EnvalutedValue: str

Gets the calculated value of a formula in the named range.

Returns:: The calculated value of the formula.
Return type:: str

property ErrorValue: str

Gets or sets the error value of the named range.

Returns:: The error value as a string.
Return type:: str

ExpandGroup

Expands a collapsed group of rows or columns in the named range.

Parameters:: groupBy (GroupByType) – Specifies whether to expand by rows or columns.

FindFirst

Finds the first cell in the named range containing the specified TimeSpan value.

Parameters:: findValue (TimeSpan) – The TimeSpan value to search for.
Returns:: The first cell containing the specified value, or None if not found.
Return type:: IXLSRange

property Formula: str

Gets or sets the formula of the named range in A1 notation.

Returns:: The formula string in A1 notation.
Return type:: str

property FormulaArray: str

Gets or sets the array formula of the named range.

Returns:: The array formula string.
Return type:: str

property FormulaArrayR1C1: str

Gets or sets the array formula of the named range in R1C1 notation.

Returns:: The array formula string in R1C1 notation.
Return type:: str

property FormulaBoolValue: bool

Gets or sets the boolean value of a formula in the named range.

Returns:: The boolean value of the formula.
Return type:: bool

property FormulaDateTime: DateTime

Gets or sets the DateTime value of a formula in the named range.

Returns:: The DateTime value of the formula.
Return type:: DateTime

property FormulaErrorValue: str

Gets or sets the error value of a formula in the named range.

Returns:: The error value of the formula as a string.
Return type:: str

property FormulaNumberValue: float

Gets the formula numeric value of the named range.

Returns:: The formula numeric value.
Return type:: float

property FormulaR1C1: str

Gets or sets the formula of the named range in R1C1 notation.

Returns:: The formula string in R1C1 notation.
Return type:: str

property FormulaStringValue: str

Gets the formula string value of the named range.

Returns:: The formula string value.
Return type:: str

FreezePanes()

Freezes panes at the position of the named range.

This method locks rows and columns to keep them visible while scrolling.

GetEnumerator() → IEnumerator

Gets an enumerator that can be used to iterate through the cells in the named range.

Returns:: An enumerator for iterating through the cells.
Return type:: IEnumerator

property HasBoolean: bool

Gets whether the named range contains a boolean value.

Returns:: True if the named range contains a boolean value; otherwise, False.
Return type:: bool

property HasDataValidation: bool

Gets whether the named range has data validation rules applied.

Returns:: True if the named range has data validation; otherwise, False.
Return type:: bool

property HasDateTime: bool

Gets whether the named range contains a DateTime value.

Returns:: True if the named range contains a DateTime value; otherwise, False.
Return type:: bool

property HasError: bool

Gets whether the named range has an error.

Returns:: True if the named range has an error; otherwise, False.
Return type:: bool

property HasExternalFormula: bool

Indicates if the current range has an external formula.

Returns:: True if the range has an external formula; otherwise, False.
Return type:: bool

property HasFormula: bool

Gets whether the named range contains a formula.

Returns:: True if the named range contains a formula; otherwise, False.
Return type:: bool

property HasFormulaArray: bool

Gets whether the named range has an array formula.

Returns:: True if the named range has an array formula; otherwise, False.
Return type:: bool

property HasFormulaBoolValue: bool

Checks if the named range has a boolean formula value.

Returns:: True if the named range has a boolean formula value; otherwise, False.
Return type:: bool

property HasFormulaDateTime: bool

Gets whether the named range has a date/time formula value.

Returns:: True if the named range has a date/time formula value; otherwise, False.
Return type:: bool

property HasFormulaErrorValue: bool

Checks if the named range has an error formula value.

Returns:: True if the named range has an error formula value; otherwise, False.
Return type:: bool

property HasFormulaNumberValue: bool

Gets whether the named range has a numeric formula value.

Returns:: True if the named range has a numeric formula value; otherwise, False.
Return type:: bool

property HasFormulaStringValue: bool

Gets whether the named range has a string formula value.

Returns:: True if the named range has a string formula value; otherwise, False.
Return type:: bool

property HasMerged: bool

Gets whether the named range contains merged cells.

Returns:: True if the range contains merged cells; otherwise, False.
Return type:: bool

property HasNumber: bool

Gets whether the named range has a numeric value.

Returns:: True if the named range has a numeric value; otherwise, False.
Return type:: bool

property HasRichText: bool

Gets whether the named range has rich text content.

Returns:: True if the named range has rich text content; otherwise, False.
Return type:: bool

property HasString: bool

Gets whether the named range has a string value.

Returns:: True if the named range has a string value; otherwise, False.
Return type:: bool

property HasStyle: bool

Gets whether the named range has a style applied.

Returns:: True if the named range has a style applied; otherwise, False.
Return type:: bool

property HorizontalAlignment: HorizontalAlignType

Gets or sets the horizontal alignment of the named range.

Returns:: The horizontal alignment setting.
Return type:: HorizontalAlignType

property HtmlString: str

Gets and sets the HTML string which contains data and some formattings in this cell.

Returns:: The HTML string representation of the cell content.
Return type:: str

property Hyperlinks: IHyperLinks

Gets the hyperlinks collection for the named range.

Returns:: The collection of hyperlinks.
Return type:: IHyperLinks

property IgnoreErrorOptions: IgnoreErrorType

Gets or sets the error options to ignore for the named range.

If the range is not a single cell, returns concatenated flags.

Returns:: The error options to ignore.
Return type:: IgnoreErrorType

property IndentLevel: int

Gets or sets the indent level for the named range.

Returns:: The indent level value.
Return type:: int

property Index: int

Gets the index of the named range in the collection.

Returns:: The zero-based index of the named range.
Return type:: int

Intersect(range: IXLSRange) → IXLSRange

Gets the range that represents the intersection of the named range and another range.

Parameters:: range (IXLSRange) – The range to intersect with.
Returns:: The range representing the intersection.
Return type:: IXLSRange

property IsBlank: bool

Gets whether the named range contains blank cells.

Returns:: True if the named range contains blank cells; otherwise, False.
Return type:: bool

property IsBuiltIn: bool

Gets whether the named range is a built-in name.

Returns:: True if the named range is a built-in name; otherwise, False.
Return type:: bool

property IsExternName: bool

Gets whether the named range is an external name.

Returns:: True if the named range is an external name; otherwise, False.
Return type:: bool

property IsFormulaHidden: bool

Gets or sets whether the formula in the named range is hidden.

Returns:: True if the formula is hidden; otherwise, False.
Return type:: bool

property IsFunction: bool

Gets whether the named range is a function.

Returns:: True if the named range is a function; otherwise, False.
Return type:: bool

property IsGroupedByColumn: bool

Gets whether the named range is grouped by columns.

Returns:: True if the named range is grouped by columns; otherwise, False.
Return type:: bool

property IsGroupedByRow: bool

Gets whether the named range is grouped by rows.

Returns:: True if the named range is grouped by rows; otherwise, False.
Return type:: bool

property IsInitialized: bool

Gets whether the named range is initialized.

Returns:: True if the named range is initialized; otherwise, False.
Return type:: bool

property IsLocal: bool

Gets whether the named range is local to a specific worksheet.

Returns:: True if the named range is local to a worksheet; False if it’s workbook-level.
Return type:: bool

property IsStringsPreserved: bool

Indicates whether all values in the range are preserved as strings.

Returns:: True if values are preserved as strings; otherwise, False.
Return type:: bool

property IsWrapText: bool

Gets or sets whether text is wrapped within the cells in the named range.

Returns:: True if text wrapping is enabled; otherwise, False.
Return type:: bool

property LastColumn: int

Gets the index of the last column of the named range.

Returns:: The index of the last column of the named range.
Return type:: int

property LastRow: int

Gets the index of the last row of the named range.

Returns:: The index of the last row of the named range.
Return type:: int

Merge: Merges all cells in the named range into a single cell.

property MergeArea: IXLSRange

Gets the range that represents the merged area containing the named range.

Returns:: The merged range.
Return type:: IXLSRange

property Name: str

Gets or sets the name of the named range.

Returns:: The name of the named range.
Return type:: str

property NameLocal: str

Gets or sets the localized name of the named range.

Returns:: The localized name of the named range.
Return type:: str

property NumberFormat: str

Gets the number format string of the named range.

Returns:: The number format string of the named range.
Return type:: str

property NumberText: str

Gets the text representation of the numeric value in the named range.

Returns:: The text representation of the numeric value.
Return type:: str

property NumberValue: float

Gets the numeric value of the named range.

Returns:: The numeric value of the named range.
Return type:: float

property RangeAddress: str

Gets the address of the named range in A1 notation.

Returns:: The address of the named range in A1 notation.
Return type:: str

property RangeAddressLocal: str

Gets the localized address of the named range in A1 notation.

Returns:: The localized address of the named range in A1 notation.
Return type:: str

property RangeGlobalAddress: str

Gets the global address of the named range.

Returns:: The global address of the named range, including the worksheet name.
Return type:: str

property RangeGlobalAddress2007: str

Gets the global address of the named range in Excel 2007 format.

Returns:: The global address of the named range in Excel 2007 format.
Return type:: str

property RangeR1C1Address: str

Gets the address of the named range in R1C1 notation.

Returns:: The address of the named range in R1C1 notation.
Return type:: str

property RangeR1C1AddressLocal: str

Gets the localized address of the named range in R1C1 notation.

Returns:: The localized address of the named range in R1C1 notation.
Return type:: str

property RefersToRange: IXLSRange

Gets or sets the cell range that this named range refers to.

Returns:: The cell range that this named range refers to.
Return type:: IXLSRange

property RichText: IRichTextString

Gets the rich text formatting for the named range.

Returns:: The rich text formatting object.
Return type:: IRichTextString

property Row: int

Gets the index of the first row of the named range.

Returns:: The index of the first row of the named range.
Return type:: int

property RowGroupLevel: int

Gets the outline level of the row in the named range.

Returns:: The outline level of the row in the named range.
Return type:: int

property RowHeight: float

Gets the height of the row in the named range.

Returns:: The height of the row in the named range.
Return type:: float

property Rows: ListXlsRanges

Gets the collection of rows in the named range.

Returns:: The collection of rows in the named range.
Return type:: ListXlsRanges

property Scope: str

Gets the scope of the named range (workbook or worksheet level).

Returns:: The scope of the named range.
Return type:: str

SetIndex

Sets the index of the named range in the collection.

This method changes the position of the named range in the collection.

Parameters:: index (int) – The new index position for the named range.

property Style: IStyle

Gets the style applied to the named range.

Returns:: The style applied to the named range.
Return type:: IStyle

property Text: str

Gets the text value of the named range.

Returns:: The text value of the named range.
Return type:: str

property TimeSpanValue: TimeSpan

Gets the TimeSpan value of the named range.

Returns:: The TimeSpan value of the named range.
Return type:: TimeSpan

UnMerge()

Unmerges previously merged cells in the named range.

This method separates a merged cell into individual cells.

property Value: str

Gets or sets the value of the named range as a string.

Returns:: The value of the named range.
Return type:: str

property Value2: SpireObject

Gets the value of the named range as a SpireObject.

This property can return different types based on the cell content.

Returns:: The value of the named range as an object.
Return type:: SpireObject

property ValueR1C1: str

Gets the formula of the named range in R1C1 notation.

Returns:: The formula in R1C1 notation.
Return type:: str

property VerticalAlignment: VerticalAlignType

Gets the vertical alignment of the named range.

Returns:: The vertical alignment of the named range.
Return type:: VerticalAlignType

property Visible: bool

Gets or sets whether the named range is visible in the workbook.

Returns:: True if the named range is visible; otherwise, False.
Return type:: bool

property Worksheet: IWorksheet

Gets the worksheet containing the named range.

Returns:: The worksheet that contains the named range.
Return type:: IWorksheet

get_Item

Gets the cell at the specified row and column in the named range.

Parameters:

row (int) – The row index.
column (int) – The column index.

Returns:

The cell at the specified row and column.

Return type:

IXLSRange

set_Item(row: int, column: int, value: IXLSRange)

Sets the cell at the specified row and column in the named range.

Parameters:

row (int) – The row index.
column (int) – The column index.
value (IXLSRange) – The cell to set.