chart: add initial layout support

Feature: #477

include/xlsxwriter/chart.h

@@ -737,6 +737,29 @@ typedef struct lxw_chart_font {
 
 } lxw_chart_font;
 
+/**
+ * @brief Struct to represent Excel chart element layout dimensions.
+ *
+ * todo:
+ */
+typedef struct lxw_chart_layout {
+
+    /** TODO:*/
+    double x;
+
+    /** TODO:*/
+    double y;
+
+    /** TODO:*/
+    double width;
+
+    /** TODO:*/
+    double height;
+
+    uint8_t has_inner;
+
+} lxw_chart_layout;
+
 typedef struct lxw_chart_marker {
 
     uint8_t type;
@@ -751,6 +774,7 @@ typedef struct lxw_chart_legend {
 
     lxw_chart_font *font;
     uint8_t position;
+    lxw_chart_layout *layout;
 
 } lxw_chart_legend;
 
@@ -769,6 +793,7 @@ typedef struct lxw_chart_title {
     lxw_series_range *range;
 
     struct lxw_series_data_point data_point;
+    lxw_chart_layout *layout;
 
 } lxw_chart_title;
 
@@ -1149,8 +1174,10 @@ typedef struct lxw_chart {
     lxw_chart_line *chartarea_line;
     lxw_chart_fill *chartarea_fill;
     lxw_chart_pattern *chartarea_pattern;
+
     lxw_chart_line *plotarea_line;
     lxw_chart_fill *plotarea_fill;
+    lxw_chart_layout *plotarea_layout;
     lxw_chart_pattern *plotarea_pattern;
 
     uint8_t has_drop_lines;
@@ -3279,6 +3306,14 @@ void chart_title_set_name_font(lxw_chart *chart, lxw_chart_font *font);
  */
 void chart_title_off(lxw_chart *chart);
 
+/**
+ * @brief TODO: Add description.
+ *
+ * @param chart  Pointer to a lxw_chart instance to be configured.
+ * @param layout A pointer to a chart #lxw_chart_layout struct.
+ */
+void chart_title_set_layout(lxw_chart *self, lxw_chart_layout * layout);
+
 /**
  * @brief Set the position of the chart legend.
  *
@@ -3317,6 +3352,16 @@ void chart_title_off(lxw_chart *chart);
  */
 void chart_legend_set_position(lxw_chart *chart, uint8_t position);
 
+/**
+ * @brief Set the layout of the chart legend.
+ *
+ * @param chart  Pointer to a lxw_chart instance to be configured.
+ * @param layout A pointer to a chart #lxw_chart_layout struct.
+ *
+ * TODO: Add example and image.
+ */
+void chart_legend_set_layout(lxw_chart *chart, lxw_chart_layout * layout);
+
 /**
  * @brief Set the font properties for a chart legend.
  *
@@ -3484,6 +3529,14 @@ void chart_plotarea_set_fill(lxw_chart *chart, lxw_chart_fill *fill);
  */
 void chart_plotarea_set_pattern(lxw_chart *chart, lxw_chart_pattern *pattern);
 
+/**
+ * @brief Set the layout of a plotarea. TODO:
+ *
+ * @param chart
+ * @param layout
+ */
+void chart_plotarea_set_layout(lxw_chart *chart, lxw_chart_layout * layout);
+
 /**
  * @brief Set the chart style type.
  *

src/chart.c

@@ -225,18 +225,22 @@ lxw_chart_free(lxw_chart *chart)
     _chart_free_font(chart->title.font);
     _chart_free_range(chart->title.range);
     free(chart->title.name);
+    free(chart->title.layout);
 
     /* Chart legend. */
     _chart_free_font(chart->legend.font);
-    free(chart->delete_series);
+    free(chart->legend.layout);
 
+    free(chart->delete_series);
     free(chart->default_marker);
 
     free(chart->chartarea_line);
     free(chart->chartarea_fill);
     free(chart->chartarea_pattern);
+
     free(chart->plotarea_line);
     free(chart->plotarea_fill);
+    free(chart->plotarea_layout);
     free(chart->plotarea_pattern);
 
     free(chart->drop_lines_line);
@@ -449,6 +453,24 @@ _chart_convert_pattern_args(lxw_chart_pattern *user_pattern)
     return pattern;
 }
 
+/*
+ * Create a copy of a user supplied layout.
+ */
+STATIC lxw_chart_layout *
+_chart_convert_layout_args(lxw_chart_layout *user_layout)
+{
+    lxw_chart_layout *layout = calloc(1, sizeof(struct lxw_chart_layout));
+    RETURN_ON_MEM_ERROR(layout, NULL);
+
+    /* Copy the user supplied properties. */
+    layout->x = user_layout->x;
+    layout->y = user_layout->y;
+    layout->width = user_layout->width;
+    layout->height = user_layout->height;
+
+    return layout;
+}
+
 /*
  * Set a marker type for a series.
  */
@@ -645,13 +667,101 @@ _chart_write_style(lxw_chart *self)
     LXW_FREE_ATTRIBUTES();
 }
 
+/*
+ * Write the <c:layoutTarget> element.
+ */
+STATIC void
+_chart_write_layout_target(lxw_chart *self)
+{
+    struct xml_attribute_list attributes;
+    struct xml_attribute *attribute;
+
+    LXW_INIT_ATTRIBUTES();
+    LXW_PUSH_ATTRIBUTES_STR("val", "inner");
+
+    lxw_xml_empty_tag(self->file, "c:layoutTarget", &attributes);
+
+    LXW_FREE_ATTRIBUTES();
+}
+
+/*
+ * Write the <c:xMode> and <c:yMode> element.
+ */
+STATIC void
+_chart_write_layout_mode(lxw_chart *self, char *mode)
+{
+    struct xml_attribute_list attributes;
+    struct xml_attribute *attribute;
+
+    LXW_INIT_ATTRIBUTES();
+    LXW_PUSH_ATTRIBUTES_STR("val", "edge");
+
+    lxw_xml_empty_tag(self->file, mode, &attributes);
+
+    LXW_FREE_ATTRIBUTES();
+}
+
+/*
+ * Write the layout dimension elements.
+ */
+STATIC void
+_chart_write_layout_dimension(lxw_chart *self, char *dimension, double value)
+{
+    struct xml_attribute_list attributes;
+    struct xml_attribute *attribute;
+
+    LXW_INIT_ATTRIBUTES();
+    LXW_PUSH_ATTRIBUTES_DBL("val", value);
+
+    lxw_xml_empty_tag(self->file, dimension, &attributes);
+
+    LXW_FREE_ATTRIBUTES();
+}
+
+/*
+ * Write the <c:manualLayout> element.
+ */
+STATIC void
+_chart_write_manual_layout(lxw_chart *self, lxw_chart_layout *layout)
+{
+    lxw_xml_start_tag(self->file, "c:manualLayout", NULL);
+
+    /* Write the c:layoutTarget element. */
+    if (layout->has_inner)
+        _chart_write_layout_target(self);
+
+    /* Write the c:xMode and c:yMode elements. */
+    _chart_write_layout_mode(self, "c:xMode");
+    _chart_write_layout_mode(self, "c:yMode");
+
+    /* Write the dimension elements. */
+    _chart_write_layout_dimension(self, "c:x", layout->x);
+    _chart_write_layout_dimension(self, "c:y", layout->y);
+    if (layout->width > 0.0)
+        _chart_write_layout_dimension(self, "c:w", layout->width);
+    if (layout->height > 0.0)
+        _chart_write_layout_dimension(self, "c:h", layout->height);
+
+    lxw_xml_end_tag(self->file, "c:manualLayout");
+}
+
 /*
  * Write the <c:layout> element.
  */
 STATIC void
-_chart_write_layout(lxw_chart *self)
+_chart_write_layout(lxw_chart *self, lxw_chart_layout *layout)
 {
-    lxw_xml_empty_tag(self->file, "c:layout", NULL);
+    if (layout == NULL) {
+        lxw_xml_empty_tag(self->file, "c:layout", NULL);
+    }
+    else {
+        lxw_xml_start_tag(self->file, "c:layout", NULL);
+
+        /* Write the c:manualLayout element. */
+        _chart_write_manual_layout(self, layout);
+
+        lxw_xml_end_tag(self->file, "c:layout");
+    }
 }
 
 /*
@@ -1538,7 +1648,7 @@ _chart_write_title_rich(lxw_chart *self, lxw_chart_title *title)
                          title->font);
 
     /* Write the c:layout element. */
-    _chart_write_layout(self);
+    _chart_write_layout(self, self->title.layout);
 
     lxw_xml_end_tag(self->file, "c:title");
 }
@@ -1555,7 +1665,7 @@ _chart_write_title_formula(lxw_chart *self, lxw_chart_title *title)
     _chart_write_tx_formula(self, title);
 
     /* Write the c:layout element. */
-    _chart_write_layout(self);
+    _chart_write_layout(self, self->title.layout);
 
     /* Write the c:txPr element. */
     _chart_write_tx_pr(self, title->is_horizontal, title->font);
@@ -3796,7 +3906,7 @@ _chart_write_legend(lxw_chart *self)
     }
 
     /* Write the c:layout element. */
-    _chart_write_layout(self);
+    _chart_write_layout(self, self->legend.layout);
 
     if (self->chart_group == LXW_CHART_PIE
         || self->chart_group == LXW_CHART_DOUGHNUT) {
@@ -4737,7 +4847,7 @@ _chart_write_scatter_plot_area(lxw_chart *self)
     lxw_xml_start_tag(self->file, "c:plotArea", NULL);
 
     /* Write the c:layout element. */
-    _chart_write_layout(self);
+    _chart_write_layout(self, self->plotarea_layout);
 
     /* Write subclass chart type elements for primary and secondary axes. */
     self->write_chart_type(self);
@@ -4769,7 +4879,7 @@ _chart_write_pie_plot_area(lxw_chart *self)
     lxw_xml_start_tag(self->file, "c:plotArea", NULL);
 
     /* Write the c:layout element. */
-    _chart_write_layout(self);
+    _chart_write_layout(self, self->plotarea_layout);
 
     /* Write subclass chart type elements for primary and secondary axes. */
     self->write_chart_type(self);
@@ -4790,7 +4900,7 @@ _chart_write_plot_area(lxw_chart *self)
     lxw_xml_start_tag(self->file, "c:plotArea", NULL);
 
     /* Write the c:layout element. */
-    _chart_write_layout(self);
+    _chart_write_layout(self, self->plotarea_layout);
 
     /* Write subclass chart type elements for primary and secondary axes. */
     self->write_chart_type(self);
@@ -6444,6 +6554,21 @@ chart_title_off(lxw_chart *self)
     self->title.off = LXW_TRUE;
 }
 
+/*
+ * Set a layout for the chart title.
+ */
+void
+chart_title_set_layout(lxw_chart *self, lxw_chart_layout *layout)
+{
+    if (!layout)
+        return;
+
+    /* Free any previously allocated resource. */
+    free(self->title.layout);
+
+    self->title.layout = _chart_convert_layout_args(layout);
+}
+
 /*
  * Set the chart legend position.
  */
@@ -6453,6 +6578,21 @@ chart_legend_set_position(lxw_chart *self, uint8_t position)
     self->legend.position = position;
 }
 
+/*
+ * Set a layout for the chart legend.
+ */
+void
+chart_legend_set_layout(lxw_chart *self, lxw_chart_layout *layout)
+{
+    if (!layout)
+        return;
+
+    /* Free any previously allocated resource. */
+    free(self->legend.layout);
+
+    self->legend.layout = _chart_convert_layout_args(layout);
+}
+
 /*
  * Set the legend font.
  */
@@ -6584,6 +6724,24 @@ chart_plotarea_set_pattern(lxw_chart *self, lxw_chart_pattern *pattern)
     self->plotarea_pattern = _chart_convert_pattern_args(pattern);
 }
 
+/*
+ * Set a layout for the plotarea.
+ */
+void
+chart_plotarea_set_layout(lxw_chart *self, lxw_chart_layout *layout)
+{
+    if (!layout)
+        return;
+
+    /* Free any previously allocated resource. */
+    free(self->plotarea_layout);
+
+    self->plotarea_layout = _chart_convert_layout_args(layout);
+
+    /* Plotarea has an additional layout field. */
+    self->plotarea_layout->has_inner = LXW_TRUE;
+}
+
 /*
  * Turn on the chart data table.
  */

test/functional/src/test_chart_layout01.c

@@ -0,0 +1,51 @@
+/*****************************************************************************
+ * Test cases for libxlsxwriter.
+ *
+ * Test to compare output against Excel files.
+ *
+ * Copyright 2014-2025, John McNamara, jmcnamara@cpan.org
+ *
+ */
+
+#include "xlsxwriter.h"
+
+int main() {
+
+    lxw_workbook  *workbook  = workbook_new("test_chart_layout01.xlsx");
+    lxw_worksheet *worksheet = workbook_add_worksheet(workbook, NULL);
+    lxw_chart     *chart     = workbook_add_chart(workbook, LXW_CHART_COLUMN);
+
+    /* For testing, copy the randomly generated axis ids in the target file. */
+    chart->axis_id_1 = 69198592;
+    chart->axis_id_2 = 69200128;
+
+    uint8_t data[5][3] = {
+        {1, 2,  3},
+        {2, 4,  6},
+        {3, 6,  9},
+        {4, 8,  12},
+        {5, 10, 15}
+    };
+
+    int row, col;
+    for (row = 0; row < 5; row++)
+        for (col = 0; col < 3; col++)
+            worksheet_write_number(worksheet, row, col, data[row][col], NULL);
+
+    chart_add_series(chart, NULL, "=Sheet1!$A$1:$A$5");
+    chart_add_series(chart, NULL, "=Sheet1!$B$1:$B$5");
+    chart_add_series(chart, NULL, "=Sheet1!$C$1:$C$5");
+
+    lxw_chart_layout layout = {
+        .x = 0.13171062992125,
+        .y = 0.26436351706036,
+        .width = 0.73970734908136,
+        .height = 0.5713732137649,
+    };
+
+    chart_plotarea_set_layout(chart, &layout);
+
+    worksheet_insert_chart(worksheet, CELL("E9"), chart);
+
+    return workbook_close(workbook);
+}

test/functional/src/test_chart_layout02.c

@@ -0,0 +1,51 @@
+/*****************************************************************************
+ * Test cases for libxlsxwriter.
+ *
+ * Test to compare output against Excel files.
+ *
+ * Copyright 2014-2025, John McNamara, jmcnamara@cpan.org
+ *
+ */
+
+#include "xlsxwriter.h"
+
+int main() {
+
+    lxw_workbook  *workbook  = workbook_new("test_chart_layout02.xlsx");
+    lxw_worksheet *worksheet = workbook_add_worksheet(workbook, NULL);
+    lxw_chart     *chart     = workbook_add_chart(workbook, LXW_CHART_COLUMN);
+
+    /* For testing, copy the randomly generated axis ids in the target file. */
+    chart->axis_id_1 = 68311296;
+    chart->axis_id_2 = 69198208;
+
+    uint8_t data[5][3] = {
+        {1, 2,  3},
+        {2, 4,  6},
+        {3, 6,  9},
+        {4, 8,  12},
+        {5, 10, 15}
+    };
+
+    int row, col;
+    for (row = 0; row < 5; row++)
+        for (col = 0; col < 3; col++)
+            worksheet_write_number(worksheet, row, col, data[row][col], NULL);
+
+    chart_add_series(chart, NULL, "=Sheet1!$A$1:$A$5");
+    chart_add_series(chart, NULL, "=Sheet1!$B$1:$B$5");
+    chart_add_series(chart, NULL, "=Sheet1!$C$1:$C$5");
+
+    lxw_chart_layout layout = {
+        .x = 0.80197353455818,
+        .y = 0.37442403032954,
+        .width = 0.12858202099737,
+        .height = 0.25115157480314,
+    };
+
+    chart_legend_set_layout(chart, &layout);
+
+    worksheet_insert_chart(worksheet, CELL("E9"), chart);
+
+    return workbook_close(workbook);
+}

test/functional/src/test_chart_layout03.c

@@ -0,0 +1,52 @@
+/*****************************************************************************
+ * Test cases for libxlsxwriter.
+ *
+ * Test to compare output against Excel files.
+ *
+ * Copyright 2014-2025, John McNamara, jmcnamara@cpan.org
+ *
+ */
+
+#include "xlsxwriter.h"
+
+int main() {
+
+    lxw_workbook  *workbook  = workbook_new("test_chart_layout03.xlsx");
+    lxw_worksheet *worksheet = workbook_add_worksheet(workbook, NULL);
+    lxw_chart     *chart     = workbook_add_chart(workbook, LXW_CHART_COLUMN);
+
+    /* For testing, copy the randomly generated axis ids in the target file. */
+    chart->axis_id_1 = 68312064;
+    chart->axis_id_2 = 69198592;
+
+    uint8_t data[5][3] = {
+        {1, 2,  3},
+        {2, 4,  6},
+        {3, 6,  9},
+        {4, 8,  12},
+        {5, 10, 15}
+    };
+
+    int row, col;
+    for (row = 0; row < 5; row++)
+        for (col = 0; col < 3; col++)
+            worksheet_write_number(worksheet, row, col, data[row][col], NULL);
+
+    chart_add_series(chart, NULL, "=Sheet1!$A$1:$A$5");
+    chart_add_series(chart, NULL, "=Sheet1!$B$1:$B$5");
+    chart_add_series(chart, NULL, "=Sheet1!$C$1:$C$5");
+
+    lxw_chart_layout layout = {
+        .x = 0.80197353455818,
+        .y = 0.37442403032954,
+        .width = 0.12858202099737,
+        .height = 0.25115157480314,
+    };
+
+    chart_legend_set_layout(chart, &layout);
+    chart_legend_set_position(chart, LXW_CHART_LEGEND_OVERLAY_RIGHT);
+
+    worksheet_insert_chart(worksheet, CELL("E9"), chart);
+
+    return workbook_close(workbook);
+}

test/functional/src/test_chart_layout04.c

@@ -0,0 +1,52 @@
+/*****************************************************************************
+ * Test cases for libxlsxwriter.
+ *
+ * Test to compare output against Excel files.
+ *
+ * Copyright 2014-2025, John McNamara, jmcnamara@cpan.org
+ *
+ */
+
+#include "xlsxwriter.h"
+
+int main() {
+
+    lxw_workbook  *workbook  = workbook_new("test_chart_layout04.xlsx");
+    lxw_worksheet *worksheet = workbook_add_worksheet(workbook, NULL);
+    lxw_chart     *chart     = workbook_add_chart(workbook, LXW_CHART_COLUMN);
+
+    /* For testing, copy the randomly generated axis ids in the target file. */
+    chart->axis_id_1 = 68311296;
+    chart->axis_id_2 = 69198208;
+
+    uint8_t data[5][3] = {
+        {1, 2,  3},
+        {2, 4,  6},
+        {3, 6,  9},
+        {4, 8,  12},
+        {5, 10, 15}
+    };
+
+    int row, col;
+    for (row = 0; row < 5; row++)
+        for (col = 0; col < 3; col++)
+            worksheet_write_number(worksheet, row, col, data[row][col], NULL);
+
+    chart_add_series(chart, NULL, "=Sheet1!$A$1:$A$5");
+    chart_add_series(chart, NULL, "=Sheet1!$B$1:$B$5");
+    chart_add_series(chart, NULL, "=Sheet1!$C$1:$C$5");
+
+
+    lxw_chart_layout layout = {
+        .x = 0.426319335083114,
+        .y = 0.143518518518518,
+    };
+
+    chart_title_set_layout(chart, &layout);
+    chart_title_set_name(chart, "Title");
+
+
+    worksheet_insert_chart(worksheet, CELL("E9"), chart);
+
+    return workbook_close(workbook);
+}

test/functional/test_chart_layout.py

@@ -0,0 +1,27 @@
+###############################################################################
+#
+# Tests for libxlsxwriter.
+#
+# SPDX-License-Identifier: BSD-2-Clause
+# Copyright 2014-2025, John McNamara, jmcnamara@cpan.org.
+#
+
+import base_test_class
+
+class TestCompareXLSXFiles(base_test_class.XLSXBaseTest):
+    """
+    Test file created with libxlsxwriter against a file created by Excel.
+
+    """
+
+    def test_chart_layout01(self):
+        self.run_exe_test('test_chart_layout01')
+
+    def test_chart_layout02(self):
+        self.run_exe_test('test_chart_layout02')
+
+    def test_chart_layout03(self):
+        self.run_exe_test('test_chart_layout03')
+
+    def test_chart_layout04(self):
+        self.run_exe_test('test_chart_layout04')