How to Add Background Image to Table in iText7

To add a background image to a table in iText7 using BackgroundImage and PdfXObject, you need to first create a PdfXObject from your image, then use that PdfXObject to create a BackgroundImage object, and finally apply it to the table using setBackgroundImage(). The key is to use PdfXObject.createXObject() with your image data, then pass that to the BackgroundImage.Builder().

Contents

• Understanding BackgroundImage and PdfXObject in iText7
• Creating PdfXObject from an Image
• Creating BackgroundImage Object
• Applying Background to Table
• Complete Kotlin Code Example
• Alternative Approaches
• Troubleshooting Common Issues

Understanding BackgroundImage and PdfXObject in iText7

In iText7, BackgroundImage is a specialized class used for adding background images to various layout elements, including tables. Unlike the older iText5 versions, iText7 uses a more object-oriented approach where you need to work with PdfXObject objects rather than direct image references.

The iText documentation explains that PdfXObject represents a PDF object (like an image) that can be used in various contexts throughout the PDF document. When you want to add a background image to a table, you need to:

1. Load your image data
2. Create a PdfXObject from that image data
3. Use the PdfXObject to create a BackgroundImage
4. Apply the BackgroundImage to your table

This approach provides better performance and more control over how images are handled in the PDF document.

Creating PdfXObject from an Image

To create a PdfXObject from an image in Kotlin, you need to use the PdfXObject.createXObject() method with your image data. Here’s how to do it:

import com.itextpdf.io.image.ImageData
import com.itextpdf.io.image.ImageDataFactory
import com.itextpdf.kernel.pdf.PdfXObject

// Load your image from a file or input stream
val imageData = ImageDataFactory.create("path/to/your/image.png")

// Create PdfXObject from the image data
val pdfXObject = PdfXObject.createXObject(imageData)

The ImageDataFactory provides various methods to create ImageData from different sources:

• ImageDataFactory.create(File) - from a file
• ImageDataFactory.create(InputStream) - from an input stream
• ImageDataFactory.create(byte[]) - from byte array
• ImageDataFactory.create(URL) - from a URL

According to the GitHub examples, this is the standard approach for converting images to iText7 objects.

Creating BackgroundImage Object

Once you have your PdfXObject, you can create a BackgroundImage object using the builder pattern:

import com.itextpdf.layout.BackgroundImage

// Create BackgroundImage using PdfXObject
val backgroundImage = BackgroundImage.Builder()
    .setImage(pdfXObject)
    .setOpacity(1f) // Optional: set opacity (0.0 to 1.0)
    .build()

The BackgroundImage.Builder() provides several configuration options:

• setImage() - sets the PdfXObject to use as background
• setOpacity() - sets the opacity level (1.0 = fully opaque, 0.0 = fully transparent)
• setArea() - sets the area where the background should be applied

As mentioned in the iText FAQ, this builder pattern gives you fine control over how the background image is applied.

Applying Background to Table

Now you can apply the background image to your table using the setBackgroundImage() method:

val table = Table(floatArrayOf(50f, 50f))
    .setAutoLayout()
    .useAllAvailableWidth()
    .setBackgroundImage(backgroundImage)

According to the tutorialspoint guide, this is the standard way to apply backgrounds to tables in iText7. The background image will be applied to the entire table area.

Complete Kotlin Code Example

Here’s a complete Kotlin example showing how to add a background image to a table:

import com.itextpdf.io.image.ImageData
import com.itextpdf.io.image.ImageDataFactory
import com.itextpdf.kernel.colors.Color
import com.itextpdf.kernel.colors.ColorConstants
import com.itextpdf.kernel.geom.PageSize
import com.itextpdf.kernel.pdf.PdfDocument
import com.itextpdf.kernel.pdf.PdfWriter
import com.itextpdf.kernel.pdf.PdfXObject
import com.itextpdf.layout.Document
import com.itextpdf.layout.element.Cell
import com.itextpdf.layout.element.Paragraph
import com.itextpdf.layout.element.Table
import com.itextpdf.layout.BackgroundImage
import java.io.File
import java.io.FileOutputStream

fun createPdfWithTableBackground() {
    val dest = "table_with_background.pdf"
    val fos = FileOutputStream(dest)
    
    // Create PDF document
    val writer = PdfWriter(fos)
    val pdfDoc = PdfDocument(writer)
    val document = Document(pdfDoc, PageSize.A4)
    
    try {
        // Load image and create PdfXObject
        val imageData = ImageDataFactory.create("background.png")
        val pdfXObject = PdfXObject.createXObject(imageData)
        
        // Create BackgroundImage
        val backgroundImage = BackgroundImage.Builder()
            .setImage(pdfXObject)
            .setOpacity(0.8f) // Semi-transparent
            .build()
        
        // Create table with background
        val table = Table(floatArrayOf(50f, 50f))
            .setAutoLayout()
            .useAllAvailableWidth()
            .setBackgroundImage(backgroundImage)
        
        // Add content to table
        table.addCell(Cell().add(Paragraph("Cell 1 Content")))
        table.addCell(Cell().add(Paragraph("Cell 2 Content")))
        
        // Add table to document
        document.add(table)
        
        // Add more content if needed
        document.add(Paragraph("Table with background image example"))
        
    } finally {
        document.close()
    }
}

This example shows the complete workflow from loading the image to creating the table with background. The iText knowledge base provides additional examples of different background scenarios.

Alternative Approaches

While using BackgroundImage with PdfXObject is the recommended approach for table backgrounds, there are alternative methods you might consider:

1. Cell-Level Background Images

If you want different background images for different cells, you can apply backgrounds to individual cells:

val cell = Cell()
    .add(Paragraph("Content with background"))
    .setBackgroundColor(ColorConstants.LIGHT_GRAY)
    .setBackgroundImage(backgroundImage)

2. Using Patterns for Backgrounds

For more complex backgrounds, you can use patterns as mentioned in the iText documentation:

val pattern = PdfPatternCanvas(pdfXObject, pdfDoc.defaultPageSize)
val patternColor = PatternColor(pattern)
table.setBackgroundColor(patternColor)

3. Direct Canvas Drawing

For maximum control, you can draw directly on the canvas:

val canvas = new PdfCanvas(pdfDoc.getFirstPage().newContentStreamBefore(), pdfDoc.getFirstPage().getResources(), pdfDoc)
canvas.addXObject(pdfXObject, 0f, 0f)

Troubleshooting Common Issues

Image Not Visible

If your background image isn’t visible:

• Ensure the image format is supported (PNG, JPEG, GIF)
• Check that the image dimensions are appropriate for the table size
• Verify that the opacity is set correctly (not 0.0)

Memory Issues

For large images, you might encounter memory issues:

• Consider using image compression
• Scale down the image before creating the PdfXObject
• Use streaming approaches for very large images

Performance Considerations

As noted in various StackOverflow discussions, background images can impact PDF generation performance:

• Use appropriate image sizes
• Consider reusing PdfXObject objects when possible
• Be mindful of the number of background images in complex documents

Conclusion

Adding background images to tables in iText7 requires understanding the relationship between PdfXObject and BackgroundImage. The key steps are:

1. Create PdfXObject from your image using PdfXObject.createXObject()
2. Build BackgroundImage using the builder pattern with your PdfXObject
3. Apply the background to your table using setBackgroundImage()

This approach provides better performance and more control than older iText versions. Remember to choose appropriate image formats and sizes for optimal results, and consider alternative approaches like cell-level backgrounds or patterns for different use cases.

For the most current information and examples, always refer to the official iText documentation and GitHub examples.

Sources

1. iText Knowledge Base - Adding a background to a table
2. iText GitHub Examples - BackgroundImage.java
3. iText FAQ - How to add a background image to a cell
4. iText Knowledge Base - Background images
5. Tutorialspoint - iText - Adding Image to a Table
6. Stack Overflow - How to Apply background image on Table in PDF using iText library