iText FAQ's - Measurements

The iText FAQ's contain a simple but useful entry on measurements. The FAQ's explain the default measurement system roughly corresponds to a typographic or PostScript point. This means if you want to create a rectangle, custom page size, etcetera, you must first convert your measurement units (inches, centimeters, millimeters, etcetera) into points. It is a simple concept, but important if you wish to do any sort of positioning or sizing with iText.

Converting measurement units into points is a common task. So you may wish to create a utility component that contains the common conversion functions like: converting inches to points, centimeters to points, etcetera. You can find the basis for such a utility component below (see MeasurementUtil.cfc).

Now onto a few examples that demonstrate the iText measurement system. The first is a direct translation from the iText tutorial. The second example is similar but it uses one of the U.S. standards PageSize.LETTER.

Documentation: Frequently Asked Questions
Source: Measurements.java

Measurements Example

<h1>Measurements Example</h1>

<cfscript>
    savedErrorMessage = "";

    fullPathToOutputFile = ExpandPath("./Measurements.pdf");

    // step 1: creation of a document-object
    pageSize = createObject("java", "com.lowagie.text.Rectangle").init(javacast("float", 288), javacast("float", 720));
    document = createObject("java", "com.lowagie.text.Document").init( pageSize,
            javacast("float", 36),
            javacast("float", 18),
            javacast("float", 72),
            javacast("float", 72) );
    
    try {
        // step 2:
        // we create a writer that listens to the document and directs a PDF-stream to a file
        outStream = createObject("java", "java.io.FileOutputStream").init(fullPathToOutputFile);
        writer = createObject("java", "com.lowagie.text.pdf.PdfWriter").getInstance(document, outStream);

        // step 3: we open the document
        document.open();

        // step 4:
        //cfSearching: create a single paragraph object and reuse it
        paragraph = createObject("java", "com.lowagie.text.Paragraph");
        
        document.add(paragraph.init("The size of this page is 288x720 points."));
        document.add(paragraph.init("288pt / 72 points per inch = 4 inch"));
        document.add(paragraph.init("720pt / 72 points per inch = 10 inch"));
        document.add(paragraph.init("The size of this page is 4x10 inch."));
        document.add(paragraph.init("4 inch x 2.54 = 10.16 cm"));
        document.add(paragraph.init("10 inch x 2.54 = 25.4 cm"));
        document.add(paragraph.init("The size of this page is 10.16x25.4 cm."));
        document.add(paragraph.init("The left border is 36pt or 0.5 inch or 1.27 cm"));
        document.add(paragraph.init("The right border is 18pt or 0.25 inch or 0.63 cm."));
        document.add(paragraph.init("The top and bottom border are 72pt or 1 inch or 2.54 cm."));
        
        //cfSearching: 
        WriteOutput("Finished!");
    }
    catch (com.lowagie.text.DocumentException de) {
        savedErrorMessage = de;
    } 
    catch (java.io.IOException ioe) {
        savedErrorMessage = ioe;
    }

    // step 5: we close the document
    document.close();
</cfscript>


<!--- show any errors --->
<cfif len(savedErrorMessage) gt 0>
    Error - unable to create document
    <cfdump var="#savedErrorMessage#">
</cfif>

Measurements LETTER Page Size Example

<h1>Measurements PageSize.LETTER Example</h1>
** Note, centimeter values are rounded<br><br>

<cfscript>
    savedErrorMessage = "";

    fullPathToOutputFile = ExpandPath("./MeasurementsLetterSize.pdf");
    
    // cfSearching: margins in points. using 1/2 inch margin on left-right, 1 inch margin on top-bottom
    util = createObject("component", "MeasurementUtil");
    marginLeft = util.inchesToPoints(0.5);
    marginRight = util.inchesToPoints(0.5);
    marginTop = util.inchesToPoints(1);
    marginBottom = util.inchesToPoints(1);

    // cfSearching: create document using pre-defined LETTER size (8.5 x 11 inches)
    PageSize = createObject("java", "com.lowagie.text.PageSize");
    document = createObject("java", "com.lowagie.text.Document").init( PageSize.LETTER,
            marginLeft, marginRight, marginTop, marginBottom );
    
    try {
        // step 2:
        // we create a writer that listens to the document and directs a PDF-stream to a file
        outStream = createObject("java", "java.io.FileOutputStream").init(fullPathToOutputFile);
        writer = createObject("java", "com.lowagie.text.pdf.PdfWriter").getInstance(document, outStream);

        // step 3: we open the document
        document.open();

        // step 4:
        // cfSearching: highlight the document content area 
        directContent = writer.getDirectContent();

        color = createObject("java", "java.awt.Color");    
        yellow = color.init( javacast("int", 255), javacast("int", 255), javacast("int", 0) );
        
        directContent.setColorFill(yellow);
        directContent.rectangle( util.inchesToPoints(0.5), 
                                 util.inchesToPoints(1), 
                                 util.inchesToPoints(7.5), 
                                 util.inchesToPoints(9));
        directContent.fill();

        // step 5:

        PdfContentByte = createObject("java", "com.lowagie.text.pdf.PdfContentByte");        
        BaseFont = createObject("java", "com.lowagie.text.pdf.BaseFont");
        textColor = color.init(javacast("int", 0), javacast("int", 0), javacast("int", 0));
        textFont = createObject("java", "com.lowagie.text.FontFactory").getFont(BaseFont.HELVETICA,
                BaseFont.WINANSI, BaseFont.NOT_EMBEDDED).getBaseFont();
        
        directContent.beginText();
        directContent.setFontAndSize(textFont, javacast("float", 14) );
        directContent.setColorFill(textColor);

        // cfSearching: show top and bottom margins
        inBottom = util.pointsToInches(marginBottom);
        cmBottom = decimalFormat(util.pointsToCM(marginBottom));
        directContent.moveText(  util.inchesToPoints(1.5), util.inchesToPoints(0.5));
        directContent.showText( "Top and bottom margins are #marginBottom# pt -> #inBottom#  in -> #cmBottom# cm ");

        // cfSearching: show left and right margins
        inLeft = util.pointsToInches(marginLeft);
        cmLeft = decimalFormat(util.pointsToCM(marginLeft));
        directContent.moveText( -util.inchesToPoints(1.5) + 15, util.inchesToPoints(5));
        directContent.showText( "Left and right margins are "& marginLeft &" pt -> #inLeft# in -> #cmLeft# cm");

        inWidth = 8.5;
        inHeight = 11;
        ptWidth = util.inchesToPoints(inWidth);
        ptHeight = util.inchesToPoints(inHeight);
        cmWidth = decimalFormat(util.pointsToCM(ptWidth));
        cmHeight = decimalFormat(util.pointsToCM(ptHeight));
        directContent.moveText(  util.inchesToPoints(0.25), util.inchesToPoints(5));
        directContent.showText( "The size of this page is #ptWidth#x#ptHeight# points ->"
                &" #inWidth#x#inHeight# inches -> #cmWidth#x#cmHeight# centimeters ");

        directContent.endText();

        WriteOutput("Finished!");
    }
    catch (com.lowagie.text.DocumentException de) {
        savedErrorMessage = de;
    } 
    catch (java.io.IOException ioe) {
        savedErrorMessage = ioe;
    }

    // step 5: we close the document
    document.close();
</cfscript>


<!--- show any errors --->
<cfif len(savedErrorMessage) gt 0>
    Error - unable to create document
    <cfdump var="#savedErrorMessage#">
</cfif>

MeasurementUtil.cfc

<cfcomponent>
    <cffunction name="inchesToPoints" returntype="numeric" access="public" output="false" 
        hint="Converts inches to PostScript points">

        <cfargument name="inches" type="numeric" required="true">
        <cfreturn     javacast("float", arguments.inches) * javacast("float", 72)>
    </cffunction>

    <cffunction name="pointsToInches" returntype="numeric" access="public" output="false" 
        hint="Converts PostScript points to inches">

        <cfargument name="points" type="numeric" required="true">
        <cfreturn     javacast("float", arguments.points) / javacast("float", 72)>
    </cffunction>

    <cffunction name="inchesToCM" returntype="numeric" access="public" output="false" 
        hint="Converts inches to centimeters" >
        
        <cfargument name="inches" type="numeric" required="true">
        <cfreturn     javacast("float", arguments.inches) * javacast("float", 2.54)>
    </cffunction>

    <!---
        Function pointsToCM based on http://itext.ugent.be/wiki/examples/src/com/lowagie/util/Measurements.java
    --->
    <cffunction name="pointsToCM" returntype="numeric" access="public" output="false" 
        hint="Converts PostScript points to centimeters.">

        <cfargument name="points" type="numeric" required="true">
        <cfreturn     (javacast("float", arguments.points) * javacast("float", 2.54)) / javacast("float", 72)>
    </cffunction>
    
    <!---
        Source http://itext.ugent.be/wiki/examples/src/com/lowagie/util/Measurements.java
    --->
    <cffunction name="mmToPoints" returntype="numeric" access="public" output="false" 
        hint="Converts millimeters to PostScript points">

        <cfargument name="millimeters" type="numeric" required="true">
        <cfreturn     (javacast("float", arguments.millimeters) * javacast("float", 7.2)) / javacast("float", 2.54)>
    </cffunction>

    <!---
        Function cmToPoints based on http://itext.ugent.be/wiki/examples/src/com/lowagie/util/Measurements.java
    --->
    <cffunction name="cmToPoints" returntype="numeric" access="public" output="false" 
        hint="Converts centimeters to PostScript points">

        <cfargument name="centimeters" type="numeric" required="true">
        <cfreturn     (javacast("float", arguments.centimeters) * javacast("float", 72)) / javacast("float", 2.54)>
    </cffunction>
</cfcomponent>