worksheet_merge_range

@brief Merge a range of cells.

@param worksheet Pointer to a lxw_worksheet instance to be updated. @param first_row The first row of the range. (All zero indexed.) @param first_col The first column of the range. @param last_row The last row of the range. @param last_col The last col of the range. @param string String to write to the merged range. @param format A pointer to a Format instance or NULL.

@return A #lxw_error code.

The %worksheet_merge_range() function allows cells to be merged together so that they act as a single area.

Excel generally merges and centers cells at same time. To get similar behavior with libxlsxwriter you need to apply a @ref format.h "Format" object with the appropriate alignment:

@code lxw_format *merge_format = workbook_add_format(workbook); format_set_align(merge_format, LXW_ALIGN_CENTER);

worksheet_merge_range(worksheet, 1, 1, 1, 3, "Merged Range", merge_format);

@endcode

It is possible to apply other formatting to the merged cells as well:

@code format_set_align (merge_format, LXW_ALIGN_CENTER); format_set_align (merge_format, LXW_ALIGN_VERTICAL_CENTER); format_set_border (merge_format, LXW_BORDER_DOUBLE); format_set_bold (merge_format); format_set_bg_color(merge_format, 0xD7E4BC);

worksheet_merge_range(worksheet, 2, 1, 3, 3, "Merged Range", merge_format);

@endcode

@image html merge.png

The %worksheet_merge_range() function writes a char* string using worksheet_write_string(). In order to write other data types, such as a number or a formula, you can overwrite the first cell with a call to one of the other write functions. The same Format should be used as was used in the merged range.

@code // First write a range with a blank string. worksheet_merge_range (worksheet, 1, 1, 1, 3, "", format);

// Then overwrite the first cell with a number. worksheet_write_number(worksheet, 1, 1, 123, format); @endcode

@note Merged ranges generally don’t work in libxlsxwriter when the Workbook #lxw_workbook_options constant_memory mode is enabled.

Meta