Block
The Block class is intended to arrange the elements added to it in a flow-like manner. It can be used for measuring, drawing, and splitting of FixedContentElements.
Add and Modify Content
The most common usage of Block is to draw flowing content. Similarly to FixedContentEditor, a block can contain images, graphics or text. The same Block instance can only be drawn once.
Inserting Text
Inserting TextFragments is achieved with one of the overloads of the Insert() method. Example 1 shows all the overloads which allow specifying the styles and font family.
Example 1: Insert text
Block block = new Block();
block.InsertText("Text");
// .NET Framework
block.InsertText(new System.Windows.Media.FontFamily("Arial"), "Text");
block.InsertText(new System.Windows.Media.FontFamily("Arial"), System.Windows.FontStyles.Italic, System.Windows.FontWeights.Bold, "Text");
// .NET Standard
//block.InsertText(new Telerik.Documents.Core.Fonts.FontFamily("Arial"), "Text");
//block.InsertText(new Telerik.Documents.Core.Fonts.FontFamily("Arial"), Telerik.Documents.Core.Fonts.FontStyles.Italic, Telerik.Documents.Core.Fonts.FontWeights.Bold, "Text");
The '\r' and '\n' characters don't have the usual meaning of "go to next line" when they are inserted into a PDF document and you cannot simply insert text containing these characters to produce multiline text. Instead, you should insert a line break.
Inserting Line Break
Inserting a line break results in the next element starting on a new line. The action is achieved with the InsertLineBreak() method as shown in Example 2.
Example 2: Break the line
block.InsertLineBreak();
Inserting Image
Block provides the following methods for inserting images:
- block.InsertImage(imageSource);
- block.InsertImage(stream);
- block.InsertImage(imageSource, size);
- block.InsertImage(stream, size);
- block.InsertImage(imageSource, width, height);
- block.InsertImage(stream, width, height);
Example 3: Inserting an image
string imageFilePath = "sample.jpg";
FileStream fileStream = new FileStream(imageFilePath, FileMode.Open);
Telerik.Windows.Documents.Fixed.Model.Resources.ImageSource imageSrc = new Telerik.Windows.Documents.Fixed.Model.Resources.ImageSource(fileStream);
block.InsertImage(imageSrc, 300, 200);
Inserting Geometries
Geometries allow you to describe 2D shapes in a document. The following methods can be used to insert different geometries.
- block.InsertCircle(center, radius);
- block.InsertEllipse(center, radiusX, radiusY);
- block.InsertLine(point1, point2);
- block.InsertPath(geometry);
- block.InsertRectangle(rectangle);
Example 4: Inserting a geometry
Telerik.Windows.Documents.Fixed.Model.Graphics.RectangleGeometry rectangleGeometry = new Telerik.Windows.Documents.Fixed.Model.Graphics.RectangleGeometry();
// .NET Framework
rectangleGeometry.Rect = new System.Windows.Rect(10, 10, 400, 300);
block.InsertRectangle(new System.Windows.Rect(10, 10, 200, 150));
// .NET Standard
//rectangleGeometry.Rect = new Telerik.Documents.Primitives.Rect(10, 5, 400, 300);
//block.InsertRectangle(new Telerik.Documents.Primitives.Rect(20, 30, 200, 150));
block.InsertPath(rectangleGeometry);
Inserting Form-XObject Elements
The Form (or also known as Form-XObject) is an object that can contain PDF content and can be sheared among the document. The Block class exposes the InsertForm() method that allows you insert a FormSource object in the document.
Example 5: Insert a form
FormSource simpleForm = new FormSource();
simpleForm.Size = new System.Windows.Size(310, 250); // .NET Framework
//simpleForm.Size = new Telerik.Documents.Primitives.Size(310, 250); // .NET Standard
FixedContentEditor formEditor = new FixedContentEditor(simpleForm);
formEditor.DrawText("Sample text.");
block.InsertForm(simpleForm);
For more information on how to create a form, check the Form and FormSource articles.
Changing Current Styles
The Block class has some properties and methods that affect how it will be rendered:
SpacingBefore: Represent the spacing before.
SpacingAfter: Represents the spacing after.
LineSpacing: The spacing between the lines.
LineSpacingType: Specifies how to interpret the line spacing.
FirstLineIndent: The indent for the first line.
LeftIndent: The left indent.
RightIndent: The right indent.
BackgroundColor: The background color.
HorizontalAlignment: The horizontal alignment of the content.
VerticalAlignment: The vertical alignment of the content.
Bullet: The element that should be rendered as Block’s list bullet.
IndentAfterBullet: The indent size after the bullet element.
TextProperties and GraphicProperties: Responsible for text and graphic properties. For more information see the Text and Graphic Properties article.
SaveTextProperties(): Saves the TextProperties. It returns an IDisposable object which when disposed calls RestoreTextProperties() and can be used in using statement.
RestoreTextProperties(): Restores the TextProperties to their previous state.
SaveGraphicProperties(): Saves the GraphicProperties. It returns an IDisposable object which when disposed calls RestoreTextProperties() and can be used in using statement.
RestoreGraphicProperties(): Restores the GrahpicPropertie to their previous state.
SaveProperties(): Saves both text and graphic properties. It returns an IDisposable object which when disposed calls RestoreTextProperties() and can be used in using statement.
RestoreProperties(): Restores both text and graphic properties.
SetBullet(List list, int listLevel): This method helps you to easily set bullet related properties respecting the numbering and the formatting of some List class instance. More information about lists you may find in this article.
Clear(): Clears all elements in the block.
Example 6: Change Block properties
RadFixedDocument radFixedDocument = new RadFixedDocument();
RadFixedPage page = radFixedDocument.Pages.AddPage();
Block block = new Block();
block.GraphicProperties.FillColor = new RgbColor(100, 0, 0, 0);
block.SpacingBefore = 10;
block.SpacingAfter = 5;
block.LineSpacingType = HeightType.Exact;
block.LineSpacing = 15;
block.FirstLineIndent = 0;
block.LeftIndent = 0;
block.RightIndent = 0;
block.BackgroundColor = new RgbColor(100, 255, 0, 0);
block.HorizontalAlignment = Telerik.Windows.Documents.Fixed.Model.Editing.Flow.HorizontalAlignment.Left;
block.VerticalAlignment = Telerik.Windows.Documents.Fixed.Model.Editing.Flow.VerticalAlignment.Top;
block.InsertText("block content");
TextFragment bulletTextFragment = new TextFragment();
bulletTextFragment.Text = "•";
block.Bullet = bulletTextFragment;
block.IndentAfterBullet = 15;
var editor = new FixedContentEditor(page);
editor.Position.Translate(50,50);
editor.DrawBlock(block);
Drawing a Block
A Block can be drawn to the content using the Draw() method. The method accepts as a parameter a Rectangle, specifying the desired size and position relatively to the editor of the element.
Example 7: Draw block
Rect boundingRect = new Rect(new Point(0, 0), new Size(200, 300));
block.Draw(fixedContentEditor, boundingRect);
Every block can be drawn only once. Otherwise, an exception will be thrown.
Measuring Block Size
Measuring a Block can be achieved with one of the two overloads of the Measure() method.
Invoking the method without a parameter will return the desired size of the block elements and set it as the block's DesiredSize property. The method is handy when you want to determine what size the Block should be depending on its content.
Example 8 Creates a Block with text, measures the text, and sets the block size to match the content size.
Block block = new Block();
block.BackgroundColor = new RgbColor(255, 255, 0, 0);
block.InsertText("Telerik Document Processing Libraries.");
// The size of the block content (DesiredSize)
Size desiredBlockContentSize = block.Measure(); // Width: 232.653, Height: 15.306
fixedContentEditor.DrawBlock(block); // If the block size (ActualSize) is not specified, it will automatically be assigned the content size (DesiredSize)
// Draw the block with Size equal to the size of the content
fixedContentEditor.DrawBlock(block, desiredBlockContentSize); // The block size (ActualSize) can also be explicitly set to the content size (DesiredSize) when drawing the block
Example 8 Result
The second overload accepts available Size. Calling it measures the block content as if the Block was in that specific size.
Additionally to setting the DesiredSize property, it also sets the PendingElements property with a collection of the elements that could not fit in the available size.
Example 9 Creates a Block with text and draws it with a specific size using the RadFixedContentEditor. The block content auto fits to the dimentions of the Block. The size of the auto fitted content can then be measured.
Block block = new Block();
block.BackgroundColor = new RgbColor(255, 255, 0, 0);
block.InsertText("Telerik Document Processing Libraries.");
// Draw with a specific block size (ActualSize), ignoring the content size (DesiredSize)
Size specificBlockSize = new Size(100, 100);
fixedContentEditor.DrawBlock(block, specificBlockSize);
// The size of the block content (DesiredSize) autofitted in the specified dimensions
CancellationTokenSource cancellationTokenSource = new(TimeSpan.FromSeconds(10));
CancellationToken cancellationToken = cancellationTokenSource.Token;
Size autoFittedBlockContentSize = block.Measure(specificBlockSize, cancellationToken); // Width: 65.946, Height: 61.226
Example 9 Result
Splitting a Block
The Split() method of a Block returns a new Block with the same properties. The resulting block contains all pending elements that do not fit in the current block, based on the result of the last measure call.
The code in Example 9 splits a block in two. The first will contains text "Hello" and the second – "RadPdfProcessing!".
Example 9: Split block
Block helloBlock = new Block();
helloBlock.InsertText("Hello");
Size helloSize = helloBlock.Measure();
Block block = new Block();
block.InsertText("Hello RadPdfProcessing!");
//Size size = block.Measure(helloSize); //This method is obsolete since Q4 2024.
CancellationTokenSource cancellationTokenSource = new(TimeSpan.FromSeconds(10));
CancellationToken cancellationToken = cancellationTokenSource.Token;
Size size = block.Measure(helloSize, cancellationToken);
Block secondBlock = block.Split();