.. _worksheet-c-api:

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
---------------------

.. c:function:: int ws_min_row(WorksheetHandle ws)

    Get the minimum row index.

    :param ws: Worksheet handle.
    :return: Minimum row index.

.. c:function:: int ws_max_row(WorksheetHandle ws)

    Get the maximum row index.

    :param ws: Worksheet handle.
    :return: Maximum row index.

.. c:function:: int ws_min_col(WorksheetHandle ws)

    Get the minimum column index.

    :param ws: Worksheet handle.
    :return: Minimum column index.

.. c:function:: int ws_max_col(WorksheetHandle ws)

    Get the maximum column index.

    :param ws: Worksheet handle.
    :return: Maximum column index.

.. c:function:: const char* ws_name(WorksheetHandle ws)

    Get the worksheet name.

    :param ws: Worksheet handle.
    :return: Worksheet name.

.. c:function:: int ws_set_name(WorksheetHandle ws, const char* newname)

    Set the worksheet name.

    :param ws: Worksheet handle.
    :param newname: New worksheet name.
    :return: 1 on success, 0 on failure.

.. c:function:: int ws_ws_type(WorksheetHandle ws)

    Get the worksheet type.

    :param ws: Worksheet handle.
    :return: Worksheet type (see :cpp:enum:`SheetTypeEnum`).

.. c:function:: int ws_get_ws_state(WorksheetHandle ws)

    Get the worksheet state.

    :param ws: Worksheet handle.
    :return: Worksheet state (see :cpp:enum:`SheetStateEnum`).

Cell Data Operations
--------------------

.. c:function:: int ws_cell_type(WorksheetHandle ws, int row, int col)

    Get the cell data type.

    :param ws: Worksheet handle.
    :param row: Row index.
    :param col: Column index.
    :return: Cell type (see :cpp:enum:`CellTypeEnum`).

.. c:function:: int ws_contains_formula(WorksheetHandle ws, int row, int col)

    Check if cell contains formula.

    :param ws: Worksheet handle.
    :param row: Row index.
    :param col: Column index.
    :return: 1 if contains formula, 0 otherwise.

.. c:function:: int ws_contains_richtext(WorksheetHandle ws, int row, int col)

    Check if cell contains rich text.

    :param ws: Worksheet handle.
    :param row: Row index.
    :param col: Column index.
    :return: 1 if contains rich text, 0 otherwise.

.. c:function:: double ws_get_num(WorksheetHandle ws, int row, int col)

    Get numeric value from cell.

    :param ws: Worksheet handle.
    :param row: Row index.
    :param col: Column index.
    :return: Numeric value.

.. c:function:: const char* ws_get_text(WorksheetHandle ws, int row, int col)

    Get text value from cell.

    :param ws: Worksheet handle.
    :param row: Row index.
    :param col: Column index.
    :return: Text string.

.. c:function:: int ws_get_boolean(WorksheetHandle ws, int row, int col)

    Get boolean value from cell.

    :param ws: Worksheet handle.
    :param row: Row index.
    :param col: Column index.
    :return: Boolean value (1=true, 0=false).

.. c:function:: double ws_get_datetime(WorksheetHandle ws, int row, int col)

    Get datetime value from cell.

    :param ws: Worksheet handle.
    :param row: Row index.
    :param col: Column index.
    :return: DateTime value as double.

.. c:function:: RichtextHandle ws_get_richtext(WorksheetHandle ws, int row, int col)

    Get rich text from cell.

    :param ws: Worksheet handle.
    :param row: Row index.
    :param col: Column index.
    :return: Rich text handle.

.. c:function:: const char* ws_get_formula_expr(WorksheetHandle ws, int row, int col)

    Get formula expression from cell.

    :param ws: Worksheet handle.
    :param row: Row index.
    :param col: Column index.
    :return: Formula expression.

.. c:function:: int ws_get_error(WorksheetHandle ws, int row, int col)

    Get error code from cell.

    :param ws: Worksheet handle.
    :param row: Row index.
    :param col: Column index.
    :return: Error code (see :cpp:enum:`ErrorCodeEnum`).

Cell Data Setting
-----------------

.. c:function:: int ws_set_num(WorksheetHandle ws, int row, int col, double val)

    Set numeric value to cell.

    :param ws: Worksheet handle.
    :param row: Row index.
    :param col: Column index.
    :param val: Numeric value.
    :return: 1 on success, 0 on failure.

.. c:function:: int ws_set_text(WorksheetHandle ws, int row, int col, const char* val)

    Set text value to cell.

    :param ws: Worksheet handle.
    :param row: Row index.
    :param col: Column index.
    :param val: Text string.
    :return: 1 on success, 0 on failure.

.. c:function:: int ws_set_boolean(WorksheetHandle ws, int row, int col, int b)

    Set boolean value to cell.

    :param ws: Worksheet handle.
    :param row: Row index.
    :param col: Column index.
    :param b: Boolean value (1=true, 0=false).
    :return: 1 on success, 0 on failure.

.. c:function:: int ws_set_datetime(WorksheetHandle ws, int row, int col, double dt)

    Set datetime value to cell.

    :param ws: Worksheet handle.
    :param row: Row index.
    :param col: Column index.
    :param dt: DateTime value as double.
    :return: 1 on success, 0 on failure.

.. c:function:: int ws_set_richtext(WorksheetHandle ws, int row, int col, RichtextHandle rt)

    Set rich text to cell.

    :param ws: Worksheet handle.
    :param row: Row index.
    :param col: Column index.
    :param rt: Rich text handle.
    :return: 1 on success, 0 on failure.

.. c:function:: int ws_set_error(WorksheetHandle ws, int row, int col, int code)

    Set error value to cell.

    :param ws: Worksheet handle.
    :param row: Row index.
    :param col: Column index.
    :param code: Error code (see :cpp:enum:`ErrorCodeEnum`).
    :return: 1 on success, 0 on failure.

Formula Operations
------------------

.. c:function:: int ws_set_formula(WorksheetHandle ws, int row, int col, const char* expr)

    Set formula to cell.

    :param ws: Worksheet handle.
    :param row: Row index.
    :param col: Column index.
    :param expr: Formula expression.
    :return: 1 on success, 0 on failure.

.. c:function:: int ws_set_formula_num(WorksheetHandle ws, int row, int col, double val)

    Set formula with numeric result.

    :param ws: Worksheet handle.
    :param row: Row index.
    :param col: Column index.
    :param val: Numeric result value.
    :return: 1 on success, 0 on failure.

.. c:function:: int ws_set_formula_string(WorksheetHandle ws, int row, int col, const char* s)

    Set formula with string result.

    :param ws: Worksheet handle.
    :param row: Row index.
    :param col: Column index.
    :param s: String result value.
    :return: 1 on success, 0 on failure.

.. c:function:: int ws_set_formula_boolean(WorksheetHandle ws, int row, int col, int b)

    Set formula with boolean result.

    :param ws: Worksheet handle.
    :param row: Row index.
    :param col: Column index.
    :param b: Boolean result value.
    :return: 1 on success, 0 on failure.

.. c:function:: int ws_set_formula_datetime(WorksheetHandle ws, int row, int col, double dt)

    Set formula with datetime result.

    :param ws: Worksheet handle.
    :param row: Row index.
    :param col: Column index.
    :param dt: DateTime result value.
    :return: 1 on success, 0 on failure.

.. c:function:: int ws_set_formula_error(WorksheetHandle ws, int row, int col, int code)

    Set formula with error result.

    :param ws: Worksheet handle.
    :param row: Row index.
    :param col: Column index.
    :param code: Error result code.
    :return: 1 on success, 0 on failure.

.. c:function:: void ws_clear_contents(WorksheetHandle ws, int begin_row, int begin_col, int end_row, int end_col)

    Clear cell contents in specified range.

    :param ws: Worksheet handle.
    :param begin_row: Start row index.
    :param begin_col: Start column index.
    :param end_row: End row index.
    :param end_col: End column index.

Cell Styling
------------

.. c:function:: void ws_set_cell_style(WorksheetHandle ws, int row, int col, StyleHandle style)

    Set style for specific cell.

    :param ws: Worksheet handle.
    :param row: Row index.
    :param col: Column index.
    :param style: Style handle.

.. c:function:: StyleHandle ws_cell_style(WorksheetHandle ws, int row, int col)

    Get style from specific cell.

    :param ws: Worksheet handle.
    :param row: Row index.
    :param col: Column index.
    :return: Style handle.

.. c:function:: StyleHandle ws_get_cell_style(WorksheetHandle ws, int row, int col)

    Get cell style (alias of ws_cell_style).

    :param ws: Worksheet handle.
    :param row: Row index.
    :param col: Column index.
    :return: Style handle.

.. c:function:: 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.

    :param ws: Worksheet handle.
    :param start_row: Start row index.
    :param start_col: Start column index.
    :param stop_row: End row index.
    :param stop_col: End column index.
    :param style: Style handle.

Row and Column Dimensions
-------------------------

.. c:function:: int ws_is_default_row_height(WorksheetHandle ws, int start, int end)

    Check if rows have default height.

    :param ws: Worksheet handle.
    :param start: Start row index.
    :param end: End row index.
    :return: 1 if default height, 0 otherwise.

.. c:function:: int ws_get_custom_row_height(WorksheetHandle ws, int start, int end, double* height, int unit)

    Get custom row height.

    :param ws: Worksheet handle.
    :param start: Start row index.
    :param end: End row index.
    :param height: Pointer to store height value.
    :param unit: Height unit (see :cpp:enum:`RowHeightUnitEnum`).
    :return: 1 if custom height exists, 0 otherwise.

.. c:function:: void ws_set_custom_row_height(WorksheetHandle ws, int start, int end, double height, int unit)

    Set custom row height.

    :param ws: Worksheet handle.
    :param start: Start row index.
    :param end: End row index.
    :param height: Height value.
    :param unit: Height unit (see :cpp:enum:`RowHeightUnitEnum`).

.. c:function:: int ws_is_default_col_width(WorksheetHandle ws, int start, int end)

    Check if columns have default width.

    :param ws: Worksheet handle.
    :param start: Start column index.
    :param end: End column index.
    :return: 1 if default width, 0 otherwise.

.. c:function:: int ws_get_custom_col_width(WorksheetHandle ws, int start, int end, double* width, int unit)

    Get custom column width.

    :param ws: Worksheet handle.
    :param start: Start column index.
    :param end: End column index.
    :param width: Pointer to store width value.
    :param unit: Width unit (see :cpp:enum:`ColWidthUnitEnum`).
    :return: 1 if custom width exists, 0 otherwise.

.. c:function:: void ws_set_custom_col_width(WorksheetHandle ws, int start, int end, double width, int unit)

    Set custom column width.

    :param ws: Worksheet handle.
    :param start: Start column index.
    :param end: End column index.
    :param width: Width value.
    :param unit: Width unit (see :cpp:enum:`ColWidthUnitEnum`).

Row and Column Styling
----------------------

.. c:function:: StyleHandle ws_row_style(WorksheetHandle ws, int row)

    Get style for entire row.

    :param ws: Worksheet handle.
    :param row: Row index.
    :return: Style handle.

.. c:function:: void ws_remove_row_style(WorksheetHandle ws, int row)

    Remove style from entire row.

    :param ws: Worksheet handle.
    :param row: Row index.

.. c:function:: void ws_set_row_style(WorksheetHandle ws, int start_row, int stop_row, StyleHandle style)

    Set style for row range.

    :param ws: Worksheet handle.
    :param start_row: Start row index.
    :param stop_row: End row index.
    :param style: Style handle.

.. c:function:: StyleHandle ws_col_style(WorksheetHandle ws, int col)

    Get style for entire column.

    :param ws: Worksheet handle.
    :param col: Column index.
    :return: Style handle.

.. c:function:: void ws_remove_col_style(WorksheetHandle ws, int col)

    Remove style from entire column.

    :param ws: Worksheet handle.
    :param col: Column index.

.. c:function:: void ws_set_col_style(WorksheetHandle ws, int start_col, int stop_col, StyleHandle style)

    Set style for column range.

    :param ws: Worksheet handle.
    :param start_col: Start column index.
    :param stop_col: End column index.
    :param style: Style handle.

Row and Column Visibility
-------------------------

.. c:function:: int ws_row_hidden(WorksheetHandle ws, int row)

    Check if row is hidden.

    :param ws: Worksheet handle.
    :param row: Row index.
    :return: 1 if hidden, 0 otherwise.

.. c:function:: void ws_set_row_hidden(WorksheetHandle ws, int start_row, int stop_row, int hidden)

    Set row hidden status.

    :param ws: Worksheet handle.
    :param start_row: Start row index.
    :param stop_row: End row index.
    :param hidden: 1 to hide, 0 to show.

.. c:function:: int ws_col_hidden(WorksheetHandle ws, int col)

    Check if column is hidden.

    :param ws: Worksheet handle.
    :param col: Column index.
    :return: 1 if hidden, 0 otherwise.

.. c:function:: void ws_set_col_hidden(WorksheetHandle ws, int start_col, int stop_col, int hidden)

    Set column hidden status.

    :param ws: Worksheet handle.
    :param start_col: Start column index.
    :param stop_col: End column index.
    :param hidden: 1 to hide, 0 to show.

Row and Column Operations
-------------------------

.. c:function:: int ws_insert_row(WorksheetHandle ws, int row, int count)

    Insert rows.

    :param ws: Worksheet handle.
    :param row: Starting row index.
    :param count: Number of rows to insert.
    :return: 1 on success, 0 on failure.

.. c:function:: int ws_delete_row(WorksheetHandle ws, int begin, int end)

    Delete rows.

    :param ws: Worksheet handle.
    :param begin: Start row index.
    :param end: End row index.
    :return: 1 on success, 0 on failure.

.. c:function:: int ws_insert_col(WorksheetHandle ws, int col, int count)

    Insert columns.

    :param ws: Worksheet handle.
    :param col: Starting column index.
    :param count: Number of columns to insert.
    :return: 1 on success, 0 on failure.

.. c:function:: int ws_delete_col(WorksheetHandle ws, int begin, int end)

    Delete columns.

    :param ws: Worksheet handle.
    :param begin: Start column index.
    :param end: End column index.
    :return: 1 on success, 0 on failure.

Range Shifting
--------------

.. c:function:: int ws_shift_range_down(WorksheetHandle ws, int start_col, int end_col, int start_row, int count)

    Shift range downward.

    :param ws: Worksheet handle.
    :param start_col: Start column index.
    :param end_col: End column index.
    :param start_row: Start row index.
    :param count: Number of rows to shift.
    :return: 1 on success, 0 on failure.

.. c:function:: int ws_shift_range_up(WorksheetHandle ws, int start_col, int end_col, int start_row, int count)

    Shift range upward.

    :param ws: Worksheet handle.
    :param start_col: Start column index.
    :param end_col: End column index.
    :param start_row: Start row index.
    :param count: Number of rows to shift.
    :return: 1 on success, 0 on failure.

.. c:function:: int ws_shift_range_right(WorksheetHandle ws, int start_row, int end_row, int start_col, int count)

    Shift range to the right.

    :param ws: Worksheet handle.
    :param start_row: Start row index.
    :param end_row: End row index.
    :param start_col: Start column index.
    :param count: Number of columns to shift.
    :return: 1 on success, 0 on failure.

.. c:function:: int ws_shift_range_left(WorksheetHandle ws, int start_row, int end_row, int start_col, int count)

    Shift range to the left.

    :param ws: Worksheet handle.
    :param start_row: Start row index.
    :param end_row: End row index.
    :param start_col: Start column index.
    :param count: Number of columns to shift.
    :return: 1 on success, 0 on failure.

Images and Background
---------------------

.. c:function:: void ws_set_bg_picture(WorksheetHandle ws, const char* file)

    Set worksheet background picture.

    :param ws: Worksheet handle.
    :param file: Image file path.

.. c:function:: 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.

    :param ws: Worksheet handle.
    :param file: Image file path.
    :param start_row: Start row index.
    :param start_col: Start column index.
    :param stop_row: End row index.
    :param stop_col: End column index.
    :return: Image index.

.. c:function:: 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.

    :param ws: Worksheet handle.
    :param file: Path to the image file.
    :param row1: Row index of the top-left anchor cell.
    :param col1: Column index of the top-left anchor cell.
    :param row2: Row index of the bottom-right anchor cell.
    :param col2: Column index of the bottom-right anchor cell.
    :param offset_x1: Horizontal offset from the top-left anchor cell (in pixels).
    :param offset_y1: Vertical offset from the top-left anchor cell (in pixels).
    :param offset_x2: Horizontal offset from the bottom-right anchor cell (in pixels).
    :param offset_y2: Vertical offset from the bottom-right anchor cell (in pixels).
    :returns: ID of the added image.

.. c:function:: 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.

    :param ws: Worksheet handle.
    :param file: Path to the image file.
    :param row: Row index of the anchor cell.
    :param col: Column index of the anchor cell.
    :param width: Desired width of the image in pixels (0 to use scaling).
    :param height: Desired height of the image in pixels (0 to use scaling).
    :param scale: Scaling factor for the image (used when width and height are 0).
    :param offset_x: Horizontal offset from the anchor cell (in pixels).
    :param offset_y: Vertical offset from the anchor cell (in pixels).
    :returns: ID of the added image.

.. c:function:: 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.
 
    :param ws: Worksheet handle.
    :param file: Path to the image file.
    :param x: X-coordinate (in pixels) for the top-left corner of the image.
    :param y: Y-coordinate (in pixels) for the top-left corner of the image.
    :param width: Desired width of the image in pixels (0 to use scaling).
    :param height: Desired height of the image in pixels (0 to use scaling).
    :param scale: Scaling factor for the image (used when width and height are 0).
    :returns: ID of the added image.

.. c:function:: int ws_image_num(WorksheetHandle ws)

    Get the total number of images currently in the worksheet.

    :param ws: Worksheet handle.
    :returns: Number of images.

.. c:function:: int ws_get_image_id(WorksheetHandle ws, int index)

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

    :param ws: Worksheet handle.
    :param index: Zero‑based index of the image (order of insertion).
    :returns: Image ID.

.. c:function:: ImageAnchorEnum ws_image_anchor_type(WorksheetHandle ws, int image_id)

    Get the anchoring type of the specified image.

    :param ws: Worksheet handle.
    :param image_id: ID of the target image.
    :returns: An enumeration value of type ImageAnchorEnum.

.. c:function:: 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.

    :param ws: Worksheet handle.
    :param image_id: ID of the target image.
    :param row: Pointer to store the row index of the anchor cell.
    :param col: Pointer to store the column index of the anchor cell.
    :returns: true if successful, false otherwise.

.. c:function:: 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.

    :param ws: Worksheet handle.
    :param image_id: ID of the target image.
    :param x: Pointer to store the X‑coordinate (in pixels).
    :param y: Pointer to store the Y‑coordinate (in pixels).
    :returns: true if successful, false otherwise.

.. c:function:: void ws_delete_image(WorksheetHandle ws, int image_id)

    Remove an image from the worksheet by its ID.

    :param ws: Worksheet handle.
    :param image_id: ID of the image to delete.

.. c:function:: void ws_remove_image(WorksheetHandle ws, int row, int col)

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

    :param ws: Worksheet handle.
    :param row: Row index of the anchor cell.
    :param col: Column index of the anchor cell.

.. c:function:: void ws_remove_absolute_image(WorksheetHandle ws, int x, int y)

    Remove an image by its absolute anchor coordinates.

    :param ws: Worksheet handle.
    :param x: X‑coordinate (in pixels) of the image's anchor point.
    :param y: Y‑coordinate (in pixels) of the image's anchor point.

Cell Navigation
---------------

.. c:function:: int ws_first_data_cell(WorksheetHandle ws, int* row, int* col)

    Find the first cell containing data.

    :param ws: Worksheet handle.
    :param row: Pointer to store row index.
    :param col: Pointer to store column index.
    :return: 1 if found, 0 if worksheet is empty.

.. c:function:: int ws_last_data_cell(WorksheetHandle ws, int* row, int* col)

    Find the last cell containing data.

    :param ws: Worksheet handle.
    :param row: Pointer to store row index.
    :param col: Pointer to store column index.
    :return: 1 if found, 0 if worksheet is empty.

Merged Cells
------------

.. c:function:: int ws_merge_num(WorksheetHandle ws)

    Get number of merged ranges.

    :param ws: Worksheet handle.
    :return: Number of merged ranges.

.. c:function:: int ws_merged_range(WorksheetHandle ws, int index, int* start_row, int* start_col, int* stop_row, int* stop_col)

    Get a merged range.

    :param ws: Worksheet handle.
    :param index: Index of merged ranges.
    :param start_row: Pointer to store start row.
    :param start_col: Pointer to store start column.
    :param stop_row: Pointer to store end row.
    :param stop_col: Pointer to store end column.
    :return: 1 on success, 0 on failure.

.. c:function:: int ws_merge(WorksheetHandle ws, int start_row, int start_col, int stop_row, int stop_col)

    Merge cell range.

    :param ws: Worksheet handle.
    :param start_row: Start row index.
    :param start_col: Start column index.
    :param stop_row: End row index.
    :param stop_col: End column index.
    :return: 1 on success, 0 on failure.

.. c:function:: int ws_unmerge(WorksheetHandle ws, int row, int col)

    Unmerge cells at specified position.

    :param ws: Worksheet handle.
    :param row: Row index.
    :param col: Column index.
    :return: 1 on success, 0 on failure.

Table Operations
----------------

.. c:function:: int ws_tabledef_count(WorksheetHandle ws)

    Get number of tables in worksheet.

    :param ws: Worksheet handle.
    :return: Number of tables.

.. c:function:: const char* ws_get_tabledef_name(WorksheetHandle ws, int index)

    Get table name by index.

    :param ws: Worksheet handle.
    :param index: Table index.
    :return: Table name.

.. c:function:: int ws_set_tabledef_name(WorksheetHandle ws, int index, const char* new_name)

    Set table name.

    :param ws: Worksheet handle.
    :param index: Table index.
    :param new_name: New table name.
    :return: 1 on success, 0 on failure.

.. c:function:: TabledefHandle ws_get_tabledef(WorksheetHandle ws, int index)

    Get table handle by index.

    :param ws: Worksheet handle.
    :param index: Table index.
    :return: Table handle.

.. c:function:: TabledefHandle ws_get_tabledef_by_name(WorksheetHandle ws, const char* name)

    Get table handle by name.

    :param ws: Worksheet handle.
    :param name: Table name.
    :return: Table handle.

.. c:function:: 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.

    :param ws: Worksheet handle.
    :param name: Table name.
    :param begin_row: Start row index.
    :param begin_col: Start column index.
    :param end_row: End row index.
    :param end_col: End column index.
    :return: Table handle.

.. c:function:: int ws_delete_tabledef(WorksheetHandle ws, const char* name)

    Delete table from worksheet.

    :param ws: Worksheet handle.
    :param name: Table name.
    :return: 1 on success, 0 on failure.

Grouping and Outlining
----------------------

.. c:function:: void ws_group_rows(WorksheetHandle ws, int begin_row, int end_row, int collapsed)

    Group rows.

    :param ws: Worksheet handle.
    :param begin_row: Start row index.
    :param end_row: End row index.
    :param collapsed: 1 for collapsed, 0 for expanded.

.. c:function:: void ws_ungroup_rows(WorksheetHandle ws, int begin_row, int end_row)

    Ungroup rows.

    :param ws: Worksheet handle.
    :param begin_row: Start row index.
    :param end_row: End row index.

.. c:function:: void ws_group_cols(WorksheetHandle ws, int begin_col, int end_col, int collapsed)

    Group columns.

    :param ws: Worksheet handle.
    :param begin_col: Start column index.
    :param end_col: End column index.
    :param collapsed: 1 for collapsed, 0 for expanded.

.. c:function:: void ws_ungroup_cols(WorksheetHandle ws, int begin_col, int end_col)

    Ungroup columns.

    :param ws: Worksheet handle.
    :param begin_col: Start column index.
    :param end_col: End column index.

.. c:function:: int ws_row_outline_level(WorksheetHandle ws, int row, int* collapsed)

    Get row outline level.

    :param ws: Worksheet handle.
    :param row: Row index.
    :param collapsed: Pointer to store collapsed status.
    :return: Outline level.

.. c:function:: int ws_col_outline_level(WorksheetHandle ws, int col, int* collapsed)

    Get column outline level.

    :param ws: Worksheet handle.
    :param col: Column index.
    :param collapsed: Pointer to store collapsed status.
    :return: Outline level.

.. c:function:: int ws_max_row_outline_level(WorksheetHandle ws)

    Get maximum row outline level.

    :param ws: Worksheet handle.
    :return: Maximum outline level.

.. c:function:: int ws_max_col_outline_level(WorksheetHandle ws)

    Get maximum column outline level.

    :param ws: Worksheet handle.
    :return: Maximum outline level.

.. c:function:: void ws_delete_row_outline(WorksheetHandle ws)

    Delete all row outlines.

    :param ws: Worksheet handle.

.. c:function:: void ws_delete_col_outline(WorksheetHandle ws)

    Delete all column outlines.

    :param ws: Worksheet handle.

.. c:function:: int ws_group_summary_below(WorksheetHandle ws)

    Check if group summary is below details.

    :param ws: Worksheet handle.
    :return: 1 if summary below, 0 if above.

.. c:function:: void ws_set_group_summary_below(WorksheetHandle ws, int below)

    Set group summary position.

    :param ws: Worksheet handle.
    :param below: 1 for summary below, 0 for above.

.. c:function:: int ws_group_summary_right(WorksheetHandle ws)

    Check if group summary is to the right of details.

    :param ws: Worksheet handle.
    :return: 1 if summary right, 0 if left.

.. c:function:: void ws_set_group_summary_right(WorksheetHandle ws, int right)

    Set group summary horizontal position.

    :param ws: Worksheet handle.
    :param right: 1 for summary right, 0 for left.

Hyperlinks
----------

.. c:function:: 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.

    :param ws: Worksheet handle.
    :param hyperlink: Hyperlink URL or address.
    :param start_row: Start row index.
    :param start_col: Start column index.
    :param end_row: End row index.
    :param end_col: End column index.
    :return: Hyperlink index.

.. c:function:: int ws_hyperlink_num(WorksheetHandle ws)

    Get number of hyperlinks.

    :param ws: Worksheet handle.
    :return: Number of hyperlinks.

.. c:function:: int ws_hyperlink_index(WorksheetHandle ws, int row, int col)

    Get hyperlink index for cell.

    :param ws: Worksheet handle.
    :param row: Row index.
    :param col: Column index.
    :return: Hyperlink index, or -1 if no hyperlink.

.. c:function:: const char* ws_hyperlink(WorksheetHandle ws, int index, int* start_row, int* start_col, int* end_row, int* end_col)

    Get hyperlink information.

    :param ws: Worksheet handle.
    :param index: Hyperlink index.
    :param start_row: Pointer to store start row.
    :param start_col: Pointer to store start column.
    :param end_row: Pointer to store end row.
    :param end_col: Pointer to store end column.
    :return: Hyperlink URL.

.. c:function:: int ws_delete_hyperlink(WorksheetHandle ws, int index)

    Delete hyperlink.

    :param ws: Worksheet handle.
    :param index: Hyperlink index.
    :return: 1 on success, 0 on failure.

Worksheet Protection
--------------------

.. c:function:: int ws_is_protected(WorksheetHandle ws)

    Check if worksheet is protected.

    :param ws: Worksheet handle.
    :return: 1 if protected, 0 otherwise.

.. c:function:: int ws_protect(WorksheetHandle ws, int item, const char* password)

    Protect worksheet.

    :param ws: Worksheet handle.
    :param item: Protection options (see :cpp:enum:`SheetProtectEnum`).
    :param password: Protection password.
    :return: 1 on success, 0 on failure.

.. c:function:: void ws_unprotect(WorksheetHandle ws)

    Unprotect worksheet.

    :param ws: Worksheet handle.

.. c:function:: int ws_protect_range(WorksheetHandle ws, int start_row, int start_col, int end_row, int end_col)

    Protect specific cell range.

    :param ws: Worksheet handle.
    :param start_row: Start row index.
    :param start_col: Start column index.
    :param end_row: End row index.
    :param end_col: End column index.
    :return: 1 on success, 0 on failure.

.. c:function:: 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.

    :param ws: Worksheet handle.
    :param start_row: Start row index.
    :param start_col: Start column index.
    :param end_row: End row index.
    :param end_col: End column index.
    :return: 1 on success, 0 on failure.

.. c:function:: int ws_editable_range_count(WorksheetHandle ws)

    Get number of editable ranges.

    :param ws: Worksheet handle.
    :return: Number of allowed edit ranges.

.. c:function:: 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.

    :param ws: Worksheet handle.
    :param index: Range index.
    :param start_row: Pointer to store start row.
    :param start_col: Pointer to store start column.
    :param stop_row: Pointer to store end row.
    :param stop_col: Pointer to store end column.
    :return: Range name.

.. c:function:: int ws_delete_editable_range(WorksheetHandle ws, int index)

    Delete an editable range.

    :param ws: Worksheet handle.
    :param index: Range index.
    :return: 1 on success, 0 on failure.

View and Display Settings
-------------------------

.. c:function:: int ws_zoom(WorksheetHandle ws)

    Get worksheet zoom level.

    :param ws: Worksheet handle.
    :return: Zoom percentage.

.. c:function:: void ws_set_zoom(WorksheetHandle ws, int zoom)

    Set worksheet zoom level.

    :param ws: Worksheet handle.
    :param zoom: Zoom percentage.

.. c:function:: int ws_right_to_left(WorksheetHandle ws)

    Check if right-to-left display is enabled.

    :param ws: Worksheet handle.
    :return: 1 if right-to-left, 0 otherwise.

.. c:function:: void ws_set_right_to_left(WorksheetHandle ws, int right_to_left)

    Set right-to-left display.

    :param ws: Worksheet handle.
    :param right_to_left: 1 for right-to-left, 0 for left-to-right.

.. c:function:: void ws_topleft_cell(WorksheetHandle ws, int* row, int* col)

    Get top-left visible cell.

    :param ws: Worksheet handle.
    :param row: Pointer to store row index.
    :param col: Pointer to store column index.

.. c:function:: void ws_set_topleft_cell(WorksheetHandle ws, int row, int col)

    Set top-left visible cell.

    :param ws: Worksheet handle.
    :param row: Row index.
    :param col: Column index.

.. c:function:: void ws_active_cell(WorksheetHandle ws, int* row, int* col)

    Get active cell.

    :param ws: Worksheet handle.
    :param row: Pointer to store row index.
    :param col: Pointer to store column index.

.. c:function:: void ws_set_active_cell(WorksheetHandle ws, int row, int col)

    Set active cell.

    :param ws: Worksheet handle.
    :param row: Row index.
    :param col: Column index.

.. c:function:: void ws_split_cell(WorksheetHandle ws, int* row, int* col)

    Get split cell position.

    :param ws: Worksheet handle.
    :param row: Pointer to store row index.
    :param col: Pointer to store column index.

.. c:function:: void ws_set_split_cell(WorksheetHandle ws, int row, int col)

    Set split cell position.

    :param ws: Worksheet handle.
    :param row: Row index.
    :param col: Column index.

.. c:function:: int ws_display_gridlines(WorksheetHandle ws)

    Check if gridlines are displayed.

    :param ws: Worksheet handle.
    :return: 1 if gridlines displayed, 0 otherwise.

.. c:function:: void ws_set_display_gridlines(WorksheetHandle ws, int show)

    Set gridlines display.

    :param ws: Worksheet handle.
    :param show: 1 to show gridlines, 0 to hide.

Page Breaks
-----------

.. c:function:: int ws_row_break_count(WorksheetHandle ws)

    Get number of row page breaks.

    :param ws: Worksheet handle.
    :return: Number of row breaks.

.. c:function:: int ws_row_break(WorksheetHandle ws, int index)

    Get row page break position.

    :param ws: Worksheet handle.
    :param index: Break index.
    :return: Row index of break.

.. c:function:: int ws_set_row_break(WorksheetHandle ws, int row, int pageBreak)

    Set row page break.

    :param ws: Worksheet handle.
    :param row: Row index.
    :param pageBreak: 1 for page break, 0 to remove.
    :return: 1 on success, 0 on failure.

.. c:function:: int ws_col_break_count(WorksheetHandle ws)

    Get number of column page breaks.

    :param ws: Worksheet handle.
    :return: Number of column breaks.

.. c:function:: int ws_col_break(WorksheetHandle ws, int index)

    Get column page break position.

    :param ws: Worksheet handle.
    :param index: Break index.
    :return: Column index of break.

.. c:function:: int ws_set_col_break(WorksheetHandle ws, int col, int pageBreak)

    Set column page break.

    :param ws: Worksheet handle.
    :param col: Column index.
    :param pageBreak: 1 for page break, 0 to remove.
    :return: 1 on success, 0 on failure.

Print Settings
--------------

.. c:function:: int ws_print_gridlines(WorksheetHandle ws)

    Check if gridlines are printed.

    :param ws: Worksheet handle.
    :return: 1 if printing gridlines, 0 otherwise.

.. c:function:: void ws_set_print_gridlines(WorksheetHandle ws, int print)

    Set whether to print gridlines.

    :param ws: Worksheet handle.
    :param print: 1 to print, 0 to not print.

.. c:function:: int ws_print_headings(WorksheetHandle ws)

    Check if headings are printed.

    :param ws: Worksheet handle.
    :return: 1 if printing headings, 0 otherwise.

.. c:function:: void ws_set_print_headings(WorksheetHandle ws, int print)

    Set whether to print headings.

    :param ws: Worksheet handle.
    :param print: 1 to print, 0 to not print.

.. c:function:: int ws_h_centered_printing(WorksheetHandle ws)

    Check if horizontal centering is enabled for printing.

    :param ws: Worksheet handle.
    :return: 1 if horizontally centered, 0 otherwise.

.. c:function:: void ws_set_h_centered_printing(WorksheetHandle ws, int centered)

    Set horizontal centering for printing.

    :param ws: Worksheet handle.
    :param centered: 1 to center horizontally, 0 to not center.

.. c:function:: int ws_v_centered_printing(WorksheetHandle ws)

    Check if vertical centering is enabled for printing.

    :param ws: Worksheet handle.
    :return: 1 if vertically centered, 0 otherwise.

.. c:function:: void ws_set_v_centered_printing(WorksheetHandle ws, int centered)

    Set vertical centering for printing.

    :param ws: Worksheet handle.
    :param centered: 1 to center vertically, 0 to not center.

Margins
-------

.. c:function:: double ws_left_margin(WorksheetHandle ws)

    Get left margin.

    :param ws: Worksheet handle.
    :return: Left margin value.

.. c:function:: void ws_set_left_margin(WorksheetHandle ws, double value)

    Set left margin.

    :param ws: Worksheet handle.
    :param value: Left margin value.

.. c:function:: double ws_right_margin(WorksheetHandle ws)

    Get right margin.

    :param ws: Worksheet handle.
    :return: Right margin value.

.. c:function:: void ws_set_right_margin(WorksheetHandle ws, double value)

    Set right margin.

    :param ws: Worksheet handle.
    :param value: Right margin value.

.. c:function:: double ws_top_margin(WorksheetHandle ws)

    Get top margin.

    :param ws: Worksheet handle.
    :return: Top margin value.

.. c:function:: void ws_set_top_margin(WorksheetHandle ws, double value)

    Set top margin.

    :param ws: Worksheet handle.
    :param value: Top margin value.

.. c:function:: double ws_bottom_margin(WorksheetHandle ws)

    Get bottom margin.

    :param ws: Worksheet handle.
    :return: Bottom margin value.

.. c:function:: void ws_set_bottom_margin(WorksheetHandle ws, double value)

    Set bottom margin.

    :param ws: Worksheet handle.
    :param value: Bottom margin value.

.. c:function:: double ws_header_margin(WorksheetHandle ws)

    Get header margin.

    :param ws: Worksheet handle.
    :return: Header margin value.

.. c:function:: void ws_set_header_margin(WorksheetHandle ws, double value)

    Set header margin.

    :param ws: Worksheet handle.
    :param value: Header margin value.

.. c:function:: double ws_footer_margin(WorksheetHandle ws)

    Get footer margin.

    :param ws: Worksheet handle.
    :return: Footer margin value.

.. c:function:: void ws_set_footer_margin(WorksheetHandle ws, double value)

    Set footer margin.

    :param ws: Worksheet handle.
    :param value: Footer margin value.

Page Setup
----------

.. c:function:: int ws_paper(WorksheetHandle ws)

    Get paper size.

    :param ws: Worksheet handle.
    :return: Paper size code.

.. c:function:: int ws_set_paper(WorksheetHandle ws, int paper_code)

    Set paper size.

    :param ws: Worksheet handle.
    :param paper_code: Paper size code.
    :return: 1 on success, 0 on failure.

.. c:function:: int ws_print_scale(WorksheetHandle ws)

    Get print scale.

    :param ws: Worksheet handle.
    :return: Print scale percentage.

.. c:function:: void ws_set_print_scale(WorksheetHandle ws, int zoom)

    Set print scale.

    :param ws: Worksheet handle.
    :param zoom: Print scale percentage.

.. c:function:: int ws_page_orientation(WorksheetHandle ws)

    Get page orientation.

    :param ws: Worksheet handle.
    :return: Page orientation (see :cpp:enum:`PageOrientEnum`).

.. c:function:: void ws_set_page_orientation(WorksheetHandle ws, int orientation)

    Set page orientation.

    :param ws: Worksheet handle.
    :param orientation: Page orientation (see :cpp:enum:`PageOrientEnum`).

.. c:function:: int ws_print_errors(WorksheetHandle ws)

    Get error printing option.

    :param ws: Worksheet handle.
    :return: Error printing option (see :cpp:enum:`PrintErrorEnum`).

.. c:function:: void ws_set_print_errors(WorksheetHandle ws, int way)

    Set error printing option.

    :param ws: Worksheet handle.
    :param way: Error printing option (see :cpp:enum:`PrintErrorEnum`).

.. c:function:: int ws_fit_page_height(WorksheetHandle ws)

    Get fit to page height setting.

    :param ws: Worksheet handle.
    :return: Number of pages tall to fit.

.. c:function:: void ws_set_fit_page_height(WorksheetHandle ws, int num)

    Set fit to page height.

    :param ws: Worksheet handle.
    :param num: Number of pages tall to fit (0 to disable).

.. c:function:: int ws_fit_page_width(WorksheetHandle ws)

    Get fit to page width setting.

    :param ws: Worksheet handle.
    :return: Number of pages wide to fit.

.. c:function:: void ws_set_fit_page_width(WorksheetHandle ws, int num)

    Set fit to page width.

    :param ws: Worksheet handle.
    :param num: Number of pages wide to fit (0 to disable).

Headers and Footers
-------------------

.. c:function:: const char* ws_page_header(WorksheetHandle ws)

    Get page header.

    :param ws: Worksheet handle.
    :return: Page header string.

.. c:function:: void ws_set_page_header(WorksheetHandle ws, const char* header)

    Set page header.

    :param ws: Worksheet handle.
    :param header: Page header string.

.. c:function:: const char* ws_page_footer(WorksheetHandle ws)

    Get page footer.

    :param ws: Worksheet handle.
    :return: Page footer string.

.. c:function:: void ws_set_page_footer(WorksheetHandle ws, const char* footer)

    Set page footer.

    :param ws: Worksheet handle.
    :param footer: Page footer string.

Enumerations
------------

See :ref:`enum-api` 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
