Add(ImGearPDETextFlags,Int32,String,ImGearPDEFont,ImGearPDEGraphicState,ImGearPDETextState,ImGearPDFFixedMatrix) Method

Adds a Unicode character or a Unicode text run to a PDE Text object.

Syntax

Visual Basic
C#
Managed Extensions for C++
C++/CLI

'Declaration
 
Public Overloads Sub Add( _
   ByVal options As ImGearPDETextFlags, _
   ByVal index As Integer, _
   ByVal text As String, _
   ByVal font As ImGearPDEFont, _
   ByVal graphicsState As ImGearPDEGraphicState, _
   ByVal textState As ImGearPDETextState, _
   ByVal textMatrix As ImGearPDFFixedMatrix _
)

'Usage
 
Dim instance As ImGearPDEText
Dim options As ImGearPDETextFlags
Dim index As Integer
Dim text As String
Dim font As ImGearPDEFont
Dim graphicsState As ImGearPDEGraphicState
Dim textState As ImGearPDETextState
Dim textMatrix As ImGearPDFFixedMatrix
 
instance.Add(options, index, text, font, graphicsState, textState, textMatrix)

public void Add( 
   ImGearPDETextFlags options,
   int index,
   string text,
   ImGearPDEFont font,
   ImGearPDEGraphicState graphicsState,
   ImGearPDETextState textState,
   ImGearPDFFixedMatrix textMatrix
)

public: void Add( 
   ImGearPDETextFlags options,
   int index,
   string* text,
   ImGearPDEFont* font,
   ImGearPDEGraphicState* graphicsState,
   ImGearPDETextState* textState,
   ImGearPDFFixedMatrix* textMatrix
)

public:
void Add( 
   ImGearPDETextFlags options,
   int index,
   String^ text,
   ImGearPDEFont^ font,
   ImGearPDEGraphicState^ graphicsState,
   ImGearPDETextState^ textState,
   ImGearPDFFixedMatrix^ textMatrix
)

Parameters

options: ImGearPDETextFlags options that specify what kind of text to add. Must be either:CHAR - for a text character, or RUN - for a text run.
index: Index after which to add character or text run.
text: String with Unicode characters to add.
font: Font for the element. Must be TrueType or Type 0 font.
graphicsState: The graphics state for the element.
textState: The text state for the element.
textMatrix: The coordinates of text are specified in text space. TextMatrix defines the transformation from text space to the user space. See section '5.3.1 Text-Positioning Operators' of the PDF Reference for more details.

Remarks

This method should be used for adding text encoded with Unicode.

The Unicode API methods require a TrueType or Type 0 font that can be embedded. This font must be created from a font file on the local machine, because the lookup tables used by these API only exist in the font files. This is required even if you only check for representable text. This method will raise an exception, if used with other fonts, like Type 1 or font retrieved from an existing PDF document.

Example

private void addUnicodeTextToolStripMenuItem_Click(object sender, EventArgs e)
{
    if (igDocument is ImGearPDFDocument)
    {
        string textToAdd =
            "Russian: Русский Текст. Greek: Κείμενο στην ελληνική γλώσσα. Japanese (unrepresentable): 日本";

        ImGearPDFPage pdfPage = (ImGearPDFPage)igDocument.Pages[0];

        ImGearPDEContent pdfContent = pdfPage.GetContent();

        ImGearPDEFont fontSerif = CreateFont("Times-Roman", "Type0", "Identity-H");
        bool embedSerifFont = false;

        // Ensure that the text is fully representable by the font.
        // Add a warning if not.
        if (!fontSerif.IsTextRepresentable(textToAdd))
        {
            System.Collections.Generic.IEnumerable<char> unrepresentableChars =
                fontSerif.FindUnrepresentableCharacters(textToAdd);

            string unrepresentableCharsString = String.Empty;
            foreach (char unrepresentableChar in unrepresentableChars)
            {
                if (unrepresentableCharsString != String.Empty)
                {
                    unrepresentableCharsString += ",";
                }

                unrepresentableCharsString += unrepresentableChar;
            }

            MessageBox.Show(
                string.Format(
                    "The selected font, {0}, does not support the following characters: [{1}]",
                    fontSerif.GetAttributes().Name.String, unrepresentableCharsString));
        }

        ImGearPDEText text = CreateTextElement(
            textToAdd,
            fontSerif, 
            11, 
            10, 
            30, 
            300);

        if (text != null)
        {
            embedSerifFont = true;
            pdfContent.AddElement((int)ImGearPDEInsertElement.AFTER_LAST, text);
            text.Dispose();
        }

        // Finalize the content
        pdfPage.SetContent();

        // Embed and subset any fonts that were used. This is only
        // required when using Unicode fonts, and only in case if the font was actually used.
        if (embedSerifFont)
        {
            ImGearPDFDocument pdfDocument = igDocument as ImGearPDFDocument;
            fontSerif.CreateToUnicodeNow(pdfDocument);
            fontSerif.CreateWidthsNow(pdfDocument);
            fontSerif.SubsetNow(pdfDocument);
        }
        
        pdfPage.ReleaseContent();

        // Clean up editing objects
        if (fontSerif != null)
        {
            fontSerif.Dispose();
        }

        if (pdfContent != null)
        {
            pdfContent.Dispose();
        }

        pdfPage.ResetDisplayCache();

        this.imGearPageView1.Update();
    }
}

static ImGearPDEFont CreateFont(string FontName, string FontType, string sysEncodingName)
{
    ImGearPDEFontAttrs findAttrs = new ImGearPDEFontAttrs();
    findAttrs.Name = new ImGearPDFAtom(FontName);
    findAttrs.Type = new ImGearPDFAtom(FontType);
    ImGearPDFSysFont sysFont = ImGearPDFSysFont.FindSysFont(findAttrs, 0);

    ImGearPDFSysEncoding encoding = new ImGearPDFSysEncoding(new ImGearPDFAtom(sysEncodingName));

    ImGearPDEFont font = new ImGearPDEFont(
        sysFont, 
        encoding, 
        findAttrs.Name,
        ImGearPDEFontCreateFlags.CREATE_EMBEDDED | ImGearPDEFontCreateFlags.WILL_SUBSET | ImGearPDEFontCreateFlags.CREATE_TO_UNICODE | ImGearPDEFontCreateFlags.ENCODE_BY_GID);

    return font;
}

static ImGearPDEText CreateTextElement(
    string Text, 
    ImGearPDEFont Font,
    Int32 FontSize, 
    int x, 
    int y, 
    int w)
{
    ImGearPDEText textElement = null;

    ImGearPDEColorSpace colorSpace =
        new ImGearPDEColorSpace(new ImGearPDFAtom("DeviceGray"));

    ImGearPDEGraphicState gState = new ImGearPDEGraphicState();
    gState.StrokeColorSpec.Space = colorSpace;
    gState.FillColorSpec.Space = colorSpace;
    gState.MiterLimit = (int)ImGearPDFFixedValues.TEN;
    gState.Flatness = (int)ImGearPDFFixedValues.ONE;
    gState.LineWidth = (int)ImGearPDFFixedValues.ONE;

    ImGearPDFFixedMatrix textMatrix = new ImGearPDFFixedMatrix();
    textMatrix.A = ImGearPDF.IntToFixed(FontSize);
    textMatrix.D = ImGearPDF.IntToFixed(FontSize);
    textMatrix.H = ImGearPDF.IntToFixed(x);
    textMatrix.V = ImGearPDF.IntToFixed(y);

    textElement = new ImGearPDEText();

    textElement.Add(
        ImGearPDETextFlags.RUN, 
        0,
        Text, 
        Font, 
        gState, 
        null, 
        textMatrix);

    colorSpace.Dispose();
    gState.Dispose();

    return textElement;
}

Visual Basic

Private Sub AddUnicodeTextToolStripMenuItem_Click(ByVal sender As System.Object, ByVal e As System.EventArgs) Handles AddUnicodeTextToolStripMenuItem.Click
    If TypeOf igDoc Is ImGearPDFDocument Then

        Dim textToAdd As String = "Russian: Русский Текст. Greek: Κείμενο στην ελληνική γλώσσα. Japanese (unrepresentable): 日本"

        Dim pdfPage As ImGearPDFPage = DirectCast(igDoc.Pages(0), ImGearPDFPage)

        Dim pdfContent As ImGearPDEContent = pdfPage.GetContent()

        Dim fontSerif As ImGearPDEFont = CreateFont("Times-Roman", "Type0", "Identity-H")
        Dim embedSerifFont As Boolean = False

        ' Ensure that the text is fully representable by the font.
        ' Add a warning if not.
        If Not fontSerif.IsTextRepresentable(textToAdd) Then
            Dim unrepresentableChars As System.Collections.Generic.IEnumerable(Of Char) = fontSerif.FindUnrepresentableCharacters(textToAdd)

            Dim unrepresentableCharsString As String = [String].Empty
            For Each unrepresentableChar As Char In unrepresentableChars
                If unrepresentableCharsString <> [String].Empty Then
                    unrepresentableCharsString += ","
                End If

                unrepresentableCharsString += unrepresentableChar
            Next

            MessageBox.Show(String.Format("The selected font, {0}, does not support the following characters: [{1}]", fontSerif.GetAttributes().Name.[String], unrepresentableCharsString))
        End If

        embedSerifFont = True

        Dim text As ImGearPDEText = CreateTextElement(textToAdd, fontSerif, 11, 10, 30, 300)

        If text IsNot Nothing Then
            pdfContent.AddElement(CInt(ImGearPDEInsertElement.AFTER_LAST), text)
            text.Dispose()
        End If

        ' Finalize the content
        pdfPage.SetContent()

        ' Embed and subset any fonts that were used. This is only
        ' required when using Unicode fonts, and only in case if the font was actually used.
        If embedSerifFont Then
            Dim pdfDocument As ImGearPDFDocument = TryCast(igDoc, ImGearPDFDocument)
            fontSerif.CreateToUnicodeNow(pdfDocument)
            fontSerif.CreateWidthsNow(pdfDocument)
            fontSerif.SubsetNow(pdfDocument)
        End If

        pdfPage.ReleaseContent()

        ' Clean up editing objects
        If fontSerif IsNot Nothing Then
            fontSerif.Dispose()
        End If

        If pdfContent IsNot Nothing Then
            pdfContent.Dispose()
        End If

        pdfPage.ResetDisplayCache()

        Me.ImGearPageView1.Update()
    End If
End Sub

Private Shared Function CreateFont(ByVal FontName As String, ByVal FontType As String, ByVal sysEncodingName As String) As ImGearPDEFont
    Dim findAttrs As New ImGearPDEFontAttrs()
    findAttrs.Name = New ImGearPDFAtom(FontName)
    findAttrs.Type = New ImGearPDFAtom(FontType)
    Dim sysFont As ImGearPDFSysFont = ImGearPDFSysFont.FindSysFont(findAttrs, 0)

    Dim encoding As New ImGearPDFSysEncoding(New ImGearPDFAtom(sysEncodingName))

    Dim font As New ImGearPDEFont(sysFont, encoding, findAttrs.Name, ImGearPDEFontCreateFlags.CREATE_EMBEDDED Or ImGearPDEFontCreateFlags.WILL_SUBSET Or ImGearPDEFontCreateFlags.CREATE_TO_UNICODE Or ImGearPDEFontCreateFlags.ENCODE_BY_GID)

    Return font
End Function

Private Shared Function CreateTextElement(ByVal Text As String, ByVal Font As ImGearPDEFont, ByVal FontSize As Int32, ByVal x As Integer, ByVal y As Integer, ByVal w As Integer) As ImGearPDEText
    Dim textElement As ImGearPDEText = Nothing

    Dim colorSpace As New ImGearPDEColorSpace(New ImGearPDFAtom("DeviceGray"))

    Dim gState As New ImGearPDEGraphicState()
    gState.StrokeColorSpec.Space = colorSpace
    gState.FillColorSpec.Space = colorSpace
    gState.MiterLimit = CInt(ImGearPDFFixedValues.TEN)
    gState.Flatness = CInt(ImGearPDFFixedValues.ONE)
    gState.LineWidth = CInt(ImGearPDFFixedValues.ONE)

    Dim textMatrix As New ImGearPDFFixedMatrix()
    textMatrix.A = ImGearPDF.IntToFixed(FontSize)
    textMatrix.D = ImGearPDF.IntToFixed(FontSize)
    textMatrix.H = ImGearPDF.IntToFixed(x)
    textMatrix.V = ImGearPDF.IntToFixed(y)

    textElement = New ImGearPDEText()

    textElement.Add(ImGearPDETextFlags.RUN, 0, Text, Font, gState, Nothing, _
     textMatrix)

    colorSpace.Dispose()
    gState.Dispose()

    Return textElement
End Function

Reference

ImGearPDEText Class
ImGearPDEText Members
Overload List
ImGearPDETextFlags Enumeration
ImGearPDEFont Class
ImGearPDEGraphicState Class
ImGearPDETextState Class
ImGearPDFFixedMatrix Class