Each Excel document has a single color palette that manages formatting colors and some drawing layer colors. A color palette contains 56 colors in Excel binary (.xls) format. Each of these colors may be customized, but changing a color in the palette will affect all formatting that uses the referenced color.

When ExcelWriter opens a workbook that does not contain an explicitly defined palette, or when ExcelWriter creates a new workbook, it uses the same default color palette that Excel uses. ExcelWriter never automatically adds colors to the palette.

Workbook.Palette returns a Palette object that represents the workbook's color palette. A Color object represents a single color in the palette.

To replace a color in the palette with a new color, call either of the following methods:

If you copy an object or cells with a custom color to another workbook, the custom color is replaced by the color in the corresponding position on the other workbook's color palette. To retain the custom color, either copy the customized color palette to the other workbook or change the corresponding color in the workbook.

If you are not sure that a specific color exists in the palette, and you want to assign the color to an element in the workbook, you can call Palette.GetClosestColor. Pass the method the red, green, and blue values of the ideal color. Palette.GetColor retrieves the color with the exact RGB value specified; if this color is not in the palette, an exception will be thrown.

A workbook's palette contains ten system colors that are fixed and cannot be changed by the user: SystemAutomaticFill, SystemAutomaticLine SystemBlack, SystemBlue, SystemCyan, SystemGreen, SystemMagenta, SystemRed, SystemWhite, and SystemYellow.

Drawing objects (pictures, shapes, comments, etc.) support custom RGB colors that may or may not be present in the palette. If you modify the color of an AutoShape (right-click the shape and select "Format AutoShape"), for example, and select a non-palette custom color, the change will not affect the workbook palette or other elements in the workbook to which the replaced color was assigned. To set custom values for shape fill and line colors, use Shape.SetCustomFillColor and Shape.SetCustomLineColor.

Example

Wherever type Color is referenced in the following example, the type is SoftArtisans.OfficeWriter.ExcelWriter.Color. If you are using ExcelWriter in a class that imports the .NET framework class System.Drawing (added by default by when a new webform is added to a VS.NET project), you will get an "ambiguous reference" error at compile-time because System.Drawing also contains a type Color. The solution is to either remove the System.Drawing import statement, or use the fully qualified name of ExcelWriter's Color object. 

private void SetupColors(Workbook wb)
{

     //--- Workbook.Palette returns the Palette object
     Palette pal = wb.Palette;

     //--- GetClosestColor finds the color in the palette
     //--- that most closely matches the specified Red,
     //--- Green, and Blue values.
     Color clrDarkBlue = pal.GetClosestColor(0, 0, 255);
     Color clrTitleCell = pal.GetClosestColor(100, 100, 255);
   
     try
     {
          //--- GetColor will find the exact color you request.
          //--- If the color does not exist in the palette
          //--- it will throw IllegalArgumentException.
          Color clrDarkGreen = pal.GetColor(51, 153, 102);
     }
     catch
     {
          //--- The color you requested was not found in the palette
     }

     //--- GetColorAt gets the color from the palette at
     //--- the specified index.  This retrieves the second
     //--- color from the palette.
     Color clrComment = pal.GetColorAt(1);

     //--- SetColor and SetColorAt are for changing
     //--- the colors in the palette. Specify a Color to
     //--- change for SetColor, the index of the color for
     //--- SetColorAt, and then the RGB values for the desired
     //--- appearance.
     pal.SetColor(clrDarkBlue, 0, 0, 200);
     pal.SetColorAt(0, 0, 255, 0);

     //--- The Color object has built-in colors
     Color clrSysGreen = Color.SystemColor.Green;
     Color clrSysBlack = Color.SystemColor.Black;
}

private void StylizeHeaderCharacters(Workbook wb, Worksheet ws)
{
     Palette pal = wb.Palette;

     //--- Get a reference to cell A1
     Cell cellHeader = ws[0, 0];

     Color clrDarkBlue = pal.GetClosestColor(0, 0, 255);
     Color clrDarkGreen = pal.GetColor(51, 153, 102);

     //--- Stylize the first word, starting from the
     //--- first character, ending at the 10th
     cellHeader.GetCharacters(0, 10).Font.Size = 12;

     //--- Format the font for the next two words in the cell
     cellHeader.GetCharacters(11, 12).Font.Color = clrDarkBlue;
     cellHeader.GetCharacters(24, 12).Font.Color = clrDarkGreen;
}