Compartilhar via


DocumentBackground Class

Document Background.When the object is serialized out as xml, its qualified name is w:background.

Inheritance Hierarchy

System.Object
  DocumentFormat.OpenXml.OpenXmlElement
    DocumentFormat.OpenXml.OpenXmlCompositeElement
      DocumentFormat.OpenXml.Wordprocessing.DocumentBackground

Namespace:  DocumentFormat.OpenXml.Wordprocessing
Assembly:  DocumentFormat.OpenXml (in DocumentFormat.OpenXml.dll)

Syntax

'Declaration
<ChildElementInfoAttribute(GetType(Background))> _
Public Class DocumentBackground _
    Inherits OpenXmlCompositeElement
'Usage
Dim instance As DocumentBackground
[ChildElementInfoAttribute(typeof(Background))]
public class DocumentBackground : OpenXmlCompositeElement

Remarks

The following table lists the possible child types:

  • DocumentFormat.OpenXml.Vml.Background <v:background>

[ISO/IEC 29500-1 1st Edition]

17.2.1 background (Document Background)

This element specifies the background for every page of the document containing the background element. A document's background is the image or fill for the entire page surface, behind all other document content.

The drawing §17.3.3.9 child elements of the background element allows any DrawingML effect to be applied to the document's background.

For solid color fill backgrounds, however, the attributes on this element allow the use of any RGB or theme color value (the latter a reference to the document's themes part).

[Example: Consider a document which utilizes a gradient fill background moving between black and the accent3 theme color, as follows:

DocumentFormat.OpenXml.Wordprocessing.DocumentBack

This background would require the following WordprocessingML markup:

<w:background w:themeColor="accent3">
<w:drawing>
<wp:inline … >
<a:graphic>
<a:graphicData … >
…
</a:graphicData>
</a:graphic>
</wp:inline>
</w:drawing></w:background>

The resulting background consists of a single color fill of the accent3 theme color from the themeColor attribute, layered under a gradientCenter fill. end example]

Parent Elements

document (§17.2.3); glossaryDocument (§17.12.10)

Child Elements

Subclause

drawing (DrawingML Object)

§17.3.3.9

Attributes

Description

color (Background Color)

Specifies the color for the background of the document.

This value can be defined as either:

  • A color value using the RGB color model whose red, green, and blue values are written as numbers in the range 0 to 255, hex encoded, and concatenated. [Example: Full intensity red would be 255 red, 0 green, 0 blue, encoded to FF, 00, 00, and concatenated to FF0000. end example]. RGB colors are specified in the sRGB color space.

  • auto to allow a consumer to automatically determine the background color in order to make the document's text readable. [Example: A document with white text and a background color of auto might result in the use of a black background, in order to ensure legibility of the content. end example]

If the background specifies the use of a theme color via the themeColor attribute, this value is ignored. [Note: Applications are discouraged from specifying both the color and themeColor attributes on the same parent element. end note]

[Example: Consider a background color with value 2C34FF, as follows:

<w:background … w:color="2C34FF"/>

The background color is therefore the color with RGB value 44,52,255 (the decimal decoding of the hex value above). end example]

The possible values for this attribute are defined by the ST_HexColor simple type (§17.18.38).

themeColor (Background Theme Color)

Specifies the base theme color used to generate the background color. The background color is the RGB value associated with themeColor as further transformed by themeTint or themeShade (if one is present), else the background color is the RGB value associated with themeColor.

The specified theme color is a reference to one of the predefined theme colors, located in the document's Theme part (§14.2.7 and §20.1.6.9), which allows color information to be set centrally in the document.

If the color attribute is specified, its value shall be ignored in favor of the color resulting from the use of this attribute with any appropriate themeTint and themeShade attribute value calculations applied.

To determine the color to display, the following actions are performed:

  • Using the mapping specified in the ST_ThemeColor simple type (§17.18.97), the appropriate attribute on the clrSchemeMapping element (§17.15.1.20) is read.

  • Using that value and the mapping specified in the ST_ColorSchemeIndex simple type (§17.18.103), the appropriate element in the document’s Theme part is read to get the base theme color.

  • The specified color is modified based on the presence of the themeTint or themeShade attribute.

[Example: Consider a background configured to use the accent5 theme color, resulting in the following WordprocessingML markup:

<w:background w:themeColor="accent5" />

If the Settings part contained the following markup:

<w:clrSchemeMapping … w:accent5="accent5"/>

and the Theme part contained the following XML markup:

<a:accent5>
<a:srgbClr val="BCBCBC"/>
</a:accent5>

the resulting background color would be BCBCBC. end example]

The possible values for this attribute are defined by the ST_ThemeColor simple type (§17.18.97).

themeShade (Background Theme Color Shade)

Specifies the shade value applied to the supplied theme color (if any) for this background. If the themeColor attribute is not specified, this attribute shall not be specified.

If the themeShade is supplied, then it is applied to the RGB value of the theme color (from the theme part) to determine the final color applied to this background.

The themeShade value is stored as a hex encoding of the shade value (from 0–255) applied to the current background.

[Example: Consider a shade of 60% applied to a background in a document. This shade is calculated as follows:

The resulting themeShade value in the file format would be 99. end example]

Given an RGB color defined as three hex values in RRGGBB format, the shade is applied as follows:

  • Convert the color to the HSL color format (values from 0 to 1)

  • Modify the luminance factor as follows:

  • Convert the resultant HSL color to RGB

[Example: Consider a document with a background using the accent2 theme color, whose RGB value (in RRGGBB hex format) is C0504D.

The equivalent HSL color value would be.

Applying the shade formula with a shade percentage of 75% to the luminance, we get:

Taking the resulting HSL color value of and converting back to RGB, we get 943634.

This transformed value can be seen in the resulting background's color attribute:

<w:background w:color="943634" w:themeColor="accent2" w:themeShade="BF"/>

end example]

The possible values for this attribute are defined by the ST_UcharHexNumber simple type (§17.18.98).

themeTint (Background Theme Color Tint)

Specifies the tint value applied to the supplied theme color (if any) for this background. If the themeColor attribute is not specified, this attribute shall not be specified.

If the themeTint is supplied, then it is applied to the RGB value of the theme color (from the theme part) to determine the final color applied to the document's background.

The themeTint value is stored as a hex encoding of the tint value (from 0–255) applied to the current background.

[Example: Consider a tint of 60% applied to a background in a document. This tint is calculated as follows:

The resulting themeTint value in the file format would be 66. end example]

Given an RGB color defined as three hex values in RRGGBB format, the shade is applied as follows:

  • Convert the color to the HSL color format (values from 0 to 1)

  • Modify the luminance factor as follows:

  • Convert the resultant HSL color to RGB

[Example: Consider a document with a background using the accent2 theme color, whose RGB value (in RRGGBB hex format) is 4F81BD.

The equivalent HSL color value would be.

Applying the tint formula with a tint percentage of 60% to the luminance, we get:

Taking the resulting HSL color value of and converting back to RGB, we get 95B3D7.

This transformed value can be seen in the resulting background's color attribute:

<w:background w:color="95B3D7" w:themeColor="accent2" w:themeTint="99"/>

end example]

The possible values for this attribute are defined by the ST_UcharHexNumber simple type (§17.18.98).

[Note: The W3C XML Schema definition of this element’s content model (CT_Background) is located in §A.1. end note]

© ISO/IEC29500: 2008.

Thread Safety

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

See Also

Reference

DocumentBackground Members

DocumentFormat.OpenXml.Wordprocessing Namespace