*****
Theme
*****

A "theme" refers to a collection of predefined design elements that can be
applied to a workbook, worksheet, chart, or any other element within Excel.
Themes include a combination of *colors*, *fonts*, and *effects* that provide
a consistent look of the workbooks.

By using themes, you can quickly change the overall look of workbook without
needing to individually format each component. 

Workbook theme
==============

A theme of a workbook is represented by the ``IXLTheme`` interface. It can be
accessed through ``IXLWorkbook.Theme`` property.

The theme consists of three parts:

* Color scheme - colors that can be used in a workbook.
* Font scheme - two fonts that can be used in a workbook.
* Effects - how should various objects look like, mostly shapes.

.. image:: img/theme-dialog-color-scheme.png
   :alt: The theme color scheme dialog in Excel.

.. image:: img/theme-dialog-font-scheme.png
   :alt: The theme font scheme dialog in Excel.

.. image:: img/theme-dialog-effects.png
   :alt: The theme effects dialog in Excel. 

A new created workbook has its theme set to the **Office 2007-2010**.

Each theme part can be modified independently of others. In order to modify the
theme, change the properties of the ``IXLTheme``.

.. code-block:: csharp
   :caption: Modify the theme color for a workbook.

   using var wb = new XLWorkbook();
   var ws = wb.AddWorksheet();
   var red = XLColor.FromHtml("FF0000");
   wb.Theme.Text2 = red;
   wb.SaveAs("theme-modified.xlsx");

.. image:: img/theme-changed-theme.png
   :alt: The theme of a workbook with changed theme color Text2.

.. warning::
   Only theme colors are loaded/saved from/to a workbook.
   
   As of 0.103, there is no capability to load font scheme or effects. The font
   scheme and effects saved to the file are always **Office 2007-2010**.

.. note::
   Themes displayed in Excel are version dependent, Microsoft might add or
   remove themes across versions.
   
   The Excel will highlight/select the theme in GUI depending on the values of
   the theme (e.g. color values from the color scheme), not the theme name.
   
   If the values of a part in a workbook don't match any Excel predefined values,
   no predefined item is highlighted.

Colors scheme
=============

The theme color can be created from static method
``XLColor.FromTheme(XLThemeColor)``. The theme color is a symbolic name and
doesn't contain actual color value. The color can be used by any API that
accepts ``XLColor``, e.g. cell fill, font color, sparkline and others.

.. code-block:: csharp
   :caption: Create a workbook with theme color

   using var wb = new XLWorkbook();
   var ws = wb.AddWorksheet();
   var accent2ThemeColor = XLColor.FromTheme(XLThemeColor.Accent2);
   ws.Cell("A1").Style.Fill.BackgroundColor = accent2ThemeColor;
   wb.SaveAs("theme-color-picker-font-color.xlsx");

.. image:: img/theme-color-picker-fill-color.png
   :alt: The output of the code sample, a workbook with a cell filled with a theme color.

The actual displayed color is determined by a theme and when theme colors change,
so does the fill color.

.. note::
   In order to get actual RGB value of a theme color, either use
   ``XLWorkbook.Theme.ResolveThemeColor(XLThemeColor)`` or one of ``IXLTheme``
   properties (e.g. ``XLWorkbook.Theme.Accent2``).
   
   The ``XLColor.Color`` throws an exception, because ``XLColor`` is a value
   object independent of a workbook and  thus has no way to resolve the color
   by itself and other potential problems (e.g. use color from one workbook
   in a different workbook).

.. image:: img/theme-color-picker-fill-color-hover.png
   :alt: Demonstration how chaning color scheme causes a different color to be used.

Font scheme
===========

Theme contains two font specifications, called *major* and *minor* font scheme.
To assign one of the font schemes to a text, set the the font property
``IXLFontBase.FontScheme`` to one of the schemes.

The font scheme can be set to any text through its font property. The font of
such text is updated, when a font scheme is changed in a theme.

.. code-block:: csharp
   :caption: Create a workbook with font in a scheme

   using var wb = new XLWorkbook();
   var ws = wb.AddWorksheet();
   
   ws.Cell("A1")
       .SetValue("Major")
       .Style.Font.SetFontScheme(XLFontScheme.Major);
   ws.Cell("A1")
       .SetValue("Minor")
       .Style.Font.SetFontScheme(XLFontScheme.Minor);
   wb.SaveAs("theme-font-scheme.xlsx");

.. image:: img/theme-font-scheme.png
   :alt: Demonstration how chaning the font scheme is updated when theme is changed.

Effects
=======

.. warning::
   Effects are not implemented.