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:
.jpg "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:
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:
[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:
[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:
[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.