Summary
FormField checkboxes (Type 71 = FIELD_FORM_CHECK_BOX) inserted into OfficeMath equations fail to render correctly when converting Word documents to PDF. Instead of rendering as actual checkbox symbols, the literal field code text " FORMCHECKBOX " appears in the PDF output.
Product Information
- Product: Aspose.Words for Java
- Version: 26.4
- License: Aspose.Total for Java (Site OEM, valid through January 2027)
- Environment: Java 17, Windows 10 or Linux
Problem Description
Expected Behavior
When a Word document contains FormField checkboxes inside OfficeMath equation objects, the checkboxes should render as visible checkbox symbols (☐) in the generated PDF, matching how they appear in Microsoft Word.
Actual Behavior
The FormField checkbox codes are NOT evaluated during PDF conversion. Instead, the literal placeholder text " FORMCHECKBOX " appears in the equation where checkboxes should be (in Word) and the PDF shows nothing where the checkbox should be.
Visual Comparison
In Microsoft Word: Equations display with visible checkbox symbols
In Aspose PDF Output: Equations show the text " FORMCHECKBOX " instead of symbols
Root Cause Analysis
Through extensive debugging, we discovered:
- FormField checkboxes exist in the document’s FormField collection (Type 71)
- Inside OfficeMath nodes, Aspose represents these checkboxes as text runs containing
" FORMCHECKBOX " - Field evaluation fails inside OfficeMath nodes - the field code is never evaluated to render the checkbox
Document Structure Analysis
FormField Collection: 12 checkboxes (Type 71 = FIELD_FORM_CHECK_BOX)
OfficeMath #1:
Text: "VBpreµl=50*0.01OD.Bp*1000=50*0.01 FORMCHECKBOX . FORMCHECKBOX FORMCHECKBOX *1000=..."
Runs inside equation: 20
Run #10: Text=' FORMCHECKBOX ' Font='Cambria Math'
Run #12: Text=' FORMCHECKBOX ' Font='Cambria Math'
Run #13: Text=' FORMCHECKBOX ' Font='Cambria Math'
Steps to Reproduce
Test Files
We have prepared two test documents:
-
equationBoxes.docx - Contains 26 equations with FormField checkboxes that don’t render
equationBoxes.docx (14.2 KB) -
equationBoxes2.docx - Mixed document showing:
- FormField checkboxes in equations (broken)
- Unicode checkbox characters in equations (working - render correctly as ☐)
equationBoxes2.docx (16.7 KB)
Minimal Reproduction Code
import com.aspose.words.Document;
import com.aspose.words.LoadOptions;
import com.aspose.words.PdfSaveOptions;
import java.nio.file.Path;
public class CheckboxInEquationTest {
public static void main(String[] args) throws Exception {
// Load document with FormField checkboxes inside equations
Path inputFile = Path.of("equationBoxes.docx");
Document doc = new Document(inputFile.toString());
// Save to PDF
PdfSaveOptions saveOptions = new PdfSaveOptions();
doc.save("output.pdf", saveOptions);
// RESULT: PDF shows " FORMCHECKBOX " text instead of checkbox symbols
}
}
Analysis Code
To verify the issue, we analyzed the document structure:
import com.aspose.words.*;
public class AnalyzeCheckboxStructure {
public static void main(String[] args) throws Exception {
Document doc = new Document("equationBoxes.docx");
// Check FormField collection
FormFieldCollection formFields = doc.getRange().getFormFields();
System.out.println("FormField checkboxes found: " + formFields.getCount());
for (FormField ff : formFields) {
if (ff.getType() == FieldType.FIELD_FORM_CHECK_BOX) {
System.out.println("Checkbox: " + ff.getName());
}
}
// Check OfficeMath nodes
NodeCollection officeMathNodes = doc.getChildNodes(NodeType.OFFICE_MATH, true);
System.out.println("OfficeMath nodes found: " + officeMathNodes.getCount());
for (int i = 0; i < officeMathNodes.getCount(); i++) {
OfficeMath math = (OfficeMath) officeMathNodes.get(i);
NodeCollection runs = math.getChildNodes(NodeType.RUN, true);
for (int j = 0; j < runs.getCount(); j++) {
Run run = (Run) runs.get(j);
if (run.getText().contains(" FORMCHECKBOX ")) {
System.out.println("Found FormCheckbox placeholder in equation:");
System.out.println(" Text: '" + run.getText() + "'");
System.out.println(" Font: " + run.getFont().getName());
}
}
}
// OUTPUT:
// FormField checkboxes found: 12
// OfficeMath nodes found: 26
// Found FormCheckbox placeholder in equation (36 occurrences)
}
}
Attempted Workaround
We attempted to work around this issue by replacing the " FORMCHECKBOX " text with Unicode checkbox characters:
private int fixCheckboxesInEquations(Document doc) {
int fixedCount = 0;
NodeCollection officeMathNodes = doc.getChildNodes(NodeType.OFFICE_MATH, true);
for (int i = 0; i < officeMathNodes.getCount(); i++) {
OfficeMath math = (OfficeMath) officeMathNodes.get(i);
NodeCollection runs = math.getChildNodes(NodeType.RUN, true);
for (int j = 0; j < runs.getCount(); j++) {
Run run = (Run) runs.get(j);
String text = run.getText();
if (text != null && text.contains(" FORMCHECKBOX ")) {
// Replace with Unicode checkbox character
String newText = text.replace(" FORMCHECKBOX ", "\u2610");
run.setText(newText);
// Change font to MS Gothic for proper glyph rendering
run.getFont().setName("MS Gothic");
fixedCount++;
}
}
}
return fixedCount;
}
Result: This workaround successfully removes the " FORMCHECKBOX " text, but the Unicode checkbox characters still don’t render correctly in the PDF output, even with font changes to MS Gothic, Arial Unicode MS, or Segoe UI Symbol.
Key Observations
- Field evaluation is the issue: FormField codes inside OfficeMath nodes are never evaluated during
doc.updateFields()ordoc.save() - Unicode checkboxes also fail: Even manual Unicode replacement doesn’t render properly, suggesting a deeper font/rendering issue inside equations
- Outside equations work fine: The same FormField checkboxes render correctly when placed outside of OfficeMath nodes
- Inconsistent behavior: In our test document, ONE manually-inserted Unicode checkbox (U+2610 with MS Gothic font) renders correctly, but our programmatic replacements do not
Impact
This issue affects:
- Scientific documents with equations containing checkboxes
- Quality control forms with mathematical formulas
- Technical specifications where users insert checkboxes into equations for data entry
Requested Fix
We request that Aspose.Words properly evaluate FormField codes inside OfficeMath nodes during PDF conversion, so that:
- FormField checkboxes render as actual checkbox symbols (not placeholder text)
- The rendering matches Microsoft Word’s display behavior
- Field codes inside equations are evaluated during
doc.updateFields()anddoc.save()
Alternatively, if there’s a recommended approach or API method we’re missing, please advise.
Attachments
We will attach:
- equationBoxes.docx - Sample document showing the issue
- equationBoxes2.docx - Document showing working vs. broken checkboxes
- equationBoxes.docx.pdf - Current broken PDF output (no checkboxes in equations are rendered)
Additional Information
- This issue occurs consistently across multiple documents
- The issue persists with both Aspose.Words 25.x and 26.4
- We’re using Aspose.Words for Java with a valid Aspose.Total Site OEM license
- No exceptions are thrown - the conversion “succeeds” but produces incorrect output
Contact Information
Priority: High - Affects customer documents with equations
Note: We’ve spent considerable time investigating this issue and are confident it’s an Aspose.Words rendering bug specific to FormField evaluation inside OfficeMath nodes. We’re happy to provide additional test cases or debugging information as needed.