Excel C API Functions

PyXLL exposes certain functions from the Excel C API. These mostly should only be called from a worksheet, menu or macro functions, and some should only be called from macro-sheet equivalent functions [1].

xlfCaller

xlfCaller()
Returns:calling cell as an XLCell instance.

Callable from any function, but most properties of XLCell are only accessible from macro sheet equivalent functions [1]

xlfSheetId

xlSheetId(sheet_name)
Returns:integer sheet id from a sheet name (e.g. ‘[Book1.xls]Sheet1’)

xlfGetWorkspace

xlfGetWorkspace(arg_num)
Parameters:arg_num (int) – number of 1 to 72 specifying the type of workspace information to return
Returns:depends on arg_num

xlfGetWorkbook

xlfGetWorkbook(arg_num workbook=None)
Parameters:
  • arg_num (int) – number from 1 to 38 specifying the type of workbook information to return
  • workbook (string) – workbook name
Returns:

depends on arg_num

xlfGetWindow

xlfGetWindow(arg_num, window=None)
Parameters:
  • arg_num (int) – number from 1 to 39 specifying the type of window information to return
  • window (string) – window name
Returns:

depends on arg_num

xlfWindows

xlfWindows(match_type=0, mask=None)
Parameters:
  • match_type (int) –

    a number from 1 to 3 specifying the type of windows to match

    1 (or omitted) = non-add-in windows

    2 = add-in windows

    3 = all windows

  • mask (string) – window name mask
Returns:

list of matching window names

xlfVolatile

xlfVolatile(volatile)
Parameters:volatile (bool) – boolean indicating whether the calling function is volatile or not.

Usually it is better to declare a function as volatile via the xl_func decorator. This function can be used to make a function behave as a volatile or non-volatile function regardless of how it was declared, which can be useful in some cases.

Callable from a macro equivalent function only [1]

xlcAlert

xlcAlert(alert)

Pops up an alert window.

Callable from a macro or menu function only [1]

Parameters:alert (string) – text to display

xlcCalculation

xlcCalculation(calc_type)

set the calculation type to automatic or manual.

Callable from a macro or menu function only [1]

Parameters:calc_type (int) –

xlCalculationAutomatic

or xlCalculationSemiAutomatic

or xlCalculationManual

xlCalculationAutomatic = 1
xlCalculationSemiAutomatic = 2
xlCalculationManual = 3

xlcCalculateNow

xlcCalculateNow()

recalculate all cells that have been marked as dirty (i.e. have dependencies that have changed) or that are volatile functions.

Equivalent to pressing F9.

Callable from a macro or menu function only [1]

xlcCalculateDocument

xlcCalculateDocument()

recalculate all cells that have been marked as dirty (i.e. have dependencies that have changed) or that are volatile functions for the current worksheet only

Callable from a macro or menu function only [1]

xlAsyncReturn

xlAsyncReturn(handle, value)

used by asynchronous functions to return the result to Excel see Asynchronous Functions

This function can be called from any thread and doesn’t have to be from a macro sheet equivalent function

Parameters:
  • handle (object) – async handle passed to the worksheet function
  • value (object) – value to return to Excel

xlAbort

xlAbort(retain=True)

Yields the processor to other tasks in the system and checks whether the user has pressed ESC to cancel a macro or workbook recalculation.

Parameters:retain (bool) – If False and a break condition has been set it is reset, otherwise don’t change the break condition.
Returns:True if the user has pressed ESC, False otherwise.

xlSheetNm

xlSheetNm(sheet_id)
Returns:sheet name from a sheet id (as returned by xlSheetId or XLCell.sheet_id).
xlfGetDocument(arg_num[, name])
Parameters:
  • arg_num (int) – number from 1 to 88 specifying the type of document information to return
  • name (string) – sheet or workbook name
Returns:

depends on arg_num

Footnotes

[1](1, 2, 3, 4, 5, 6, 7) A macro sheet equivalent function is a function exposed using xl_func with macro=True.