xlsgen > overview > Chart theme

Themes is a mechanism in xlsgen for choosing visual styles for charts and other workbook elements with just one line of code.

The workbook interface exposes a ThemeManager object and an enumeration type that lets a client application which theme it is interested in. Among more than 40 themes :

typedef enum
{
  [helpstring("Workbook Theme, classic (Excel 2003)")]      workbooktheme_classic     = 0,
  [helpstring("Workbook Theme, modern (Excel 2007)")]    workbooktheme_modern   = 1
  [helpstring("Workbook Theme, olive")]                           workbooktheme_olive   = 2,
  [helpstring("Workbook Theme, marine")]                        workbooktheme_marine  = 3
  [helpstring("Workbook Theme, office")]               workbooktheme_office       = 4,
  [helpstring("Workbook Theme, adjacency")]            workbooktheme_adjacency    = 5,
  [helpstring("Workbook Theme, angles")]               workbooktheme_angles       = 6,
  [helpstring("Workbook Theme, apex")]                 workbooktheme_apex         = 7,
  [helpstring("Workbook Theme, apothecary")]           workbooktheme_apothecary   = 8,
  [helpstring("Workbook Theme, aspect")]               workbooktheme_aspect       = 9,
  [helpstring("Workbook Theme, austin")]               workbooktheme_austin       = 10,
  [helpstring("Workbook Theme, black tie")]            workbooktheme_blacktie     = 11,
  [helpstring("Workbook Theme, civic")]                workbooktheme_civic        = 12,
  [helpstring("Workbook Theme, clarity")]              workbooktheme_clarity      = 13,
  [helpstring("Workbook Theme, composite")]            workbooktheme_composite    = 14,
  [helpstring("Workbook Theme, concourse")]            workbooktheme_concourse    = 15,
  [helpstring("Workbook Theme, couture")]              workbooktheme_coutoure     = 16,
  [helpstring("Workbook Theme, elemental")]            workbooktheme_elemental    = 17,
  [helpstring("Workbook Theme, equity")]               workbooktheme_equity       = 18,
  [helpstring("Workbook Theme, essential")]            workbooktheme_essential    = 19,
  [helpstring("Workbook Theme, executive")]            workbooktheme_executive    = 20,
  [helpstring("Workbook Theme, flow")]                 workbooktheme_flow         = 21,
  [helpstring("Workbook Theme, foundry")]              workbooktheme_foundry      = 22,
  [helpstring("Workbook Theme, grid")]                 workbooktheme_grid         = 23,
  [helpstring("Workbook Theme, hardcover")]            workbooktheme_hardcover    = 24,
  [helpstring("Workbook Theme, horizon")]              workbooktheme_horizon      = 25,
  [helpstring("Workbook Theme, median")]               workbooktheme_median       = 26,
  [helpstring("Workbook Theme, metro")]                workbooktheme_metro        = 27,
  [helpstring("Workbook Theme, module")]               workbooktheme_module       = 28,
  [helpstring("Workbook Theme, newsprint")]            workbooktheme_newsprint    = 29,
  [helpstring("Workbook Theme, opulent")]              workbooktheme_opulent      = 30,
  [helpstring("Workbook Theme, oriel")]                workbooktheme_oriel        = 31,
  [helpstring("Workbook Theme, origin")]               workbooktheme_origin       = 32,
  [helpstring("Workbook Theme, paper")]                workbooktheme_paper        = 33,
  [helpstring("Workbook Theme, perspective")]          workbooktheme_perspective  = 34,
  [helpstring("Workbook Theme, pushpin")]              workbooktheme_pushpin      = 35,
  [helpstring("Workbook Theme, slipstream")]           workbooktheme_slipstream   = 36,
  [helpstring("Workbook Theme, solstice")]             workbooktheme_solstice     = 37,
  [helpstring("Workbook Theme, technic")]              workbooktheme_technic      = 38,
  [helpstring("Workbook Theme, thatch")]               workbooktheme_thatch       = 39,
  [helpstring("Workbook Theme, trek")]                 workbooktheme_trek         = 40,
  [helpstring("Workbook Theme, urban")]                workbooktheme_urban        = 41,
  [helpstring("Workbook Theme, verve")]                workbooktheme_verve        = 42,
  [helpstring("Workbook Theme, waveform")]             workbooktheme_waveform     = 43


} enumWorkbookTheme;

Classic theme is really Excel 2003 looking, particularly for charts.

Modern theme however is more Excel 2013 looking, particularly for charts. For instance, compared to classic theme a number of formatting elements look different by default : many borders are removed ; bars use gradient fill ; lines are thicker ; the legend does not show up unless there are at least two series ; etc.

xlsgen defaults to the modern theme. If you are willing to use classic instead, all it takes is the following :

workbook.ThemeManager.Theme = enumWorkbookTheme.workbooktheme_classic;

Here are more examples of differences between modern and classic.

Olive theme

The alternate olive theme uses a number of olive-like colors.

workbook.ThemeManager.Theme = enumWorkbookTheme.workbooktheme_olive;

When used, the olive theme produces charts like these :

Marine theme

The marine theme uses a number of marine-like colors.

workbook.ThemeManager.Theme = enumWorkbookTheme.workbooktheme_marine;

Additional themes will be introduced in the future.

Default theme

xlsgen defaults to the Elemental theme with Adjacency colors.

To be more accurate, it uses Elemental for fonts and effects, but it uses the Adjacency theme colors. Indeed a theme is made of 3 independent sections : colors, fonts and effects, and a client application may choose a different theme for each section, among the 40+ themes. The Elemental colors were shades of blue, and we believe it would be more appropriate to use a more diverse set of colors. That is why we choose Adjacency colors.

It is equivalent to writing the following in code, except you don't have to :

workbook.ThemeManager.Theme = enumWorkbookTheme.workbooktheme_elemental;
workbook.ThemeManager.CustomColors = enumWorkbookTheme.workbooktheme_adjacency;

Another mechanism built in Excel starting with version 2007 (that is, all XLSX files), is chart styles. Any of 48 built-in chart styles, and can be found in Excel by selecting a chart first, which prompts the Chart tabs in the ribbon, then clicking on the Design tab in order to show the styles. Here is a screen capture of the built-in chart styles preview for a bar chart :

The 48 styles are spread around two axis, vertically the effect span, horizontally the color span. Each row thus has 8 color variants : the grayscale, the automatic colors, and then 6 primary theme color selections. There are 6 rows accounting for 4 gradual effect spans : no effect, subtle effect, moderate effect, intense effect, and then two more rows for the classic Excel 2003 mode and the intense dark mode (dark background which may be white depending on your system background and foreground colors).

How it works in xlsgen is quite simple. Here is a piece of code in C++ for a creating a pie chart with, as in the example above, the moderate effect, and auto colors :

xlsgen::IXlsWorksheetPtr wksht001 = workbook->AddWorksheet( L"Sheet1" );

// make sure to disable modern themes
workbook->ThemeManager->Theme = xlsgen::workbooktheme_classic;

xlsgen::IXlsChartPtr chart001s0 = wksht001->NewChart(xlsgen::charttype_pie2D, 5, 2, 20, 9);

// chart theme
chart001s0->Theme->EffectSpan = xlsgen::chartthemeeffectspan_moderate;
chart001s0->Theme->ColorSpan = xlsgen::chartthemecolorspan_auto;

xlsgen::IXlsChartDynamicDataSourcePtr datasource001s0 = chart001s0->DynamicDataSource;

xlsgen::IXlsChartDynamicDataSourceSeriesPtr serie001s0ss0 = datasource001s0->AddSerie();
serie001s0ss0->SeriesValuesFormula = L"={2;5;4}";
chart001s0->SurfaceArea->Options->Patterns->Area->Type = xlsgen::chartareatype_custom;
chart001s0->SurfaceArea->Options->Patterns->Area->Pattern->PatternStyle = xlsgen::chartareapattern_solid;
chart001s0->SurfaceArea->Options->Patterns->Area->Pattern->BackgroundColor = 0xB4DDE7;
chart001s0->PlotArea->Options->Patterns->Borders->Type = xlsgen::chartbordertype_none;
chart001s0->PlotArea->Options->Patterns->Area->Type = xlsgen::chartareatype_none;
chart001s0->CustomProperties->PieExplodedSliceDistance = 0;
chart001s0->Legend->Show = xlsgen::chartlegend_right;
chart001s0->SeriesByIndex[1]->DataElements[2]->PieExplodedSliceDistance = 12;

The resulting chart generated with the source code above.

Technically speaking, each of the above 48 chart styles are dependent on the current theme being used, which means the look of charts may differ greatly depending on the theme being used for the spreadsheet. The theme is for all charts of the spreadsheet, whereas the chart style can differ in each chart.

Another chart type, with the same chart theme.