# Block

The `Block` class arranges the elements added to it in a flow-like manner. You can use it 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](https://www.telerik.com/document-processing-libraries/documentation/libraries/radpdfprocessing/editing/fixedcontenteditor), a block can contain images, graphics, or text. The same Block instance can only be drawn once.

### Inserting Text

Insert [TextFragments](https://www.telerik.com/document-processing-libraries/documentation/libraries/radpdfprocessing/model/textfragment) 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**

```C#
Telerik.Documents.Fixed.Model.Editing.Block block = new Block();
block.InsertText("Text");
#if NET8_0_WINDOWS
//.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");
#else
//.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"); 
#endif
```

> The '\r' and '\n' characters do not have the usual meaning of "go to next line" when inserted into a PDF document, and you cannot insert text containing these characters to produce multiline text. Instead, insert a line break.

> important In **.NET Standard/.NET (Target OS: None)** environments, fonts beyond the [14 standard ones](https://www.telerik.com/document-processing-libraries/documentation/libraries/radpdfprocessing/concepts/fonts#standard-fonts) require a [FontsProvider implementation](https://www.telerik.com/document-processing-libraries/documentation/knowledge-base/pdfprocessing-implement-fontsprovider) to be resolved correctly.

### Inserting Line Break

Inserting a line break results in the next element starting on a new line. Use the `InsertLineBreak()` method as shown in **Example 2**.

**Example 2: Break the line**

```C#
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**

```C#
string imageFilePath = "sample.jpg";
FileStream fileStream = new FileStream(imageFilePath, FileMode.Open);
Telerik.Documents.Fixed.Model.Resources.ImageSource imageSrc =
    new Telerik.Documents.Fixed.Model.Resources.ImageSource(fileStream);

block.InsertImage(imageSrc, 300, 200);
```

Information on images in the context of the library is available in the [ImageSource](https://www.telerik.com/document-processing-libraries/documentation/libraries/radpdfprocessing/model/imagesource) and [Image](https://www.telerik.com/document-processing-libraries/documentation/libraries/radpdfprocessing/model/image) articles.

### Inserting Geometries

[Geometries](https://www.telerik.com/document-processing-libraries/documentation/libraries/radpdfprocessing/concepts/geometry) 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**

```C#
Telerik.Documents.Fixed.Model.Graphics.RectangleGeometry rectangleGeometry =
    new Telerik.Documents.Fixed.Model.Graphics.RectangleGeometry();

#if NET8_0_WINDOWS //.NET Framework
rectangleGeometry.Rect = new System.Windows.Rect(10, 10, 400, 300); 
block.InsertRectangle(new System.Windows.Rect(10, 10, 200, 150)); 
#else //.NET Standard
//rectangleGeometry.Rect = new Telerik.Documents.Primitives.Rect(10, 5, 400, 300); 
//block.InsertRectangle(new Telerik.Documents.Primitives.Rect(20, 30, 200, 150)); 
#endif
block.InsertPath(rectangleGeometry);
```

### Inserting Form-XObject Elements

The Form (also known as Form-XObject) is an object that can contain PDF content and can be shared among the document. The `Block` class exposes the `InsertForm()` method that allows you to insert a `FormSource` object in the document.

**Example 5: Insert a form**

```C#

FormSource simpleForm = new FormSource();
#if NET8_0_WINDOWS
simpleForm.Size = new System.Windows.Size(310, 250); // .NET Framework 
#else
//simpleForm.Size = new Telerik.Documents.Primitives.Size(310, 250); // .NET Standard 
#endif

FixedContentEditor formEditor = new FixedContentEditor(simpleForm);
formEditor.DrawText("Sample text.");

block.InsertForm(simpleForm);
```

There are two more overloads of `InsertForm()` that allow you to pass the size that should be used for the form.

> For more information on how to create a form, see the [Form](https://www.telerik.com/document-processing-libraries/documentation/libraries/radpdfprocessing/model/form) and [FormSource](https://www.telerik.com/document-processing-libraries/documentation/libraries/radpdfprocessing/model/formsource/overview) articles.

### Inserting Link Annotation

The following example shows how to insert a link inside the text:

**Example 6: Insert a text link**

```C#
Block block = new Block();
block.InsertHyperlinkStart(new Uri("https://docs.telerik.com/devtools/document-processing/libraries/radpdfprocessing/getting-started"));
block.InsertText("text");
block.InsertHyperlinkEnd();
```

### Changing Current Styles

The `Block` class has properties and methods that affect how it is rendered:

* `SpacingBefore`: Represents the spacing before.

* `SpacingAfter`: Represents the spacing after.

* `LineSpacing`: The spacing between lines. Defaults to `1.15`. When `LineSpacingType` is `Auto`, this acts as a line height multiplier. When `LineSpacingType` is `Exact` or `AtLeast`, this specifies the line height in [Device Independent Pixels](https://www.telerik.com/document-processing-libraries/documentation/common-information/device-independent-pixels) (DIPs).

* `LineSpacingType`: Specifies how to interpret the line spacing using the `HeightType` enumeration (`Auto`, `Exact`, `AtLeast`). Defaults to `Auto`.

* `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 is rendered as the `Block` 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](https://www.telerik.com/document-processing-libraries/documentation/libraries/radpdfprocessing/editing/text-and-graphic-properties) article.

* `SaveTextProperties()`: Saves the TextProperties. It returns an IDisposable object which when disposed calls `RestoreTextProperties()` and can be used in a using statement.

* `RestoreTextProperties()`: Restores the TextProperties to their previous state.

* `SaveGraphicProperties()`: Saves the GraphicProperties. It returns an IDisposable object which when disposed calls `RestoreGraphicProperties()` and can be used in a using statement.

* `RestoreGraphicProperties()`: Restores the GraphicProperties to their previous state.

* `SaveProperties()`: Saves both text and graphic properties. It returns an IDisposable object which when disposed calls `RestoreProperties()` and can be used in a using statement.

* `RestoreProperties()`: Restores both text and graphic properties.

* `SetBullet(List list, int listLevel)`: This method helps you set bullet-related properties respecting the numbering and the formatting of some `List` class instance. More information about lists is available in the [List](https://www.telerik.com/document-processing-libraries/documentation/libraries/radpdfprocessing/editing/list) article.

* `Clear()`: Clears all elements in the block.

**Example 7: Change Block properties**

```C#
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.Documents.Fixed.Model.Editing.Flow.HorizontalAlignment.Left;
block.VerticalAlignment = Telerik.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);
```

![RadPdfProcessing Block Properties Result](https://www.telerik.com/document-processing-libraries/documentation/assets/8447776410279ef7b400585b7c06092a/radpdfprocessing-editing-block_5_result.png)

## 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 relative to the editor of the element.

**Example 8: Draw block**

```C#
Rect boundingRect = new Rect(0, 0, 200, 300);
block.Draw(editor, boundingRect);
```

> important Every block can be drawn only once. Otherwise, an exception is 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 returns the desired size of the block elements and sets it as the block `DesiredSize` property. The method is handy when you want to determine what size the `Block` needs depending on its content.

**Example 9** creates a `Block` with text, measures the text, and sets the block size to match the content size.

```C#
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 9 Result**

![RadPdfProcessing Block Example 9 Result](https://www.telerik.com/document-processing-libraries/documentation/assets/94f65b2c07b9f129423c1c2bbaa493c8/radpdfprocessing_measuring_block_01.png)

The second overload accepts an available `Size`. Calling it measures the block content as if the `Block` was in that specific size. Additionally, it sets the `PendingElements` property with a collection of the elements that could not fit in the available size.

**Example 10** creates a `Block` with text and draws it with a specific size using the [FixedContentEditor](https://www.telerik.com/document-processing-libraries/documentation/libraries/radpdfprocessing/editing/fixedcontenteditor). The block content auto-fits to the dimensions of the `Block`. The size of the auto-fitted content can then be measured.

```C#
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 10 Result**

![RadPdfProcessing Block Example 10 Result](https://www.telerik.com/document-processing-libraries/documentation/assets/0718b0c25c0ba07577b6194d4d34a246/radpdfprocessing_measuring_block_02.png)

## 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 11** splits a block in two. The first contains text "Hello" and the second contains "RadPdfProcessing!".

**Example 11: Split block**

```C#
Block helloBlock = new Block();
helloBlock.InsertText("Hello");
Size helloSize = helloBlock.Measure();

Block block = new Block();
block.InsertText("Hello RadPdfProcessing!");

CancellationTokenSource cancellationTokenSource = new(TimeSpan.FromSeconds(10));
CancellationToken cancellationToken = cancellationTokenSource.Token;

Size size = block.Measure(helloSize, cancellationToken);

Block secondBlock = block.Split();
```

## See Also

* [FixedContentEditor](https://www.telerik.com/document-processing-libraries/documentation/libraries/radpdfprocessing/editing/fixedcontenteditor)
* [TextFragment](https://www.telerik.com/document-processing-libraries/documentation/libraries/radpdfprocessing/model/textfragment)
* [Image](https://www.telerik.com/document-processing-libraries/documentation/libraries/radpdfprocessing/model/image)
* [Geometry](https://www.telerik.com/document-processing-libraries/documentation/libraries/radpdfprocessing/concepts/geometry)
* [Text and Graphic Properties](https://www.telerik.com/document-processing-libraries/documentation/libraries/radpdfprocessing/editing/text-and-graphic-properties)
* [How to Measure Text in WordsProcessing .NET Framework](https://www.telerik.com/document-processing-libraries/documentation/knowledge-base/wordsprocessing-measure-text-netframework)
* [How to Measure Text in WordsProcessing .NET Standard](https://www.telerik.com/document-processing-libraries/documentation/knowledge-base/wordsprocessing-measure-text-netstandard)
* [How to Generate a PDF Document from Images with FixedContentEditor](https://www.telerik.com/document-processing-libraries/documentation/knowledge-base/pdf-from-images-with-fixedcontenteditor)
* [How to Change Text Color Using PdfProcessing](https://www.telerik.com/document-processing-libraries/documentation/knowledge-base/pdfprocessing-text-color)
* [Positioning Centered and Right-Aligned Text on the Same Line in PDF](https://www.telerik.com/document-processing-libraries/documentation/knowledge-base/aligning-centered-right-margin-text-pdf-telerik-document-processing)
* [Clone PDF Template Pages with Form Fields to Accommodate Dynamic Content](https://www.telerik.com/document-processing-libraries/documentation/knowledge-base/clone-pdf-template-pages-with-form-fields-dynamic-content)