Worksheet API Reference — oosxl 0.1.0 documentation

# Worksheet API Reference

## Overview

The Worksheet API provides comprehensive functions to manage Excel worksheets, including cell operations, styling, row/column management, formatting, images, hyperlinks, tables, and printing settings.

## Worksheet Information

int ws_min_row(WorksheetHandle ws)

  Get the minimum row index.

  Parameters:

    - ws – Worksheet handle.

  Returns:

    Minimum row index.

int ws_max_row(WorksheetHandle ws)

  Get the maximum row index.

  Parameters:

    - ws – Worksheet handle.

  Returns:

    Maximum row index.

int ws_min_col(WorksheetHandle ws)

  Get the minimum column index.

  Parameters:

    - ws – Worksheet handle.

  Returns:

    Minimum column index.

int ws_max_col(WorksheetHandle ws)

  Get the maximum column index.

  Parameters:

    - ws – Worksheet handle.

  Returns:

    Maximum column index.

const char *ws_name(WorksheetHandle ws)

  Get the worksheet name.

  Parameters:

    - ws – Worksheet handle.

  Returns:

    Worksheet name.

int ws_set_name(WorksheetHandle ws, const char *newname)

  Set the worksheet name.

  Parameters:

    - ws – Worksheet handle.

    - newname – New worksheet name.

  Returns:

    1 on success, 0 on failure.

int ws_ws_type(WorksheetHandle ws)

  Get the worksheet type.

  Parameters:

    - ws – Worksheet handle.

  Returns:

    Worksheet type (see `SheetTypeEnum`).

int ws_get_ws_state(WorksheetHandle ws)

  Get the worksheet state.

  Parameters:

    - ws – Worksheet handle.

  Returns:

    Worksheet state (see `SheetStateEnum`).

## Cell Data Operations

int ws_cell_type(WorksheetHandle ws, int row, int col)

  Get the cell data type.

  Parameters:

    - ws – Worksheet handle.

    - row – Row index.

    - col – Column index.

  Returns:

    Cell type (see `CellTypeEnum`).

int ws_contains_formula(WorksheetHandle ws, int row, int col)

  Check if cell contains formula.

  Parameters:

    - ws – Worksheet handle.

    - row – Row index.

    - col – Column index.

  Returns:

    1 if contains formula, 0 otherwise.

int ws_contains_richtext(WorksheetHandle ws, int row, int col)

  Check if cell contains rich text.

  Parameters:

    - ws – Worksheet handle.

    - row – Row index.

    - col – Column index.

  Returns:

    1 if contains rich text, 0 otherwise.

double ws_get_num(WorksheetHandle ws, int row, int col)

  Get numeric value from cell.

  Parameters:

    - ws – Worksheet handle.

    - row – Row index.

    - col – Column index.

  Returns:

    Numeric value.

const char *ws_get_text(WorksheetHandle ws, int row, int col)

  Get text value from cell.

  Parameters:

    - ws – Worksheet handle.

    - row – Row index.

    - col – Column index.

  Returns:

    Text string.

int ws_get_boolean(WorksheetHandle ws, int row, int col)

  Get boolean value from cell.

  Parameters:

    - ws – Worksheet handle.

    - row – Row index.

    - col – Column index.

  Returns:

    Boolean value (1=true, 0=false).

double ws_get_datetime(WorksheetHandle ws, int row, int col)

  Get datetime value from cell.

  Parameters:

    - ws – Worksheet handle.

    - row – Row index.

    - col – Column index.

  Returns:

    DateTime value as double.

RichtextHandle ws_get_richtext(WorksheetHandle ws, int row, int col)

  Get rich text from cell.

  Parameters:

    - ws – Worksheet handle.

    - row – Row index.

    - col – Column index.

  Returns:

    Rich text handle.

const char *ws_get_formula_expr(WorksheetHandle ws, int row, int col)

  Get formula expression from cell.

  Parameters:

    - ws – Worksheet handle.

    - row – Row index.

    - col – Column index.

  Returns:

    Formula expression.

int ws_get_error(WorksheetHandle ws, int row, int col)

  Get error code from cell.

  Parameters:

    - ws – Worksheet handle.

    - row – Row index.

    - col – Column index.

  Returns:

    Error code (see `ErrorCodeEnum`).

## Cell Data Setting

int ws_set_num(WorksheetHandle ws, int row, int col, double val)

  Set numeric value to cell.

  Parameters:

    - ws – Worksheet handle.

    - row – Row index.

    - col – Column index.

    - val – Numeric value.

  Returns:

    1 on success, 0 on failure.

int ws_set_text(WorksheetHandle ws, int row, int col, const char *val)

  Set text value to cell.

  Parameters:

    - ws – Worksheet handle.

    - row – Row index.

    - col – Column index.

    - val – Text string.

  Returns:

    1 on success, 0 on failure.

int ws_set_boolean(WorksheetHandle ws, int row, int col, int b)

  Set boolean value to cell.

  Parameters:

    - ws – Worksheet handle.

    - row – Row index.

    - col – Column index.

    - b – Boolean value (1=true, 0=false).

  Returns:

    1 on success, 0 on failure.

int ws_set_datetime(WorksheetHandle ws, int row, int col, double dt)

  Set datetime value to cell.

  Parameters:

    - ws – Worksheet handle.

    - row – Row index.

    - col – Column index.

    - dt – DateTime value as double.

  Returns:

    1 on success, 0 on failure.

int ws_set_richtext(WorksheetHandle ws, int row, int col, RichtextHandle rt)

  Set rich text to cell.

  Parameters:

    - ws – Worksheet handle.

    - row – Row index.

    - col – Column index.

    - rt – Rich text handle.

  Returns:

    1 on success, 0 on failure.

int ws_set_error(WorksheetHandle ws, int row, int col, int code)

  Set error value to cell.

  Parameters:

    - ws – Worksheet handle.

    - row – Row index.

    - col – Column index.

    - code – Error code (see `ErrorCodeEnum`).

  Returns:

    1 on success, 0 on failure.

## Formula Operations

int ws_set_formula(WorksheetHandle ws, int row, int col, const char *expr)

  Set formula to cell.

  Parameters:

    - ws – Worksheet handle.

    - row – Row index.

    - col – Column index.

    - expr – Formula expression.

  Returns:

    1 on success, 0 on failure.

int ws_set_formula_num(WorksheetHandle ws, int row, int col, double val)

  Set formula with numeric result.

  Parameters:

    - ws – Worksheet handle.

    - row – Row index.

    - col – Column index.

    - val – Numeric result value.

  Returns:

    1 on success, 0 on failure.

int ws_set_formula_string(WorksheetHandle ws, int row, int col, const char *s)

  Set formula with string result.

  Parameters:

    - ws – Worksheet handle.

    - row – Row index.

    - col – Column index.

    - s – String result value.

  Returns:

    1 on success, 0 on failure.

int ws_set_formula_boolean(WorksheetHandle ws, int row, int col, int b)

  Set formula with boolean result.

  Parameters:

    - ws – Worksheet handle.

    - row – Row index.

    - col – Column index.

    - b – Boolean result value.

  Returns:

    1 on success, 0 on failure.

int ws_set_formula_datetime(WorksheetHandle ws, int row, int col, double dt)

  Set formula with datetime result.

  Parameters:

    - ws – Worksheet handle.

    - row – Row index.

    - col – Column index.

    - dt – DateTime result value.

  Returns:

    1 on success, 0 on failure.

int ws_set_formula_error(WorksheetHandle ws, int row, int col, int code)

  Set formula with error result.

  Parameters:

    - ws – Worksheet handle.

    - row – Row index.

    - col – Column index.

    - code – Error result code.

  Returns:

    1 on success, 0 on failure.

void ws_clear_contents(WorksheetHandle ws, int begin_row, int begin_col, int end_row, int end_col)

  Clear cell contents in specified range.

  Parameters:

    - ws – Worksheet handle.

    - begin_row – Start row index.

    - begin_col – Start column index.

    - end_row – End row index.

    - end_col – End column index.

## Cell Styling

void ws_set_cell_style(WorksheetHandle ws, int row, int col, StyleHandle style)

  Set style for specific cell.

  Parameters:

    - ws – Worksheet handle.

    - row – Row index.

    - col – Column index.

    - style – Style handle.

StyleHandle ws_cell_style(WorksheetHandle ws, int row, int col)

  Get style from specific cell.

  Parameters:

    - ws – Worksheet handle.

    - row – Row index.

    - col – Column index.

  Returns:

    Style handle.

StyleHandle ws_get_cell_style(WorksheetHandle ws, int row, int col)

  Get cell style (alias of ws_cell_style).

  Parameters:

    - ws – Worksheet handle.

    - row – Row index.

    - col – Column index.

  Returns:

    Style handle.

void ws_set_range_style(WorksheetHandle ws, int start_row, int start_col, int stop_row, int stop_col, StyleHandle style)

  Set style for cell range.

  Parameters:

    - ws – Worksheet handle.

    - start_row – Start row index.

    - start_col – Start column index.

    - stop_row – End row index.

    - stop_col – End column index.

    - style – Style handle.

## Row and Column Dimensions

int ws_is_default_row_height(WorksheetHandle ws, int start, int end)

  Check if rows have default height.

  Parameters:

    - ws – Worksheet handle.

    - start – Start row index.

    - end – End row index.

  Returns:

    1 if default height, 0 otherwise.

int ws_get_custom_row_height(WorksheetHandle ws, int start, int end, double *height, int unit)

  Get custom row height.

  Parameters:

    - ws – Worksheet handle.

    - start – Start row index.

    - end – End row index.

    - height – Pointer to store height value.

    - unit – Height unit (see `RowHeightUnitEnum`).

  Returns:

    1 if custom height exists, 0 otherwise.

void ws_set_custom_row_height(WorksheetHandle ws, int start, int end, double height, int unit)

  Set custom row height.

  Parameters:

    - ws – Worksheet handle.

    - start – Start row index.

    - end – End row index.

    - height – Height value.

    - unit – Height unit (see `RowHeightUnitEnum`).

int ws_is_default_col_width(WorksheetHandle ws, int start, int end)

  Check if columns have default width.

  Parameters:

    - ws – Worksheet handle.

    - start – Start column index.

    - end – End column index.

  Returns:

    1 if default width, 0 otherwise.

int ws_get_custom_col_width(WorksheetHandle ws, int start, int end, double *width, int unit)

  Get custom column width.

  Parameters:

    - ws – Worksheet handle.

    - start – Start column index.

    - end – End column index.

    - width – Pointer to store width value.

    - unit – Width unit (see `ColWidthUnitEnum`).

  Returns:

    1 if custom width exists, 0 otherwise.

void ws_set_custom_col_width(WorksheetHandle ws, int start, int end, double width, int unit)

  Set custom column width.

  Parameters:

    - ws – Worksheet handle.

    - start – Start column index.

    - end – End column index.

    - width – Width value.

    - unit – Width unit (see `ColWidthUnitEnum`).

## Row and Column Styling

StyleHandle ws_row_style(WorksheetHandle ws, int row)

  Get style for entire row.

  Parameters:

    - ws – Worksheet handle.

    - row – Row index.

  Returns:

    Style handle.

void ws_remove_row_style(WorksheetHandle ws, int row)

  Remove style from entire row.

  Parameters:

    - ws – Worksheet handle.

    - row – Row index.

void ws_set_row_style(WorksheetHandle ws, int start_row, int stop_row, StyleHandle style)

  Set style for row range.

  Parameters:

    - ws – Worksheet handle.

    - start_row – Start row index.

    - stop_row – End row index.

    - style – Style handle.

StyleHandle ws_col_style(WorksheetHandle ws, int col)

  Get style for entire column.

  Parameters:

    - ws – Worksheet handle.

    - col – Column index.

  Returns:

    Style handle.

void ws_remove_col_style(WorksheetHandle ws, int col)

  Remove style from entire column.

  Parameters:

    - ws – Worksheet handle.

    - col – Column index.

void ws_set_col_style(WorksheetHandle ws, int start_col, int stop_col, StyleHandle style)

  Set style for column range.

  Parameters:

    - ws – Worksheet handle.

    - start_col – Start column index.

    - stop_col – End column index.

    - style – Style handle.

## Row and Column Visibility

int ws_row_hidden(WorksheetHandle ws, int row)

  Check if row is hidden.

  Parameters:

    - ws – Worksheet handle.

    - row – Row index.

  Returns:

    1 if hidden, 0 otherwise.

void ws_set_row_hidden(WorksheetHandle ws, int start_row, int stop_row, int hidden)

  Set row hidden status.

  Parameters:

    - ws – Worksheet handle.

    - start_row – Start row index.

    - stop_row – End row index.

    - hidden – 1 to hide, 0 to show.

int ws_col_hidden(WorksheetHandle ws, int col)

  Check if column is hidden.

  Parameters:

    - ws – Worksheet handle.

    - col – Column index.

  Returns:

    1 if hidden, 0 otherwise.

void ws_set_col_hidden(WorksheetHandle ws, int start_col, int stop_col, int hidden)

  Set column hidden status.

  Parameters:

    - ws – Worksheet handle.

    - start_col – Start column index.

    - stop_col – End column index.

    - hidden – 1 to hide, 0 to show.

## Row and Column Operations

int ws_insert_row(WorksheetHandle ws, int row, int count)

  Insert rows.

  Parameters:

    - ws – Worksheet handle.

    - row – Starting row index.

    - count – Number of rows to insert.

  Returns:

    1 on success, 0 on failure.

int ws_delete_row(WorksheetHandle ws, int begin, int end)

  Delete rows.

  Parameters:

    - ws – Worksheet handle.

    - begin – Start row index.

    - end – End row index.

  Returns:

    1 on success, 0 on failure.

int ws_insert_col(WorksheetHandle ws, int col, int count)

  Insert columns.

  Parameters:

    - ws – Worksheet handle.

    - col – Starting column index.

    - count – Number of columns to insert.

  Returns:

    1 on success, 0 on failure.

int ws_delete_col(WorksheetHandle ws, int begin, int end)

  Delete columns.

  Parameters:

    - ws – Worksheet handle.

    - begin – Start column index.

    - end – End column index.

  Returns:

    1 on success, 0 on failure.

## Range Shifting

int ws_shift_range_down(WorksheetHandle ws, int start_col, int end_col, int start_row, int count)

  Shift range downward.

  Parameters:

    - ws – Worksheet handle.

    - start_col – Start column index.

    - end_col – End column index.

    - start_row – Start row index.

    - count – Number of rows to shift.

  Returns:

    1 on success, 0 on failure.

int ws_shift_range_up(WorksheetHandle ws, int start_col, int end_col, int start_row, int count)

  Shift range upward.

  Parameters:

    - ws – Worksheet handle.

    - start_col – Start column index.

    - end_col – End column index.

    - start_row – Start row index.

    - count – Number of rows to shift.

  Returns:

    1 on success, 0 on failure.

int ws_shift_range_right(WorksheetHandle ws, int start_row, int end_row, int start_col, int count)

  Shift range to the right.

  Parameters:

    - ws – Worksheet handle.

    - start_row – Start row index.

    - end_row – End row index.

    - start_col – Start column index.

    - count – Number of columns to shift.

  Returns:

    1 on success, 0 on failure.

int ws_shift_range_left(WorksheetHandle ws, int start_row, int end_row, int start_col, int count)

  Shift range to the left.

  Parameters:

    - ws – Worksheet handle.

    - start_row – Start row index.

    - end_row – End row index.

    - start_col – Start column index.

    - count – Number of columns to shift.

  Returns:

    1 on success, 0 on failure.

## Images and Background

void ws_set_bg_picture(WorksheetHandle ws, const char *file)

  Set worksheet background picture.

  Parameters:

    - ws – Worksheet handle.

    - file – Image file path.

int ws_add_cell_image(WorksheetHandle ws, const char *file, int start_row, int start_col, int stop_row, int stop_col)

  Add image to fit specific cell range.

  Parameters:

    - ws – Worksheet handle.

    - file – Image file path.

    - start_row – Start row index.

    - start_col – Start column index.

    - stop_row – End row index.

    - stop_col – End column index.

  Returns:

    Image index.

int ws_add_image_with_two_cells(WorksheetHandle ws, const char *file, int row1, int col1, int row2, int col2, int offset_x1, int offset_y1, int offset_x2, int offset_y2)

  Add an image to the worksheet, anchoring it between two cells.

  Parameters:

    - ws – Worksheet handle.

    - file – Path to the image file.

    - row1 – Row index of the top-left anchor cell.

    - col1 – Column index of the top-left anchor cell.

    - row2 – Row index of the bottom-right anchor cell.

    - col2 – Column index of the bottom-right anchor cell.

    - offset_x1 – Horizontal offset from the top-left anchor cell (in pixels).

    - offset_y1 – Vertical offset from the top-left anchor cell (in pixels).

    - offset_x2 – Horizontal offset from the bottom-right anchor cell (in pixels).

    - offset_y2 – Vertical offset from the bottom-right anchor cell (in pixels).

  Returns:

    ID of the added image.

int ws_add_image_with_one_cell(WorksheetHandle ws, const char *file, int row, int col, int width, int height, double scale, int offset_x, int offset_y)

  Add an image to the worksheet, anchored to a single cell. If both width and height are 0, the image size is determined by the scale parameter.

  Parameters:

    - ws – Worksheet handle.

    - file – Path to the image file.

    - row – Row index of the anchor cell.

    - col – Column index of the anchor cell.

    - width – Desired width of the image in pixels (0 to use scaling).

    - height – Desired height of the image in pixels (0 to use scaling).

    - scale – Scaling factor for the image (used when width and height are 0).

    - offset_x – Horizontal offset from the anchor cell (in pixels).

    - offset_y – Vertical offset from the anchor cell (in pixels).

  Returns:

    ID of the added image.

int ws_add_absolute_image(WorksheetHandle ws, const char *file, int x, int y, int width, int height, double scale)

  Add an image to the worksheet, positioned using absolute pixel coordinates. If both width and height are 0, the image size is determined by the scale parameter.

  Parameters:

    - ws – Worksheet handle.

    - file – Path to the image file.

    - x – X-coordinate (in pixels) for the top-left corner of the image.

    - y – Y-coordinate (in pixels) for the top-left corner of the image.

    - width – Desired width of the image in pixels (0 to use scaling).

    - height – Desired height of the image in pixels (0 to use scaling).

    - scale – Scaling factor for the image (used when width and height are 0).

  Returns:

    ID of the added image.

int ws_image_num(WorksheetHandle ws)

  Get the total number of images currently in the worksheet.

  Parameters:

    - ws – Worksheet handle.

  Returns:

    Number of images.

int ws_get_image_id(WorksheetHandle ws, int index)

  Retrieve the ID of an image based on its insertion order.

  Parameters:

    - ws – Worksheet handle.

    - index – Zero‑based index of the image (order of insertion).

  Returns:

    Image ID.

ImageAnchorEnum ws_image_anchor_type(WorksheetHandle ws, int image_id)

  Get the anchoring type of the specified image.

  Parameters:

    - ws – Worksheet handle.

    - image_id – ID of the target image.

  Returns:

    An enumeration value of type ImageAnchorEnum.

bool ws_get_anchored_cell(WorksheetHandle ws, int image_id, int *row, int *col)

  Retrieve the cell anchor coordinates for an image that uses single‑cell anchoring.

  Parameters:

    - ws – Worksheet handle.

    - image_id – ID of the target image.

    - row – Pointer to store the row index of the anchor cell.

    - col – Pointer to store the column index of the anchor cell.

  Returns:

    true if successful, false otherwise.

bool ws_get_absolute_coord(WorksheetHandle ws, int image_id, int *x, int *y)

  Retrieve the absolute pixel coordinates for an image that uses absolute positioning.

  Parameters:

    - ws – Worksheet handle.

    - image_id – ID of the target image.

    - x – Pointer to store the X‑coordinate (in pixels).

    - y – Pointer to store the Y‑coordinate (in pixels).

  Returns:

    true if successful, false otherwise.

void ws_delete_image(WorksheetHandle ws, int image_id)

  Remove an image from the worksheet by its ID.

  Parameters:

    - ws – Worksheet handle.

    - image_id – ID of the image to delete.

void ws_remove_image(WorksheetHandle ws, int row, int col)

  Remove an image by the cell to which it is anchored.

  Parameters:

    - ws – Worksheet handle.

    - row – Row index of the anchor cell.

    - col – Column index of the anchor cell.

void ws_remove_absolute_image(WorksheetHandle ws, int x, int y)

  Remove an image by its absolute anchor coordinates.

  Parameters:

    - ws – Worksheet handle.

    - x – X‑coordinate (in pixels) of the image’s anchor point.

    - y – Y‑coordinate (in pixels) of the image’s anchor point.

## Cell Navigation

int ws_first_data_cell(WorksheetHandle ws, int *row, int *col)

  Find the first cell containing data.

  Parameters:

    - ws – Worksheet handle.

    - row – Pointer to store row index.

    - col – Pointer to store column index.

  Returns:

    1 if found, 0 if worksheet is empty.

int ws_last_data_cell(WorksheetHandle ws, int *row, int *col)

  Find the last cell containing data.

  Parameters:

    - ws – Worksheet handle.

    - row – Pointer to store row index.

    - col – Pointer to store column index.

  Returns:

    1 if found, 0 if worksheet is empty.

## Merged Cells

int ws_merge_num(WorksheetHandle ws)

  Get number of merged ranges.

  Parameters:

    - ws – Worksheet handle.

  Returns:

    Number of merged ranges.

int ws_merged_range(WorksheetHandle ws, int index, int *start_row, int *start_col, int *stop_row, int *stop_col)

  Get a merged range.

  Parameters:

    - ws – Worksheet handle.

    - index – Index of merged ranges.

    - start_row – Pointer to store start row.

    - start_col – Pointer to store start column.

    - stop_row – Pointer to store end row.

    - stop_col – Pointer to store end column.

  Returns:

    1 on success, 0 on failure.

int ws_merge(WorksheetHandle ws, int start_row, int start_col, int stop_row, int stop_col)

  Merge cell range.

  Parameters:

    - ws – Worksheet handle.

    - start_row – Start row index.

    - start_col – Start column index.

    - stop_row – End row index.

    - stop_col – End column index.

  Returns:

    1 on success, 0 on failure.

int ws_unmerge(WorksheetHandle ws, int row, int col)

  Unmerge cells at specified position.

  Parameters:

    - ws – Worksheet handle.

    - row – Row index.

    - col – Column index.

  Returns:

    1 on success, 0 on failure.

## Table Operations

int ws_tabledef_count(WorksheetHandle ws)

  Get number of tables in worksheet.

  Parameters:

    - ws – Worksheet handle.

  Returns:

    Number of tables.

const char *ws_get_tabledef_name(WorksheetHandle ws, int index)

  Get table name by index.

  Parameters:

    - ws – Worksheet handle.

    - index – Table index.

  Returns:

    Table name.

int ws_set_tabledef_name(WorksheetHandle ws, int index, const char *new_name)

  Set table name.

  Parameters:

    - ws – Worksheet handle.

    - index – Table index.

    - new_name – New table name.

  Returns:

    1 on success, 0 on failure.

TabledefHandle ws_get_tabledef(WorksheetHandle ws, int index)

  Get table handle by index.

  Parameters:

    - ws – Worksheet handle.

    - index – Table index.

  Returns:

    Table handle.

TabledefHandle ws_get_tabledef_by_name(WorksheetHandle ws, const char *name)

  Get table handle by name.

  Parameters:

    - ws – Worksheet handle.

    - name – Table name.

  Returns:

    Table handle.

TabledefHandle ws_add_tabledef(WorksheetHandle ws, const char *name, int begin_row, int begin_col, int end_row, int end_col)

  Add table to worksheet.

  Parameters:

    - ws – Worksheet handle.

    - name – Table name.

    - begin_row – Start row index.

    - begin_col – Start column index.

    - end_row – End row index.

    - end_col – End column index.

  Returns:

    Table handle.

int ws_delete_tabledef(WorksheetHandle ws, const char *name)

  Delete table from worksheet.

  Parameters:

    - ws – Worksheet handle.

    - name – Table name.

  Returns:

    1 on success, 0 on failure.

## Grouping and Outlining

void ws_group_rows(WorksheetHandle ws, int begin_row, int end_row, int collapsed)

  Group rows.

  Parameters:

    - ws – Worksheet handle.

    - begin_row – Start row index.

    - end_row – End row index.

    - collapsed – 1 for collapsed, 0 for expanded.

void ws_ungroup_rows(WorksheetHandle ws, int begin_row, int end_row)

  Ungroup rows.

  Parameters:

    - ws – Worksheet handle.

    - begin_row – Start row index.

    - end_row – End row index.

void ws_group_cols(WorksheetHandle ws, int begin_col, int end_col, int collapsed)

  Group columns.

  Parameters:

    - ws – Worksheet handle.

    - begin_col – Start column index.

    - end_col – End column index.

    - collapsed – 1 for collapsed, 0 for expanded.

void ws_ungroup_cols(WorksheetHandle ws, int begin_col, int end_col)

  Ungroup columns.

  Parameters:

    - ws – Worksheet handle.

    - begin_col – Start column index.

    - end_col – End column index.

int ws_row_outline_level(WorksheetHandle ws, int row, int *collapsed)

  Get row outline level.

  Parameters:

    - ws – Worksheet handle.

    - row – Row index.

    - collapsed – Pointer to store collapsed status.

  Returns:

    Outline level.

int ws_col_outline_level(WorksheetHandle ws, int col, int *collapsed)

  Get column outline level.

  Parameters:

    - ws – Worksheet handle.

    - col – Column index.

    - collapsed – Pointer to store collapsed status.

  Returns:

    Outline level.

int ws_max_row_outline_level(WorksheetHandle ws)

  Get maximum row outline level.

  Parameters:

    - ws – Worksheet handle.

  Returns:

    Maximum outline level.

int ws_max_col_outline_level(WorksheetHandle ws)

  Get maximum column outline level.

  Parameters:

    - ws – Worksheet handle.

  Returns:

    Maximum outline level.

void ws_delete_row_outline(WorksheetHandle ws)

  Delete all row outlines.

  Parameters:

    - ws – Worksheet handle.

void ws_delete_col_outline(WorksheetHandle ws)

  Delete all column outlines.

  Parameters:

    - ws – Worksheet handle.

int ws_group_summary_below(WorksheetHandle ws)

  Check if group summary is below details.

  Parameters:

    - ws – Worksheet handle.

  Returns:

    1 if summary below, 0 if above.

void ws_set_group_summary_below(WorksheetHandle ws, int below)

  Set group summary position.

  Parameters:

    - ws – Worksheet handle.

    - below – 1 for summary below, 0 for above.

int ws_group_summary_right(WorksheetHandle ws)

  Check if group summary is to the right of details.

  Parameters:

    - ws – Worksheet handle.

  Returns:

    1 if summary right, 0 if left.

void ws_set_group_summary_right(WorksheetHandle ws, int right)

  Set group summary horizontal position.

  Parameters:

    - ws – Worksheet handle.

    - right – 1 for summary right, 0 for left.

## Hyperlinks

int ws_add_hyperlink(WorksheetHandle ws, const char *hyperlink, int start_row, int start_col, int end_row, int end_col)

  Add hyperlink to cell range.

  Parameters:

    - ws – Worksheet handle.

    - hyperlink – Hyperlink URL or address.

    - start_row – Start row index.

    - start_col – Start column index.

    - end_row – End row index.

    - end_col – End column index.

  Returns:

    Hyperlink index.

int ws_hyperlink_num(WorksheetHandle ws)

  Get number of hyperlinks.

  Parameters:

    - ws – Worksheet handle.

  Returns:

    Number of hyperlinks.

int ws_hyperlink_index(WorksheetHandle ws, int row, int col)

  Get hyperlink index for cell.

  Parameters:

    - ws – Worksheet handle.

    - row – Row index.

    - col – Column index.

  Returns:

    Hyperlink index, or -1 if no hyperlink.

const char *ws_hyperlink(WorksheetHandle ws, int index, int *start_row, int *start_col, int *end_row, int *end_col)

  Get hyperlink information.

  Parameters:

    - ws – Worksheet handle.

    - index – Hyperlink index.

    - start_row – Pointer to store start row.

    - start_col – Pointer to store start column.

    - end_row – Pointer to store end row.

    - end_col – Pointer to store end column.

  Returns:

    Hyperlink URL.

int ws_delete_hyperlink(WorksheetHandle ws, int index)

  Delete hyperlink.

  Parameters:

    - ws – Worksheet handle.

    - index – Hyperlink index.

  Returns:

    1 on success, 0 on failure.

## Worksheet Protection

int ws_is_protected(WorksheetHandle ws)

  Check if worksheet is protected.

  Parameters:

    - ws – Worksheet handle.

  Returns:

    1 if protected, 0 otherwise.

int ws_protect(WorksheetHandle ws, int item, const char *password)

  Protect worksheet.

  Parameters:

    - ws – Worksheet handle.

    - item – Protection options (see `SheetProtectEnum`).

    - password – Protection password.

  Returns:

    1 on success, 0 on failure.

void ws_unprotect(WorksheetHandle ws)

  Unprotect worksheet.

  Parameters:

    - ws – Worksheet handle.

int ws_protect_range(WorksheetHandle ws, int start_row, int start_col, int end_row, int end_col)

  Protect specific cell range.

  Parameters:

    - ws – Worksheet handle.

    - start_row – Start row index.

    - start_col – Start column index.

    - end_row – End row index.

    - end_col – End column index.

  Returns:

    1 on success, 0 on failure.

int ws_set_editable_range(WorksheetHandle ws, int start_row, int start_col, int end_row, int end_col)

  Allow editing of specific range in protected worksheet.

  Parameters:

    - ws – Worksheet handle.

    - start_row – Start row index.

    - start_col – Start column index.

    - end_row – End row index.

    - end_col – End column index.

  Returns:

    1 on success, 0 on failure.

int ws_editable_range_count(WorksheetHandle ws)

  Get number of editable ranges.

  Parameters:

    - ws – Worksheet handle.

  Returns:

    Number of allowed edit ranges.

const char *ws_get_editable_range(WorksheetHandle ws, int index, int *start_row, int *start_col, int *stop_row, int *stop_col)

  Get editable range information.

  Parameters:

    - ws – Worksheet handle.

    - index – Range index.

    - start_row – Pointer to store start row.

    - start_col – Pointer to store start column.

    - stop_row – Pointer to store end row.

    - stop_col – Pointer to store end column.

  Returns:

    Range name.

int ws_delete_editable_range(WorksheetHandle ws, int index)

  Delete an editable range.

  Parameters:

    - ws – Worksheet handle.

    - index – Range index.

  Returns:

    1 on success, 0 on failure.

## View and Display Settings

int ws_zoom(WorksheetHandle ws)

  Get worksheet zoom level.

  Parameters:

    - ws – Worksheet handle.

  Returns:

    Zoom percentage.

void ws_set_zoom(WorksheetHandle ws, int zoom)

  Set worksheet zoom level.

  Parameters:

    - ws – Worksheet handle.

    - zoom – Zoom percentage.

int ws_right_to_left(WorksheetHandle ws)

  Check if right-to-left display is enabled.

  Parameters:

    - ws – Worksheet handle.

  Returns:

    1 if right-to-left, 0 otherwise.

void ws_set_right_to_left(WorksheetHandle ws, int right_to_left)

  Set right-to-left display.

  Parameters:

    - ws – Worksheet handle.

    - right_to_left – 1 for right-to-left, 0 for left-to-right.

void ws_topleft_cell(WorksheetHandle ws, int *row, int *col)

  Get top-left visible cell.

  Parameters:

    - ws – Worksheet handle.

    - row – Pointer to store row index.

    - col – Pointer to store column index.

void ws_set_topleft_cell(WorksheetHandle ws, int row, int col)

  Set top-left visible cell.

  Parameters:

    - ws – Worksheet handle.

    - row – Row index.

    - col – Column index.

void ws_active_cell(WorksheetHandle ws, int *row, int *col)

  Get active cell.

  Parameters:

    - ws – Worksheet handle.

    - row – Pointer to store row index.

    - col – Pointer to store column index.

void ws_set_active_cell(WorksheetHandle ws, int row, int col)

  Set active cell.

  Parameters:

    - ws – Worksheet handle.

    - row – Row index.

    - col – Column index.

void ws_split_cell(WorksheetHandle ws, int *row, int *col)

  Get split cell position.

  Parameters:

    - ws – Worksheet handle.

    - row – Pointer to store row index.

    - col – Pointer to store column index.

void ws_set_split_cell(WorksheetHandle ws, int row, int col)

  Set split cell position.

  Parameters:

    - ws – Worksheet handle.

    - row – Row index.

    - col – Column index.

int ws_display_gridlines(WorksheetHandle ws)

  Check if gridlines are displayed.

  Parameters:

    - ws – Worksheet handle.

  Returns:

    1 if gridlines displayed, 0 otherwise.

void ws_set_display_gridlines(WorksheetHandle ws, int show)

  Set gridlines display.

  Parameters:

    - ws – Worksheet handle.

    - show – 1 to show gridlines, 0 to hide.

## Page Breaks

int ws_row_break_count(WorksheetHandle ws)

  Get number of row page breaks.

  Parameters:

    - ws – Worksheet handle.

  Returns:

    Number of row breaks.

int ws_row_break(WorksheetHandle ws, int index)

  Get row page break position.

  Parameters:

    - ws – Worksheet handle.

    - index – Break index.

  Returns:

    Row index of break.

int ws_set_row_break(WorksheetHandle ws, int row, int pageBreak)

  Set row page break.

  Parameters:

    - ws – Worksheet handle.

    - row – Row index.

    - pageBreak – 1 for page break, 0 to remove.

  Returns:

    1 on success, 0 on failure.

int ws_col_break_count(WorksheetHandle ws)

  Get number of column page breaks.

  Parameters:

    - ws – Worksheet handle.

  Returns:

    Number of column breaks.

int ws_col_break(WorksheetHandle ws, int index)

  Get column page break position.

  Parameters:

    - ws – Worksheet handle.

    - index – Break index.

  Returns:

    Column index of break.

int ws_set_col_break(WorksheetHandle ws, int col, int pageBreak)

  Set column page break.

  Parameters:

    - ws – Worksheet handle.

    - col – Column index.

    - pageBreak – 1 for page break, 0 to remove.

  Returns:

    1 on success, 0 on failure.

## Print Settings

int ws_print_gridlines(WorksheetHandle ws)

  Check if gridlines are printed.

  Parameters:

    - ws – Worksheet handle.

  Returns:

    1 if printing gridlines, 0 otherwise.

void ws_set_print_gridlines(WorksheetHandle ws, int print)

  Set whether to print gridlines.

  Parameters:

    - ws – Worksheet handle.

    - print – 1 to print, 0 to not print.

int ws_print_headings(WorksheetHandle ws)

  Check if headings are printed.

  Parameters:

    - ws – Worksheet handle.

  Returns:

    1 if printing headings, 0 otherwise.

void ws_set_print_headings(WorksheetHandle ws, int print)

  Set whether to print headings.

  Parameters:

    - ws – Worksheet handle.

    - print – 1 to print, 0 to not print.

int ws_h_centered_printing(WorksheetHandle ws)

  Check if horizontal centering is enabled for printing.

  Parameters:

    - ws – Worksheet handle.

  Returns:

    1 if horizontally centered, 0 otherwise.

void ws_set_h_centered_printing(WorksheetHandle ws, int centered)

  Set horizontal centering for printing.

  Parameters:

    - ws – Worksheet handle.

    - centered – 1 to center horizontally, 0 to not center.

int ws_v_centered_printing(WorksheetHandle ws)

  Check if vertical centering is enabled for printing.

  Parameters:

    - ws – Worksheet handle.

  Returns:

    1 if vertically centered, 0 otherwise.

void ws_set_v_centered_printing(WorksheetHandle ws, int centered)

  Set vertical centering for printing.

  Parameters:

    - ws – Worksheet handle.

    - centered – 1 to center vertically, 0 to not center.

## Margins

double ws_left_margin(WorksheetHandle ws)

  Get left margin.

  Parameters:

    - ws – Worksheet handle.

  Returns:

    Left margin value.

void ws_set_left_margin(WorksheetHandle ws, double value)

  Set left margin.

  Parameters:

    - ws – Worksheet handle.

    - value – Left margin value.

double ws_right_margin(WorksheetHandle ws)

  Get right margin.

  Parameters:

    - ws – Worksheet handle.

  Returns:

    Right margin value.

void ws_set_right_margin(WorksheetHandle ws, double value)

  Set right margin.

  Parameters:

    - ws – Worksheet handle.

    - value – Right margin value.

double ws_top_margin(WorksheetHandle ws)

  Get top margin.

  Parameters:

    - ws – Worksheet handle.

  Returns:

    Top margin value.

void ws_set_top_margin(WorksheetHandle ws, double value)

  Set top margin.

  Parameters:

    - ws – Worksheet handle.

    - value – Top margin value.

double ws_bottom_margin(WorksheetHandle ws)

  Get bottom margin.

  Parameters:

    - ws – Worksheet handle.

  Returns:

    Bottom margin value.

void ws_set_bottom_margin(WorksheetHandle ws, double value)

  Set bottom margin.

  Parameters:

    - ws – Worksheet handle.

    - value – Bottom margin value.

double ws_header_margin(WorksheetHandle ws)

  Get header margin.

  Parameters:

    - ws – Worksheet handle.

  Returns:

    Header margin value.

void ws_set_header_margin(WorksheetHandle ws, double value)

  Set header margin.

  Parameters:

    - ws – Worksheet handle.

    - value – Header margin value.

double ws_footer_margin(WorksheetHandle ws)

  Get footer margin.

  Parameters:

    - ws – Worksheet handle.

  Returns:

    Footer margin value.

void ws_set_footer_margin(WorksheetHandle ws, double value)

  Set footer margin.

  Parameters:

    - ws – Worksheet handle.

    - value – Footer margin value.

## Page Setup

int ws_paper(WorksheetHandle ws)

  Get paper size.

  Parameters:

    - ws – Worksheet handle.

  Returns:

    Paper size code.

int ws_set_paper(WorksheetHandle ws, int paper_code)

  Set paper size.

  Parameters:

    - ws – Worksheet handle.

    - paper_code – Paper size code.

  Returns:

    1 on success, 0 on failure.

int ws_print_scale(WorksheetHandle ws)

  Get print scale.

  Parameters:

    - ws – Worksheet handle.

  Returns:

    Print scale percentage.

void ws_set_print_scale(WorksheetHandle ws, int zoom)

  Set print scale.

  Parameters:

    - ws – Worksheet handle.

    - zoom – Print scale percentage.

int ws_page_orientation(WorksheetHandle ws)

  Get page orientation.

  Parameters:

    - ws – Worksheet handle.

  Returns:

    Page orientation (see `PageOrientEnum`).

void ws_set_page_orientation(WorksheetHandle ws, int orientation)

  Set page orientation.

  Parameters:

    - ws – Worksheet handle.

    - orientation – Page orientation (see `PageOrientEnum`).

int ws_print_errors(WorksheetHandle ws)

  Get error printing option.

  Parameters:

    - ws – Worksheet handle.

  Returns:

    Error printing option (see `PrintErrorEnum`).

void ws_set_print_errors(WorksheetHandle ws, int way)

  Set error printing option.

  Parameters:

    - ws – Worksheet handle.

    - way – Error printing option (see `PrintErrorEnum`).

int ws_fit_page_height(WorksheetHandle ws)

  Get fit to page height setting.

  Parameters:

    - ws – Worksheet handle.

  Returns:

    Number of pages tall to fit.

void ws_set_fit_page_height(WorksheetHandle ws, int num)

  Set fit to page height.

  Parameters:

    - ws – Worksheet handle.

    - num – Number of pages tall to fit (0 to disable).

int ws_fit_page_width(WorksheetHandle ws)

  Get fit to page width setting.

  Parameters:

    - ws – Worksheet handle.

  Returns:

    Number of pages wide to fit.

void ws_set_fit_page_width(WorksheetHandle ws, int num)

  Set fit to page width.

  Parameters:

    - ws – Worksheet handle.

    - num – Number of pages wide to fit (0 to disable).

## Headers and Footers

const char *ws_page_header(WorksheetHandle ws)

  Get page header.

  Parameters:

    - ws – Worksheet handle.

  Returns:

    Page header string.

void ws_set_page_header(WorksheetHandle ws, const char *header)

  Set page header.

  Parameters:

    - ws – Worksheet handle.

    - header – Page header string.

const char *ws_page_footer(WorksheetHandle ws)

  Get page footer.

  Parameters:

    - ws – Worksheet handle.

  Returns:

    Page footer string.

void ws_set_page_footer(WorksheetHandle ws, const char *footer)

  Set page footer.

  Parameters:

    - ws – Worksheet handle.

    - footer – Page footer string.

## Enumerations

See Enumerations Reference for related enumerations used by these functions.

## Usage Notes

- All row and column indices are 1-based

- Cell ranges are inclusive (start to end indices both included)

- Style handles should be released when no longer needed

- Rich text handles must be released after use

- Table handles are managed by the worksheet and don’t need explicit release

Styled using the Piccolo Theme