Advanced text flow effects in PDF documents using floating elements

Introduction

Floating elements in CSS can be defined using CSS float property which can have the following values: none, left, right, initial, inherit. Such elements should be docked to one of the page sides pushing other elements to the opposite side. The element that follows floating element can either respect the “floating” nature of the preceding element or ignore it using the clear property. This property can have values: none, left, right, both, initial, inherit – which indicate the side where floating elements should be ignored and new line created.

Flow layout API provided by Apitron PDF Kit implements similar approach to floating elements, and provides you with an ability to define floating blocks in the same way CSS does. Such elements can be used to create text flow effects e.g. it can flow around the image, other text elements and so on. The visual example is provided in the next section of the article.

Floating image and text sample

Consider the following code that creates three sections with floating image elements docked to different sides of the section. The last section has two images docked to both sides, and its text flows in-between. All sections use the same content and describe the well-known flower called Viola Tricolor.

The code:

public void CreateFloatingImageWithText()

{

    // prepare info blocks

    string paragraph1 = "Viola tricolor, known as heartsease, heart's ease, heart's delight, tickle-my-fancy, Jack-jump-up-and-kiss-me, come-and-cuddle-me, three faces in a hood, or love-in-idleness, is a common European wild flower, growing as an annual or short-lived perennial. It has been introduced into North America, where it has spread widely, and is known as the johnny jump up (though this name is also applied to similar species such as the yellow pansy). It is the progenitor of the cultivated pansy, and is therefore sometimes called wild pansy; before the cultivated pansies were developed, \"pansy\" was an alternative name for the wild form.";

    string paragraph2 = "Viola tricolor is a small plant of creeping and ramping habit, reaching at most 15 cm in height, with flowers about 1.5 cm in diameter. It grows in short grassland on farms and wasteland, chiefly on acid or neutral soils. It is usually found in partial shade. It flowers from April to September (in the northern hemisphere). The flowers can be purple, blue, yellow or white. They are hermaphrodite and self-fertile, pollinated by bees.";

    

    // prepare resources

    ResourceManager resourceManager = new ResourceManager();

    resourceManager.RegisterResource(new Apitron.PDF.Kit.FixedLayout.Resources.XObjects.Image("viola","viola.jpg"));

    // create and fill document

    FlowDocument doc = new FlowDocument(){Margin = new Thickness(5,5,5,5)};

    // register style for image floating to the left

    doc.StyleManager.RegisterStyle("image.thumbnail_left",

        new Style()

        {

           Float = Float.Left,

           Width = 160, 

           Height = 160, 

           Margin = new Thickness(0,0,10,5)

        });

    // register style for image floating to the right

    doc.StyleManager.RegisterStyle("image.thumbnail_right", 

        new Style()

        {

           Float = Float.Right,

           Width = 160,

           Height = 160,

           Margin = new Thickness(10,0,0,5)

        });

    // register style for content section

    doc.StyleManager.RegisterStyle("section", 

        new Style()

        {

           Align = Align.Justify,

           Border = new Border(1), 

           BorderColor = RgbColors.Black, 

           Margin = new Thickness(0,5,0,5),

           Padding = new Thickness(5,5,5,5)

        });   

    // register style for first level text blocks used as captions

    doc.StyleManager.RegisterStyle("flowdocument > textblock", 

        new Style(){Color = RgbColors.Red});

   

    // add first section

    doc.Add(new TextBlock("Image with Float=left"));

    Section description1 = new Section();

    description1.Add(new Apitron.PDF.Kit.FlowLayout.Content.Image("viola")

        {Class = "thumbnail_left"});       

    description1.Add(new TextBlock(paragraph1));

    description1.Add(new Br());

    description1.Add(new TextBlock(paragraph2));

    doc.Add(description1);

    // add second section

    doc.Add(new TextBlock("Image with Float=right"));

    Section description2 = new Section();

    description2.Add(new Apitron.PDF.Kit.FlowLayout.Content.Image("viola")

        {Class="thumbnail_right" });

    description2.Add(new TextBlock(paragraph1));

    description2.Add(new Br());

    description2.Add(new TextBlock(paragraph2));

    doc.Add(description2);

   

    // add third section

    doc.Add(new TextBlock("Images with Float=left and Float=Right"));

    Section description3 = new Section();

    description3.Add(new Apitron.PDF.Kit.FlowLayout.Content.Image("viola")

        {Class = "thumbnail_left"});

    description3.Add(new Apitron.PDF.Kit.FlowLayout.Content.Image("viola")

        {Class="thumbnail_right" });

    description3.Add(new TextBlock(paragraph1));

    description3.Add(new Br());

    description3.Add(new TextBlock(paragraph2));

    doc.Add(description3);

    // save document

    using (Stream stream = File.Create("floating_elements.pdf"))

    {

        doc.Write(stream,resourceManager);

    }

}

Each image becomes styled via appropriate style defined using class selector. Section objects are being styled using type selector, and texblocks using child elements selector.

The resulting image produced by this code sample is shown below:

Pic. 1 Floating image and text

Ignoring the floats: Clear

What if we need to ignore the floating element? Clear setting lets the layout engine know that element should ignore the preceding floating elements and continue from the new line.

If we used this setting for the first section of our document, it would like that:

    ...

    // set the clear value for this text block

    description1.Add(new TextBlock(paragraph2){Clear = Clear.Left});

    ...

And the resulting image:

Pic. 2 Usage of clear setting, second paragraph uses clear = left

Conclusion

In this post we described how to use floating elements for achieving advanced text effects with the help of Flow layout API provided by our PDF library. Read more about Apitron PDF Kit for .NET pdf component on its product page. Try it and let us know what you think. We regularly post new samples and articles in our blog and welcome any feedback from you.

Downloadable version of this article can be found by the following link [PDF].