TX Text Control .NET for Windows Forms Technical ArticlesUsing Images, Text Frames, Charts, Barcodes and Drawings
Images, text frames, charts, barcodes and drawings are represented through Image, TextFrame, ChartFrame, BarcodeFrameand DrawingFrame objects. The FrameBase class which is the base class of these objects handles the alignment in the text implementing properties like Location, TextDistances, InsertionMode, TextPosition and ChangeZOrder. All objects of the same kind are contained in collections, named ImageCollection, TextFrameCollection, ChartCollection, BarcodeCollectionand DrawingCollection, which can be used to add and to remove items or to get a particular item from the collection. Furthermore a FrameCollection has been defined containing all images, text frames, charts, barcodes and drawings. This collection is useful to get a particular item, regardless of the kind of object.
A chart frame is always associated with a chart control of the type System.Windows.Forms.DataVisualization.Charting.Chart. Therefore charts can only be used, when the assembly whichimplements this control is available. The Charting namespace is part of the .net Framework since version 4 and can be downloaded and installed for the .net Framework version 3.5.
A barcode frame is associated with a barcode control of the type TXTextControl.Barcode.TXBarcodeControl or TXTextControl.WPF.Barcode.TXBarcodeControl and can be only used, if the optional product assemblies for TX Barcode .NET are available.
A drawing frame is associated with a drawing control of the type TXTextControl.Drawing.TXDrawingControl or TXTextControl.WPF.Drawing.TXDrawingControl, which are located in the TXDrawing.dll, TXDrawing.Windows.Forms.dll and TXDrawing.WPF.dll assemblies.
TX Text Control supports three ways of inserting an image, a text frame, a chart, a barcode or a drawing into a document:
For each kind of object, image, textframe, chart, barcode and drawing, Text Control manages one collection containing all objects of that kind. The following describes the collection of images, the collections of the other work in the same way.
The image collection can be used to add and to remove images and to get a particular image from the collection. There are several Add methods which can be used to insert an image in the document.
The following two methods insert an image inline, which means that it is treated in the text like a single character:
public bool Add();
public bool Add(Image image, int textPosition);Public Function Add() As Boolean
Public Function Add(ByVal image As Image, ByVal textPosition As Integer) As BooleanThe first version has no parameters and opens a File Open dialog box providing all image formats TX Text Control supports. The user can select an image, close the dialog box and the image is added to the collection and automatically inserted in the document at the current input position. The second method works in the same way, but inserts the image at the specified text position. To avoid, that adialog box is opened, the Image.FileName and the Image.FilterIndex property of the specified Image object must be set.
The following two methods insert an image anchored to a paragraph, which means that it is moved with the paragraph it is anchored to:
public bool Add(Image image, HorizontalAlignment alignment, int textPosition, ImageInsertionMode insertionMode);
public bool Add(Image image, Point location, int textPosition, ImageInsertionMode insertionMode);Public Function Add(ByVal image As Image, ByVal alignment As HorizontalAlignment, ByVal textPosition As Integer, _
ByVal insertionMode As ImageInsertionMode) As Boolean
Public Function Add(ByVal image As Image, ByVal location As Point, ByVal textPosition As Integer, _
ByVal insertionMode As ImageInsertionMode) As BooleanThe text position can be any position in the paragraph. If -1 is specified, the image is anchored to the paragraph containing the current text input position. The location of the image relative to the paragraph is determined through a horizontal alignment or through a horizontal and a vertical offset. The position and extension of a paragraph is determined through its left and its right paragraph indent.The insertionMode parameter determines the textflow. The following values are possible:
Both methods open a file open dialog box only, when the Image.FileName and the Image.FilterIndex property of the specified Image object has not been set. The Image.Alignment property is only available for images anchored to a paragraph, for inline images and fixed positioned images a horizontal alignment is not defined.
The following code shows an example for inserting an image anchored to the fifth paragraph of a document:
Paragraph p = textControl1.Paragraphs[5];
textControl1.Images.Add(new Image(), HorizontalAlignment.Left, p.Start-1, ImageInsertionMode.DisplaceText);Dim p As Paragraph = TextControl1.Paragraphs.Item(5)
TextControl1.Images.Add(New Image(), HorizontalAlignment.Left, p.Start - 1, ImageInsertionMode.DisplaceText)The remaining two methods insert an image at a fixed geometric position in the document, which means that there is noanchor position and the image remains always at the same location:
public bool Add(Image image, int page, Point location, ImageInsertionMode insertionMode);
public bool Add(Image image, Point location, ImageInsertionMode insertionMode);Public Function Add(ByVal image As Image, ByVal page As Integer, ByVal location As Point, _
ByVal insertionMode As ImageInsertionMode) As Boolean
Public Function Add(ByVal image As Image, ByVal location As Point, _
ByVal insertionMode As ImageInsertionMode) As BooleanThe first method defines the geometric position through a certain page and a location relative to the top-left corner on that page.The second method defines the position relative to the top-left corner of the complete document. This also includes all gaps between thepages. The horizontal value is relative to the left edge of all pages and the vertical value is relative to the top of the document including the gap above the first page.Regardless of which method has been used to insert the image the Image.Location property returns the location relative to the complete document. The insertionMode parameter determines the textflow with the same values as descibed for images anchored to a paragraph. Both methods open a file open dialog box only, when the Image.FileName and the Image.FilterIndex property of the specified Image object has not been set.
TX Text Control can load images saved with the following image formats, while the SVG format is only supported by managed code TextControl components available for Windows Forms, WPF and ASP.NET.:
If an image has been added to a document with one of the ImageCollection.Add methods and this document is saved, a reference to the image file is saved. This reference is the image's file name including its absolute path on the file system. If such a document is loaded and the image to where the saved file reference points cannot be found, a rectangle with the image's size and a text string with the file name is displayed. The LoadSettings.ImageSearchPath property determines an additional path where to find images.
Images which are pasted from the clipboard have no file reference, therefore these images are saved in a document with their binary data. By default TX Text Control saves the image's binary data in its original file format.
Alternatively, a programmer can specify with the SaveSettings.ImageSaveMode or with the Image.SaveMode property whether images are saved through a file reference or with their binary data. The SaveSettings.ImageSaveMode property determines this for all images of the document and the Image.SaveMode property determines it for a certain image. If ImageSaveMode.SaveAsFileReference is specified for an image and a file for this image does not exist, a new file is created.
The SaveSettings.ImageExportFilterIndex and the Image.ExportFilterIndex properties can be used to save images in another than their original format. The SaveSettings.ImageExportFilterIndex property determines the export format for all images of the document and the Image.ExportFilterIndex property determines the export format for a certain image. TX Text Control supports the following formats to export images:
If an export format has been specified and a text filter does not support this format, the image is stored in the default format of the text filter. The following lists the image formats supported by each text filter. The first format (in bold) is the default format, used when the specified format is not possible:
If images are exported in another format, either the binary data is embedded in the document or new files are created and references to these files are embedded in the document. TX Text Control creates these files with the following rules: