# Images > Insert, anchor and scale images in a Windows Forms TextControl with ImageCollection.Add, the Frame Formatting tab, ImageAttributesDialog and save settings. - **Product:** TX Text Control .NET for Windows Forms - **Section:** Documentation - **Kind:** Topic - **Path:** TX Text Control .NET for Windows Forms > Document Editor > Images - **3955 words** - **Web URL:** https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-editor/images/ - **LLMs URL:** https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-editor/images/llms.txt - **LLMs-Full URL:** https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-editor/images/llms-full.txt --- Logos, photos, scanned signatures and diagrams become part of a document as images. Users of a Windows Forms `TextControl` insert them from the ribbon, drag them into place, resize them with the mouse and choose how the text flows around them; your code inserts images from files, anchors them to paragraphs, reacts when the user clicks them and opens the built-in dialog box. The examples are methods of *Form1.cs* in the application of [Create Your First Windows Forms Application](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/getting-started/document-editor/first-application/llms-full.txt), with a `TextControl` named `textControl1`. Call them from the `Click` handler of a button, and copy an image named *logo.png* into the output folder of the project. Inserting and extracting images without a user interface, with `ServerTextControl`, is covered in [Images, Text Frames, and Shapes](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-processing/images-shapes/llms-full.txt). ### How Images Are Placed An [Image](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/image/llms-full.txt) is one of the frames of a document, together with text frames, charts, barcodes and drawings, and shares their base class [FrameBase](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/framebase/llms-full.txt) with its name, ID, size, location and text distances. [TextControl.Images](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/images-property/llms-full.txt) returns the [ImageCollection](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/imagecollection/llms-full.txt) of the text part with the input focus: the main text, or the header, footer or text frame the user is editing. ![Class diagram of the image classes: TextControl, WPF.TextControl and ServerTextControl with their Images property and image events, ImageCollection with its Add, GetItem and Remove methods, and the Image class with its properties.](https://docs.textcontrol.com/assets/img/tx-text-control-dotnet-winforms/images-class-diagram.e6302deb.webp) An image is placed inline, like a single character of the text, anchored to a paragraph, with which it moves, or at a fixed position on a page. [How Frames Are Placed](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-processing/images-shapes/#how-frames-are-placed) describes the three placements, the `Add` overload of each and the text flow values for all kinds of frames. When the user drags an anchored image, its anchor moves to the paragraph nearest to its new top-left corner. Locations and sizes are measured in twips, 1/1440 inch. ### Insert and Arrange Images in the Ribbon On the **Insert** tab, **Image** in the **Illustrations** group inserts an image at the input position. Its **Image...** item opens a file dialog box with the image formats TX Text Control reads; **Image Placeholder** is for templates, as [Images and Barcodes](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/mail-merge/images-barcodes/llms-full.txt) in Mail Merge describes. ![The Insert tab of the ribbon with the groups Pages, Tables and Illustrations, where the mouse points at the Image button next to Chart, Shape and Barcode.](https://docs.textcontrol.com/assets/img/tx-text-control-dotnet-winforms/ribbon-insert-illustrations.7aa6bb64.webp) A click on an image selects it and shows its sizing handles. Users drag the image to move it and drag a handle to resize it. The **Frame Formatting** tab, a [RibbonFrameLayoutTab](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-windows-forms-ribbon/ribbonframelayouttab/llms-full.txt), changes the selected image: - **Arrange:** **Wrap Text** sets the text flow with **In Line with Text**, **Top and Bottom**, **Square**, **In Front of Text** and **Behind Text**, and **More Layout Options...** opens the dialog box. **Bring to Front** and **Send to Back** change the order of overlapping objects, and **Position** aligns the image. - **Size:** **Height** and **Width**. - **Properties:** the **Name**, **ID** and **Descriptive Text** of the image. ![TX Text Control Words with a selected logo in the header of an invoice and the Frame Formatting tab of the Frame Tools group, with the groups Arrange, Size and Properties.](https://docs.textcontrol.com/assets/img/tx-text-control-dotnet-winforms/header-footer-tab.a3713148.webp) TX Text Control Words shows this tab in a contextual **Frame Tools** group while a frame is selected, which [Built-in Ribbon Tabs](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-editor/ribbon-ui/ribbon/#show-tabs-only-in-context) describes. The same tab formats text frames, drawings and barcodes, with a group of its own for each kind. ### Insert an Image From Code The following methods open the file dialog box and insert a logo from a file, anchored at the right edge of the paragraph with the input position: ```csharp using System; using System.Windows.Forms; using TXTextControl; public partial class Form1 : Form { private void InsertImageWithDialog() { // Opens a file dialog box and inserts the image inline at the input position textControl1.Images.Add(); } private void InsertLogo() { // 4 is the import filter for PNG TXTextControl.Image logo = new TXTextControl.Image("logo.png", 4); // Anchored to the paragraph at the input position, the text flows around it textControl1.Images.Add(logo, TXTextControl.HorizontalAlignment.Right, -1, ImageInsertionMode.DisplaceText); logo.Name = "logo"; logo.DescriptiveText = "Company logo"; } } ``` The code works as follows: - [ImageCollection.Add](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/imagecollection/add-method/llms-full.txt) without parameters opens a file dialog box and inserts the chosen image inline at the input position. Every other overload opens the dialog box as well when the `Image` has neither a file name nor a filter index. - The [Image constructor](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/image/constructor/llms-full.txt) takes the file name and the number of the import filter; 4 is PNG. Other constructors take a `System.Drawing.Image` or a `MemoryStream`. - `Add(image, alignment, textPosition, insertionMode)` anchors the image to the paragraph that contains the text position; `-1` is the input position. The alignment is `Left`, `Right` or `Center`, and [ImageInsertionMode](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/imageinsertionmode/enumeration/llms-full.txt) sets the text flow. - [FrameBase.Name](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/framebase/name-property/llms-full.txt) is the name your code finds the image by later, and [DescriptiveText](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/framebase/descriptivetext-property/llms-full.txt) its alternative text for screen readers and tagged PDF files. In a form, the names `Image` and `HorizontalAlignment` exist in `System.Drawing` and `System.Windows.Forms` as well, so the code writes `TXTextControl.Image` and `TXTextControl.HorizontalAlignment`. The two remaining overloads place an image at a fixed position: `Add(image, page, location, insertionMode)` relative to the top-left corner of a page, numbered from 1, and `Add(image, location, insertionMode)` relative to the whole document, including the gaps between the pages. What the position properties return depends on the placement: - [FrameBase.Location](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/framebase/location-property/llms-full.txt) of an image at a fixed position is relative to the whole document, whichever of the two overloads inserted it. For an anchored image it is relative to the paragraph, whose position and width are given by its left and right indents. It returns zero for an inline image and for an image with a horizontal alignment. - [FrameBase.Alignment](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/framebase/alignment-property/llms-full.txt) is defined only for images anchored to a paragraph. Inline images and images at a fixed position have no horizontal alignment. ### Image Formats The import filters are numbered in the order of [ImageCollection.ImportFilters](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/imagecollection/importfilters-property/llms-full.txt), a filter string you can assign to the `Filter` property of an `OpenFileDialog` of your own. Its `FilterIndex` then serves as the filter number of the image: | Filter index | Format | |---|---| | 1 | Windows Bitmap (BMP) | | 2 | Tagged Image Format (TIF) | | 3 | Windows Metafile (WMF) | | 4 | Portable Network Graphics (PNG) | | 5 | JPEG (JPG, JPEG) | | 6 | Graphics Interchange Format (GIF) | | 7 | Windows Enhanced Metafile (EMF) | | 8 | Scalable Vector Graphics (SVG) | The blog article [Various Ways of Inserting Images into TX Text Control](https://www.textcontrol.com/blog/2024/05/03/various-ways-of-inserting-images-into-tx-text-control/) inserts images from memory streams, byte arrays and URLs. ### React to the Selected Image Your code finds the image the user has selected and can open the dialog box for it. The following methods open the dialog box on a double-click and halve the size of the selected image: ```csharp using System; using System.Windows.Forms; using TXTextControl; public partial class Form1 : Form { private void ConnectImageEvents() { textControl1.ImageDoubleClicked += TextControl1_ImageDoubleClicked; } private void TextControl1_ImageDoubleClicked(object sender, ImageEventArgs e) { // A double-click selects the image, so the dialog box opens for it textControl1.ImageAttributesDialog(); } private void HalveSelectedImage() { // The image the user has selected, or null TXTextControl.Image image = textControl1.Images.GetItem(); if (image != null) { // Scaling factors in percent image.HorizontalScaling = 50; image.VerticalScaling = 50; } } } ``` The code works as follows: - [ImageDoubleClicked](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/imagedoubleclicked-event/llms-full.txt) passes an [ImageEventArgs](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/imageeventargs/llms-full.txt) whose [Image](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/imageeventargs/image-property/llms-full.txt) is the image. Call `ConnectImageEvents` once, for example in the constructor of the form. - [ImageAttributesDialog](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/imageattributesdialog-method/llms-full.txt) opens the dialog box of the selected image, with tabs for text wrapping and layout, size and distances, and saving options. It's shown only when an image is selected. - [ImageCollection.GetItem](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/imagecollection/getitem-method/llms-full.txt) without a parameter returns the selected image, or `null`. With a name or an ID, it returns that image. - [HorizontalScaling](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/image/horizontalscaling-property/llms-full.txt) and [VerticalScaling](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/image/verticalscaling-property/llms-full.txt) scale the image in percent. The size of an image, `FrameBase.Size`, can only be read. Other events report what users do with images: [ImageClicked](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/imageclicked-event/llms-full.txt), [ImageMoved](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/imagemoved-event/llms-full.txt), [ImageSized](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/imagesized-event/llms-full.txt) and [ImageDeleted](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/imagedeleted-event/llms-full.txt). [ImageCreated](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/imagecreated-event/llms-full.txt) occurs for images that are pasted or loaded with a document, but not for images your code adds. For all kinds of frames at once, [TextControl.Frames](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/frames-property/llms-full.txt) and the [FrameSelected](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/frameselected-event/llms-full.txt) event report the selected image, text frame, chart, barcode or drawing. [Events](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-editor/events/llms-full.txt) lists them all. ### Control How Images Are Saved An image inserted from a file is saved as a reference to that file, with its absolute path, while pasted images are saved with their data in their original format. When a document is opened on another computer, a file reference may point nowhere, and the image is shown as a rectangle with its file name. To keep the images in the document, save them as data: - [SaveSettings.ImageSaveMode](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/savesettings/imagesavemode-property/llms-full.txt) `SaveAsData` saves all images with their data, and [Image.SaveMode](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/image/savemode-property/llms-full.txt) does it for one image. - `SaveAsFileReference` saves the images as file references. An image that has no file yet, such as a pasted one, is written to a new file. - [SaveSettings.ImageExportFilterIndex](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/savesettings/imageexportfilterindex-property/llms-full.txt) and [Image.ExportFilterIndex](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/image/exportfilterindex-property/llms-full.txt) save images in another format. Their numbers differ from the import filters and follow the order of [ImageCollection.ExportFilters](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/imagecollection/exportfilters-property/llms-full.txt): 1 BMP, 2 WMF, 3 PNG, 4 JPG, 5 EMF, 6 TIF and 7 GIF. - [LoadSettings.ImageSearchPath](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/loadsettings/imagesearchpath-property/llms-full.txt) sets a folder in which file references are searched when a document is loaded. Users set the same options on the saving tab of the image dialog box. [Loading and Saving Documents](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-editor/load-save/llms-full.txt) describes `SaveSettings` and `LoadSettings`. #### Image Formats of Each Document Format Each document format stores only some image formats. When an image's format, or the export format you set, isn't one of them, the image is saved in the default format of the document format, the first in its row: | Document format | Image formats, default first | |---|---| | RTF | PNG, BMP, WMF, JPG, EMF | | DOC | WMF, BMP, PNG, JPG, EMF, TIF | | DOCX | PNG, BMP, WMF, JPG, EMF, TIF, GIF, SVG | | HTML | PNG, BMP, JPG, GIF | | PDF | BMP, JPG; the vector formats EMF, WMF and SVG are converted to PostScript | | TX Text Control format | WMF, BMP, PNG, JPG, EMF, TIF, GIF, SVG | #### Where Image Files Are Saved When images are saved as file references, for example in an HTML document, TX Text Control writes the image files by these rules: 1. **Folder.** [SaveSettings.ImageSavePath](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/savesettings/imagesavepath-property/llms-full.txt) sets the folder, which is created if it doesn't exist. Without it, the files go into a subfolder next to the document, named after the document with `_Images` appended: for `C:\temp\sample.rtf`, that is `C:\temp\sample_Images\`. 2. **File name.** [Image.ExportFileName](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/image/exportfilename-property/llms-full.txt) sets the name of an image's file; users set it in the image dialog box. 3. **Without an export file name**, the original file name is used, with the extension of the export format. 4. **Without any file name**, the name of the document followed by a number is used, such as `sample_1.bmp` and `sample_2.bmp` for images exported as BMP. ### Next Steps - [Text Frames and Shapes](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-editor/text-frames-shapes/llms-full.txt): place text boxes and drawings like images. - [Headers and Footers](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-editor/headers-footers/llms-full.txt): put a logo on every page. - [Images and Barcodes](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/mail-merge/images-barcodes/llms-full.txt): fill image placeholders of a template with data. - [Images, Text Frames, and Shapes](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-processing/images-shapes/llms-full.txt): images in code with `ServerTextControl`. --- ## Nearby - **Previous:** [Tables and Table Formulas](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-editor/tables/llms-full.txt) - **Next:** [Text Frames and Shapes](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-editor/text-frames-shapes/llms-full.txt)