com.itextpdf.kernel.contrast

Class ColorContrastChecker

java.lang.Object

com.itextpdf.kernel.contrast.ColorContrastChecker

All Implemented Interfaces:

IValidationChecker

public class ColorContrastChecker
extends Object
implements IValidationChecker

A validation checker that analyzes color contrast in PDF documents to ensure compliance with Web Content Accessibility Guidelines (WCAG) standards.

This checker validates the contrast ratio between text and background colors to ensure readability for users with visual impairments. It supports both WCAG 2.0 Level AA and Level AAA conformance levels.

Features: @see ContrastAnalyzer for details.

Current Limitations @see ContrastAnalyzer for details.

Constructor Summary

Constructors

Constructor and Description
ColorContrastChecker(boolean checkIndividualGlyphs, boolean throwExceptionOnFailure) Creates a new ColorContrastChecker with the specified configuration.

Method Summary

Modifier and Type	Method and Description
boolean	isPdfObjectReadyToFlush(PdfObject object) Determines if a PDF object is ready to be flushed to the output stream.
ColorContrastChecker	setCheckWcagAA(boolean checkWcagAA) Sets whether to check for WCAG AA compliance.
ColorContrastChecker	setCheckWcagAAA(boolean checkWcagAAA) Sets whether to check for WCAG AAA compliance.
void	setMinimalPercentualCoverage(double minimalPercentualCoverage) Sets the minimal percentual coverage of text area that must be covered by a background element for its contrast ratio to be considered in the analysis.
void	validate(IValidationContext validationContext) Validates the given context for color contrast compliance.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ColorContrastChecker

public ColorContrastChecker(boolean checkIndividualGlyphs,
                            boolean throwExceptionOnFailure)

Creates a new ColorContrastChecker with the specified configuration.

Parameters:

checkIndividualGlyphs - if true, contrast is checked at the individual glyph level; if false, contrast is checked at the text block level. Individual glyph checking is more precise but may impact performance.

throwExceptionOnFailure - if true, a PdfException is thrown when contrast requirements are not met; if false, warnings are logged instead.

Method Detail

setMinimalPercentualCoverage

public final void setMinimalPercentualCoverage(double minimalPercentualCoverage)

Sets the minimal percentual coverage of text area that must be covered by a background element for its contrast ratio to be considered in the analysis.

For example, if set to 0.1 (10%), only background elements that cover at least 10% of the text area will be included in the contrast analysis. This helps filter out insignificant backgrounds that do not meaningfully affect text readability. Like underlines or small decorative elements.

Parameters:

minimalPercentualCoverage - the minimal percentual coverage (between 0.0 and 1.0)

setCheckWcagAA

public final ColorContrastChecker setCheckWcagAA(boolean checkWcagAA)

Sets whether to check for WCAG AA compliance. WCAG AA requires a contrast ratio of at least 4.5:1 for normal text and 3:1 for large text (18pt+ or 14pt+ bold).

Parameters:

checkWcagAA - true to enable WCAG AA compliance checking, false to disable

Returns:

this ColorContrastChecker instance for method chaining

setCheckWcagAAA

public final ColorContrastChecker setCheckWcagAAA(boolean checkWcagAAA)

Sets whether to check for WCAG AAA compliance. WCAG AAA requires a contrast ratio of at least 7:1 for normal text and 4.5:1 for large text (18pt+ or 14pt+ bold).

Parameters:

checkWcagAAA - true to enable WCAG AAA compliance checking, false to disable

Returns:

this ColorContrastChecker instance for method chaining

validate

public void validate(IValidationContext validationContext)

Validates the given context for color contrast compliance.

This method is called by the validation framework to check color contrast when a PDF page is being validated. It only processes validation contexts of type ValidationType.PDF_PAGE.

Specified by:

validate in interface IValidationChecker

Parameters:

validationContext - the validation context containing the PDF page to validate

isPdfObjectReadyToFlush

public boolean isPdfObjectReadyToFlush(PdfObject object)

Determines if a PDF object is ready to be flushed to the output stream.

This implementation always returns true as color contrast checking does not impose any restrictions on when objects can be flushed.

Specified by:

isPdfObjectReadyToFlush in interface IValidationChecker

Parameters:

object - the PDF object to check

Returns:

always true