ComPDFKit
Contact Sales
PDF SDKIDPConversion SDK
PDF SDK
DownloadFAQTechnical Support
Guides

Background ​

The background refers to the underlying layer or pattern on the document pages, used to present the fundamental visual effect of the document. Adding a background can alter the document's appearance, making it more personalized or professional. It can be used to emphasize a brand, protect copyright, or enhance the reading experience of the document.

In a PDF document, only one background can exist, and adding a new background to pages containing an existing background will overwrite the old background.

Set Color Background ​

The steps to set a color background are as follows:

  1. Obtain the document's background object.

  2. Set the background type to color.

  3. Configure the properties of the background.

  4. Update the background of the document.

This example shows how to set the color background:

swift
let url = URL(fileURLWithPath: "File Path")
let document = CPDFDocument(url: url)

let background = document?.background()
background?.type = .color
background?.color = .black // Background color (image background not applicable).
background?.opacity = 1.0 // Background transparency, with a range of values from 0 to 1, defaulting to 1.
background?.scale = 1.0 // Background tiling ratio.
background?.rotation = 0 // Background rotation angle, with a range of values from 0 to 360, defaulting to 0 (rotation around the page center).
background?.horizontalAlignment = 1 // Horizontal alignment of the background. `0` represents left alignment, `1` represents center alignment, and `2` represents right alignment.
background?.verticalAlignment = 1 // Vertical alignment of the background. `0` represents top alignment, `1` represents center alignment, and `2` represents bottom alignment.
background?.xOffset = 0 // Horizontal offset of the background. Positive values indicate a rightward offset, while negative values indicate a leftward offset.
background?.yOffset = 0 // Vertical offset of the background. Positive values indicate a downward offset, while negative values indicate an upward offset.
background?.pageString = "0,1,2" // Background page range, for example, "0,3,5-7".
background?.update()
objective-c
NSURL *url = [NSURL fileURLWithPath:@""];
CPDFDocument *document = [[CPDFDocument alloc] initWithURL:url];

CPDFBackground *background = document.background;
background.type = CPDFBackgroundTypeColor;
background.color = [UIColor blackColor]; // Background color (image background not applicable).
background.opacity = 1.0; // Background transparency, with a range of values from 0 to 1, defaulting to 1.
background.scale = 1.0; // Background tiling ratio.
background.rotation = 0; // Background rotation angle, with a range of values from 0 to 360, defaulting to 0 (rotation around the page center).
background.horizontalAlignment = 1; // Horizontal alignment of the background. `0` represents left alignment, `1` represents center alignment, and `2` represents right alignment.
background.verticalAlignment = 1; // Vertical alignment of the background. `0` represents top alignment, `1` represents center alignment, and `2` represents bottom alignment.。
background.xOffset = 0; // Horizontal offset of the background. Positive values indicate a rightward offset, while negative values indicate a leftward offset.
background.yOffset = 0; // Vertical offset of the background. Positive values indicate a downward offset, while negative values indicate an upward offset.
background.pageString = @"0,1,2"; // Background page range, for example, "0,3,5-7".
[background update];

Set Image Background ​

Setting the image background involves the following steps:

  1. Obtain the document background object.

  2. Set the background type to an image.

  3. Specify the background properties.

  4. Update the background on the document.

This example shows how to set the image background:

swift
let url = URL(fileURLWithPath: "File Path")
let document = CPDFDocument(url: url)

let imagePath = ""
if let image = UIImage(contentsOfFile: imagePath) {
    let background = document?.background()
    background?.setImage(image)
    background?.type = .image
    background?.opacity = 1.0 // Background transparency, with a range of values from 0 to 1, defaulting to 1.
    background?.scale = 1.0 // Background image repetition.
    background?.rotation = 0 // Background rotation angle, with a range of values from 0 to 360, defaulting to 0 (rotation around the page center).
    background?.horizontalAlignment = 1 // Vertical alignment of the background. `0` represents top alignment, `1` represents center alignment, and `2` represents bottom alignment.
    background?.verticalAlignment = 1 // Horizontal alignment of the background. `0` represents left alignment, `1` represents center alignment, and `2` represents right alignment.
    background?.xOffset = 0 // Horizontal offset of the background. Positive values indicate a rightward offset, while negative values indicate a leftward offset.
    background?.yOffset = 0 // Vertical offset of the background. Positive values indicate a downward offset, while negative values indicate an upward offset.
    background?.pageString = "0,1,2" // Set the background page range through a string, for example, "0,3,5-7".
    background?.update()
}
objective-c
NSURL *url = [NSURL fileURLWithPath:@""];
CPDFDocument *document = [[CPDFDocument alloc] initWithURL:url];

NSString *imagePath = @"";
UIImage *image = [[UIImage alloc] initWithContentsOfFile:imagePath];

CPDFBackground *background = document.background;
[background setImage:image];
background.type = CPDFBackgroundTypeImage;
background.opacity = 1.0; // Background transparency, with a range of values from 0 to 1, defaulting to 1.
background.scale = 1.0; // Background image repetition.
background.rotation = 0; // Background rotation angle, with a range of values from 0 to 360, defaulting to 0 (rotation around the page center).
background.horizontalAlignment = 1; // Vertical alignment of the background. `0` represents top alignment, `1` represents center alignment, and `2` represents bottom alignment.
background.verticalAlignment = 1; // Horizontal alignment of the background. `0` represents left alignment, `1` represents center alignment, and `2` represents right alignment.
background.xOffset = 0; // Horizontal offset of the background. Positive values indicate a rightward offset, while negative values indicate a leftward offset.
background.yOffset = 0; // Vertical offset of the background. Positive values indicate a downward offset, while negative values indicate an upward offset.
background.pageString = @"0,1,2"; // Set the background page range through a string, for example, "0,3,5-7".
[background update];

Remove Background ​

Removing the background follows these steps:

  1. Obtain the document background object.

  2. remove the document background.

The steps to remove the background are as follows:

swift
let background = document?.background()

background?.clear()
objective-c
CPDFBackground *background = [document background];
    
[background clear];