XlsWorkbook module

class XlsWorkbook.XlsWorkbook

Bases: XlsObject, IWorkbook

Activate()

Activates the workbook window.

property ActiveSheet: IWorksheet
property ActiveSheetIndex: int
AddFont(fontToAdd: IFont) → IFont

Adds a font to the workbook and returns the new font object.

Parameters:

fontToAdd (IFont) – The font to add.

Returns:

The added font object.

Return type:

IFont

property AddInFunctions: IAddInFunctions

Gets the collection of add-in functions in the workbook.

Returns:

The collection of add-in functions.

Return type:

IAddInFunctions

property Allow3DRangesInDataValidation: bool

Gets or sets whether 3D ranges are allowed in data validation.

Returns:

True if 3D ranges are allowed, otherwise False.

Return type:

bool

property ArgumentsSeparator: str

Gets the separator used for function arguments in the workbook.

Returns:

The arguments separator character.

Return type:

str

property Author: str

Gets or sets the author of the workbook.

Returns:

The name of the workbook author.

Return type:

str

property BuiltInDocumentProperties: IBuiltInDocumentProperties

Gets the collection of built-in document properties.

Returns:

The collection of built-in document properties.

Return type:

IBuiltInDocumentProperties

property Charts: ICharts

Gets the collection of charts in the workbook.

Returns:

The collection of charts.

Return type:

ICharts

Clone() → IWorkbook

Clones the workbook and returns a new workbook object.

Returns:

A new workbook object that is a copy of the current workbook.

Return type:

IWorkbook

Close

Closes the workbook and saves changes to the specified file.

Parameters:

Filename (str) – The file name to save changes to.

property CodeName: str
ContainsFont(font: XlsFont) → bool

Checks if the workbook contains a specific font.

Parameters:

font (XlsFont) – The font to check for.

Returns:

True if the font is found, otherwise False.

Return type:

bool

CopyToClipboard()

Copies the workbook to the clipboard.

CreateFont

Creates a new font object.

Returns:

The new font object.

Return type:

IFont

CreateTemplateMarkersProcessor() → IMarkersDesigner

Creates and returns a template markers processor for the workbook.

Returns:

The template markers processor instance.

Return type:

IMarkersDesigner

property CurrentHeaderId: int

Gets or sets the current header ID in the workbook.

Returns:

The current header ID.

Return type:

int

property CurrentObjectId: int

Gets or sets the current object ID in the workbook.

Returns:

The current object ID.

Return type:

int

property CurrentShapeId: int

Gets or sets the current shape ID in the workbook.

Returns:

The current shape ID.

Return type:

int

property CustomDocumentProperties: ICustomDocumentProperties

Gets the collection of custom document properties.

Returns:

The collection of custom document properties.

Return type:

ICustomDocumentProperties

static DEF_BAD_SHEET_NAME() → str

Gets the placeholder name used for invalid sheet names.

Returns:

Default bad sheet name placeholder.

Return type:

str

static DEF_COMENT_PARSE_COLOR() → Color

Gets the default color used for parsing comments.

Returns:

The default comment parse color.

Return type:

Color

static DEF_FIRST_USER_COLOR() → int

Gets the index of the first user-modifiable color in the palette.

Returns:

Index of the first user color (8 in default Excel palette).

Return type:

int

property DataConns: DataConnections

Gets the collection of data connections in the workbook.

Returns:

The collection of data connections.

Return type:

DataConnections

property Date1904: bool
DecodeName(name: str) → str

Decodes the specified name string.

Parameters:

name (str) – The name to decode.

Returns:

The decoded name string.

Return type:

str

property DefaultXFIndex: int

Gets or sets the default XF (extended format) index in the workbook.

Returns:

The default XF index.

Return type:

int

property DetectDateTimeInValue: bool

Gets or sets whether to automatically detect date/time values in cell values.

Returns:

True if date/time detection is enabled, otherwise False.

Return type:

bool

property DisableMacrosStart: bool

Gets or sets whether macros are disabled when the workbook starts.

Returns:

True if macros are disabled on startup, otherwise False.

Return type:

bool

property DisplayWorkbookTabs: bool

Gets or sets whether to display workbook tabs.

Returns:

True if workbook tabs are displayed, otherwise False.

Return type:

bool

property DisplayedTab: int

Gets or sets the index of the currently displayed tab.

Returns:

The index of the displayed tab.

Return type:

int

Dispose()

Releases all resources used by the workbook.

EncodeName(strName: str) → str

Encodes the specified name string.

Parameters:

strName (str) – The name to encode.

Returns:

The encoded name string.

Return type:

str

Gets the collection of external links in the workbook.

Returns:

The collection of external links.

Return type:

ExternalLinkCollection

FileWidthToPixels(fileWidth: float) → float

Converts a file width value to a pixel value.

Parameters:

fileWidth (float) – The file width value to convert.

Returns:

The corresponding pixel value.

Return type:

float

FindOne

Finds a range in the workbook that contains the specified value.

Parameters:

  • findValue (float) – The value to find.

  • flags (FindType) – The flags for the search.

Returns:

The range that contains the specified value.

Return type:

IXLSRange

property FirstCharSize: int

Gets or sets the size of the first character in the workbook.

Returns:

The size of the first character.

Return type:

int

property FullFileName: str

Gets the full path and name of the workbook file.

Returns:

The complete file path and name.

Return type:

str

GetBookIndex(referenceIndex: int) → int

Gets the book index for the specified reference index.

Parameters:

referenceIndex (int) – The reference index to look up.

Returns:

The corresponding book index.

Return type:

int

GetMaxDigitWidth() → float

Gets the maximum digit width for the workbook.

Returns:

The maximum digit width.

Return type:

float

GetNearestColor

Gets the nearest matching Excel color for the specified color.

Parameters:

color (Color) – The color to find the nearest match for.

Returns:

The nearest matching Excel color.

Return type:

ExcelColors

GetPaletteColor(color: ExcelColors) → Color

Gets the Color object corresponding to the specified Excel color.

Parameters:

color (ExcelColors) – The Excel color to get the Color object for.

Returns:

The Color object corresponding to the Excel color.

Return type:

Color

property HasDuplicatedNames: bool

Gets or sets whether the workbook contains duplicate named ranges.

Returns:

True if the workbook has duplicate names, otherwise False.

Return type:

bool

property HasMacros: bool

Gets whether the workbook contains macros.

Returns:

True if the workbook has macros, otherwise False.

Return type:

bool

property InnerAddInFunctions: XlsAddInFunctionsCollection

Gets the collection of add-in functions in the workbook.

Returns:

The collection of add-in functions.

Return type:

XlsAddInFunctionsCollection

property InnerFonts: XlsFontsCollection

Gets the collection of fonts in the workbook.

Returns:

The collection of fonts.

Return type:

XlsFontsCollection

property IsCellProtection: bool

Gets whether cell protection is enabled in the workbook.

Returns:

True if cell protection is enabled, otherwise False.

Return type:

bool

property IsDisplayPrecision: bool

Gets or sets whether to display values with full precision.

Returns:

True if full precision display is enabled, otherwise False.

Return type:

bool

IsExternalReference(reference: int) → bool

Determines whether the specified reference is an external reference.

Parameters:

reference (int) – The reference to check.

Returns:

True if the reference is external, otherwise False.

Return type:

bool

IsFormatted(xfIndex: int) → bool

Checks if the specified XF index is formatted.

Parameters:

xfIndex (int) – The XF index to check.

Returns:

True if formatted, otherwise False.

Return type:

bool

property IsHScrollBarVisible: bool

Gets or sets whether the horizontal scroll bar is visible.

Returns:

True if the horizontal scroll bar is visible, otherwise False.

Return type:

bool

property IsLoaded: bool

Gets whether the workbook is currently loaded.

Returns:

True if the workbook is loaded, otherwise False.

Return type:

bool

property IsRightToLeft: bool

Gets or sets whether the workbook uses right-to-left text direction.

Returns:

True if right-to-left text direction is enabled, otherwise False.

Return type:

bool

property IsVScrollBarVisible: bool

Indicates whether the vertical scroll bar is visible in the workbook window.

Returns:

True if the vertical scroll bar is visible, otherwise False.

Return type:

bool

property IsWindowProtection: bool

Indicates whether window protection is enabled for the workbook.

Returns:

True if window protection is enabled, otherwise False.

Return type:

bool

property Loading: bool

Indicates whether the workbook is currently loading.

Returns:

True if the workbook is loading, otherwise False.

Return type:

bool

property MaxColumnCount: int

Gets the maximum number of columns supported by the workbook.

Returns:

The maximum column count.

Return type:

int

property MaxDigitWidth: float

Gets the maximum digit width used in the workbook.

Returns:

The maximum digit width.

Return type:

float

property MaxIndent: int

Gets the maximum indent level allowed in the workbook.

Returns:

The maximum indent level.

Return type:

int

property MaxRowCount: int

Gets the maximum number of rows supported by the workbook.

Returns:

The maximum row count.

Return type:

int

property MaxXFCount: int

Gets the maximum number of XF records allowed in the workbook.

Returns:

The maximum XF count.

Return type:

int

property Names: INameRanges

Gets the collection of named ranges in the workbook.

Returns:

The collection of named ranges.

Return type:

INameRanges

property ObjectCount: int

Gets the total number of objects in the workbook.

Returns:

The total number of objects.

Return type:

int

property OleSize: IXLSRange

Gets or sets the OLE size range of the workbook.

Returns:

The OLE size range.

Return type:

IXLSRange

property Palette: List[Color]
property PasswordToOpen: str

Gets the password required to open the workbook, if set.

Returns:

The password to open the workbook.

Return type:

str

PixelsToWidth(pixels: float) → float

Converts a pixel value to a column width value.

Parameters:

pixels (float) – The pixel value to convert.

Returns:

The corresponding column width.

Return type:

float

Protect

Protects the workbook with specified window and content protection settings.

Parameters:

  • bIsProtectWindow (bool) – Whether to protect the workbook window.

  • bIsProtectContent (bool) – Whether to protect the workbook content.

property ReadOnly: bool

Indicates whether the workbook is read-only.

Returns:

True if the workbook is read-only, otherwise False.

Return type:

bool

property ReadOnlyRecommended: bool

Indicates whether the workbook is read-only recommended.

Returns:

True if the workbook is read-only recommended, otherwise False.

Return type:

bool

Replace

Replaces all occurrences of a specified value with a new value in the workbook.

Parameters:

  • oldValue (str) – The value to replace.

  • newValue (str) – The new value.

ResetPalette()

Resets the workbook’s color palette to its default state. This will restore all colors to their original Excel default values.

property RowSeparator: str

Gets the row separator used in the workbook.

Returns:

The row separator.

Return type:

str

Save()

Saves the workbook using its current file name and format. If the workbook hasn’t been saved before, this will throw an exception.

SaveAs

Saves the workbook to a stream using a specified separator.

Parameters:

  • stream (Stream) – The stream to save the workbook to.

  • separator (str) – The separator to use for the workbook.

SaveAsEmfStream(sheetIndex: int, EmfStream: Stream, firstRow: int, firstColumn: int, lastRow: int, lastColumn: int)

Saves the specified range of the workbook as an EMF stream.

Parameters:

  • sheetIndex (int) – The index of the sheet to save.

  • EmfStream (Stream) – The stream to save the EMF image to.

  • firstRow (int) – The first row of the range to save.

  • firstColumn (int) – The first column of the range to save.

  • lastRow (int) – The last row of the range to save.

  • lastColumn (int) – The last column of the range to save.

SaveAsHtml(fileName: str, saveOption: HTMLOptions)

Saves the workbook as an HTML file with specified options.

Parameters:

  • fileName (str) – The name of the HTML file to save to.

  • saveOption (HTMLOptions) – The options for saving as HTML.

SaveAsImageOrXps

Saves the workbook as an image or XPS file to a stream.

Parameters:

  • stream (Stream) – The stream to save the file to.

  • fileFormat (FileFormat) – The format to save the file as (image or XPS).

SaveAsImages

Saves the workbook as images with specified DPI values.

Parameters:

  • dpiX (float) – The horizontal DPI value.

  • dpiY (float) – The vertical DPI value.

Returns:

A list of Stream objects containing the saved images.

Return type:

List[Stream]

SaveChartAsEmfImage(worksheet: Worksheet, chartIndex: int, imageOrPrintOptions: ConverterSetting, emfStream: Stream) → Stream

Saves the specified chart of the worksheet as an EMF image.

Parameters:

  • worksheet (Worksheet) – The worksheet containing the chart.

  • chartIndex (int) – The index of the chart to save.

  • imageOrPrintOptions (ConverterSetting) – The options for the image or print.

  • emfStream (Stream) – The stream to save the EMF image to.

SaveChartAsImage

Saves the specified chart of the worksheet as an image.

Parameters:

  • worksheet (Worksheet) – The worksheet containing the chart.

  • imageOrPrintOptions (ConverterSetting) – The options for the image or print.

Returns:

A list of Stream objects containing the saved images.

Return type:

List[Stream]

SaveToPdf

Saves the workbook as a PDF file to a stream.

Parameters:

stream (Stream) – The stream to save the PDF to.

SaveToXlsm

Saves the workbook as an XLSM file (Excel workbook with macros).

Parameters:

fileName (str) – The name of the file to save to.

property Saved: bool

Gets or sets whether the workbook has been saved.

Returns:

True if the workbook has been saved, otherwise False.

Return type:

bool

property Saving: bool

Gets whether the workbook is currently being saved.

Returns:

True if the workbook is being saved, otherwise False.

Return type:

bool

property SecondCharSize: int

Gets or sets the size of the second character in the workbook.

Returns:

The size of the second character.

Return type:

int

SetActiveWorksheet(sheet: XlsWorksheetBase)

Sets the specified worksheet as the active worksheet in the workbook.

Parameters:

sheet (XlsWorksheetBase) – The worksheet to set as active.

SetChanged()

Marks the workbook as having unsaved changes. This method is called when modifications are made to the workbook that need to be saved.

SetColorOrGetNearest

Sets a color in the workbook’s palette or returns the nearest matching color if the exact color is not available.

Parameters:

color (Color) – The color to set or find nearest match for.

Returns:

The nearest matching Excel color.

Return type:

ExcelColors

SetMaxDigitWidth(w: int)

Sets the maximum width of digits in the workbook.

Parameters:

w (int) – The maximum digit width to set.

SetPaletteColor(index: int, color: Color)

Sets a specific color in the workbook’s palette.

Parameters:

  • index (int) – The index in the palette where to set the color.

  • color (Color) – The color to set in the palette.

SetSeparators(argumentsSeparator: int, arrayRowsSeparator: int)

Sets the separators for the workbook.

Parameters:

  • argumentsSeparator (int) – The separator for arguments.

  • arrayRowsSeparator (int) – The separator for array rows.

SetWriteProtectionPassword(password: str)

Sets the write protection password for the workbook.

Parameters:

password (str) – The password to set for write protection.

property StandardFont: str
property StandardFontSize: float
property StandardRowHeight: float

Gets the standard row height of the workbook.

Returns:

The standard row height.

Return type:

float

property StandardRowHeightInPixels: int

Gets the standard row height in pixels.

Returns:

The standard row height in pixels.

Return type:

int

property Styles: IStyles

Gets the collection of styles in the workbook.

Returns:

The collection of styles.

Return type:

IStyles

property TabSheets: ITabSheets

Gets the collection of tab sheets in the workbook.

Returns:

The collection of tab sheets.

Return type:

ITabSheets

property ThrowOnUnknownNames: bool

Indicates whether the workbook should throw an exception when encountering unknown names.

Returns:

True if the workbook should throw an exception, otherwise False.

Return type:

bool

Unprotect

Removes write protection from the workbook.

property Version: ExcelVersion

Gets the Excel version of the workbook.

Returns:

The Excel version.

Return type:

ExcelVersion

WidthToFileWidth(width: float) → float

Converts a pixel width value to a file width value.

Parameters:

width (float) – The pixel width value to convert.

Returns:

The corresponding file width.

Return type:

float

property Worksheets: IWorksheets

Gets the collection of worksheets in the workbook.

Returns:

The collection of worksheets.

Return type:

IWorksheets