# Text Frames and Shapes > Let users draw text frames and shapes in a Windows Forms TextControl, or insert them in C# with TextFrameCollection, TXDrawingControl, Shape and DrawingFrame. - **Product:** TX Text Control .NET for Windows Forms - **Section:** Documentation - **Kind:** Topic - **Path:** TX Text Control .NET for Windows Forms > Document Editor > Text Frames and Shapes - **4423 words** - **Web URL:** https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-editor/text-frames-shapes/ - **LLMs URL:** https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-editor/text-frames-shapes/llms.txt - **LLMs-Full URL:** https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-editor/text-frames-shapes/llms-full.txt --- A text frame is a box with text of its own that sits anywhere on a page: an address block for a window envelope, a note beside a paragraph, a sidebar with a small table. Drawings add shapes such as lines, arrows, stars and callouts. In a Windows Forms `TextControl`, users draw both with the mouse from the **Insert** tab, and your code inserts, finds and formats them through `TextFrames` and `Drawings`. The examples are methods of *Form1.cs* of the application from [Create Your First Windows Forms Application](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/getting-started/document-editor/first-application/llms-full.txt), called from the `Click` handler of a button. Frames are placed like images, inline, anchored to a paragraph or at a fixed position, as [How Frames Are Placed](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-processing/images-shapes/#how-frames-are-placed) explains. Text frames and drawings in documents processed without a user interface are covered in [Images, Text Frames, and Shapes](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-processing/images-shapes/llms-full.txt). ### How Text Frames Work A [TextFrame](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textframe/llms-full.txt) is a text part of its own, like a header: it has a [Selection](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textframe/selection-property/llms-full.txt), paragraphs, tables, images and fields, and users type into it as into the main text. [TextControl.TextFrames](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/textframes-property/llms-full.txt) returns the [TextFrameCollection](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textframecollection/llms-full.txt) of the text part with the input focus: the main text, a header or footer, or a text frame, which can hold text frames of its own. ![Class diagram of the text frame classes: TextControl, WPF.TextControl and ServerTextControl with TextFrames, TextFrameMarkerLines and the text frame events, TextFrameCollection and the TextFrame class with its properties and collections.](https://docs.textcontrol.com/assets/img/tx-text-control-dotnet-winforms/text-frames-class-diagram.23648174.webp) A text frame on the screen is in one of two states: - **Selected.** The frame is selected as an object and shows sizing handles; users move, resize or delete it. [TextFrameCollection.GetItem](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textframecollection/getitem-method/llms-full.txt) without a parameter returns it. - **Activated.** The input position is inside the frame, and the user edits its text. [GetActivatedItem](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textframecollection/getactivateditem-method/llms-full.txt) returns it, and [DeactivateItem](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textframecollection/deactivateitem-method/llms-full.txt) moves the input position back to the text around it. Sizes, borders and margins are measured in twips, 1/1440 inch. ### Insert Text Frames and Shapes in the Ribbon **Text Frame** in the **Text** group of the **Insert** tab has two items. **Insert Text Frame** changes the mouse pointer to a cross, and the user draws the frame; ESC cancels. **Show Text Frame Marker Lines** shows the outline of frames without a border, which is [TextControl.TextFrameMarkerLines](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/textframemarkerlines-property/llms-full.txt) in code. **Shape** in the **Illustrations** group opens a gallery of shapes in the categories **Lines**, **Rectangles**, **Basic Shapes**, **Block Arrows**, **Equation Shapes**, **Flowchart**, **Stars and Banners** and **Callouts**. **New Drawing Canvas** inserts an empty canvas that holds several shapes, and **Show Drawing Marker Lines** shows the frame of each drawing, [TextControl.DrawingMarkerLines](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/drawingmarkerlines-property/llms-full.txt) in code. ![TX Text Control Words with the Shape gallery of the Insert tab open, showing its categories from Lines to Callouts, the items New Drawing Canvas and Show Drawing Marker Lines, and a blue smiley face shape in the document.](https://docs.textcontrol.com/assets/img/tx-text-control-dotnet-winforms/insert-tab-shape-gallery.3fec7b12.webp) A selected text frame or drawing is formatted on the **Frame Formatting** tab, the [RibbonFrameLayoutTab](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-windows-forms-ribbon/ribbonframelayouttab/llms-full.txt). Besides **Arrange**, **Size** and **Properties**, which work as for images, it shows a **Frames & Background** group with **Background Color**, **Transparency**, **Border Width** and **Border Color** for a text frame, and one with **Line Color**, **Background Color**, **Line Width**, **Transparency** and **Rotate** for a drawing. ### Insert a Text Frame From Code The first method lets the user draw a text frame, as **Insert Text Frame** does. The second inserts a note with a background color and a double border at the right edge of the current paragraph: ```csharp using System; using System.Drawing; using System.Windows.Forms; using TXTextControl; public partial class Form1 : Form { private void DrawTextFrame() { // The user draws the frame with the mouse; ESC cancels TextFrame frame = new TextFrame(new Size(2880, 1440)); textControl1.TextFrames.Add(frame, TextFrameInsertionMode.DisplaceText); } private void InsertNote() { // 3 x 1.5 inches in twips TextFrame note = new TextFrame(new Size(4320, 2160)) { Name = "note", BackColor = Color.LightYellow, BorderWidth = 20, BorderColor = Color.DarkBlue, BorderStyle = TXTextControl.FrameStyle.Double, InternalMargins = new int[] { 144, 144, 144, 144 } }; // Anchored at the right edge of the paragraph at the input position textControl1.TextFrames.Add(note, TXTextControl.HorizontalAlignment.Right, -1, TextFrameInsertionMode.DisplaceText); // The frame has a selection of its own note.Selection.Text = "Payment due within 14 days."; } } ``` The code works as follows: - The [TextFrame constructor](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textframe/constructor/llms-full.txt) takes the size of the frame. - [TextFrameCollection.Add](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textframecollection/add-method/llms-full.txt) with only a [TextFrameInsertionMode](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textframeinsertionmode/enumeration/llms-full.txt) starts the built-in mouse interface: the user determines the size and position, and changing the document or pressing ESC cancels it. `DisplaceText` lets the text flow around the frame. - `Add(frame, alignment, textPosition, insertionMode)` anchors the frame to the paragraph with the text position; `-1` is the input position. Other overloads insert it inline or at a fixed position on a page. - [BackColor](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textframe/backcolor-property/llms-full.txt), [BorderWidth](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textframe/borderwidth-property/llms-full.txt), [BorderColor](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textframe/bordercolor-property/llms-full.txt) and [BorderStyle](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textframe/borderstyle-property/llms-full.txt) set its appearance, and [InternalMargins](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textframe/internalmargins-property/llms-full.txt) the distances between border and text, left, top, right and bottom. `FrameStyle` also exists in `System.Windows.Forms`, so the code writes `TXTextControl.FrameStyle`. - `note.Selection.Text` writes into the frame, as `textControl1.Selection` does in the main text. ### Work With the Selected or Activated Frame The following methods open the text frame dialog box for the selected frame and insert today's date into the frame the user is editing: ```csharp using System; using System.Windows.Forms; using TXTextControl; public partial class Form1 : Form { private void ShowFrameAttributes() { // A text frame the user has selected, or null if (textControl1.TextFrames.GetItem() != null) { textControl1.TextFrameAttributesDialog(); } } private void InsertDateIntoActiveFrame() { // The text frame whose text the user is editing, or null TextFrame frame = textControl1.TextFrames.GetActivatedItem(); if (frame != null) { frame.Selection.Text = DateTime.Today.ToShortDateString(); } } } ``` - [TextFrameAttributesDialog](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/textframeattributesdialog-method/llms-full.txt) opens the dialog box with tabs for text wrapping and layout, size and distances, and border and background color. It's shown only while a text frame is selected. - `GetActivatedItem` returns `null` while the input position is in the main text. The editor reports what users do with text frames: [TextFrameActivated](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/textframeactivated-event/llms-full.txt) occurs when a frame receives the input position, and events such as `TextFrameSelected`, `TextFrameMoved` and `TextFrameSized` follow the mouse actions, each with a [TextFrameEventArgs](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textframeeventargs/llms-full.txt) that holds the [TextFrame](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textframeeventargs/textframe-property/llms-full.txt). See [Events](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-editor/events/llms-full.txt). ### Insert a Shape From Code A drawing in the document consists of two objects: a [TXDrawingControl](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-drawing/txdrawingcontrol/llms-full.txt) that holds the shapes, and a [DrawingFrame](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-datavisualization/drawingframe/llms-full.txt) that places it in the document like a text frame. [TextControl.Drawings](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/drawings-property/llms-full.txt) returns the [DrawingCollection](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-datavisualization/drawingcollection/llms-full.txt). ![Class diagram of the drawing classes: TextControl, WPF.TextControl and ServerTextControl with Drawings and the drawing events, DrawingCollection, DrawingFrame, TXDrawingControl, the shape collection and the Shape class.](https://docs.textcontrol.com/assets/img/tx-text-control-dotnet-winforms/drawings-class-diagram.743b394e.webp) The following method creates a red donut with a yellow outline and lets the user draw its frame: ```csharp using System; using System.Drawing; using System.Windows.Forms; using TXTextControl; using TXTextControl.DataVisualization; using TXTextControl.Drawing; public partial class Form1 : Form { private void DrawDonut() { // A drawing control holds the shapes of one drawing TXDrawingControl drawing = new TXDrawingControl(); Shape donut = new Shape(ShapeType.Donut); donut.ShapeFill.Color = Color.Red; donut.ShapeOutline.Color = Color.Yellow; donut.ShapeOutline.Width = 200; // The shape fills the whole drawing drawing.Shapes.Add(donut, ShapeCollection.AddStyle.Fill); // The user draws the frame of the drawing with the mouse DrawingFrame frame = new DrawingFrame(drawing); textControl1.Drawings.Add(frame, FrameInsertionMode.DisplaceText); } } ``` The code works as follows: - The reference documents only the `TXDrawingControl` constructor without parameters. The sample of the blog article [Inserting Shapes and Drawing Groups](https://www.textcontrol.com/blog/2020/07/24/inserting-shapes-and-drawing-groups/) also passes the width and height of the drawing, such as `new TXDrawingControl(3000, 3000)`. - A [Shape](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-drawing/shape/llms-full.txt) gets its form from [ShapeType](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-drawing/shapetype/enumeration/llms-full.txt), whose values follow the preset shapes of Office Open XML, such as `Rectangle`, `Diamond` and `Donut`. - [ShapeFill](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-drawing/shape/shapefill-property/llms-full.txt) sets the fill color, and [ShapeOutline](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-drawing/shape/shapeoutline-property/llms-full.txt) the color and width of the outline. - [ShapeCollection.Add](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-drawing/shapecollection/add-method/llms-full.txt) with `AddStyle.Fill` makes the shape fill the whole drawing. `AddStyle.None` uses the location and size of the shape, and `MouseCreation` lets the user draw the shape inside an activated drawing. - [DrawingCollection.Add](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-datavisualization/drawingcollection/add-method/llms-full.txt) with only a [FrameInsertionMode](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/frameinsertionmode/enumeration/llms-full.txt) lets the user draw the frame with the mouse. `Add(frame, -1)` inserts it inline at the input position instead. ![A Windows Forms window with a TextControl showing a red donut shape with a yellow outline inside its drawing frame.](https://docs.textcontrol.com/assets/img/tx-text-control-dotnet-winforms/donut-shape-drawing-frame.9e1bf6c4.webp) A click on a drawing activates it, and the user edits its shapes; a click on its border selects the drawing, which can then be moved, resized and copied. [DrawingCollection.GetActivatedItem](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-datavisualization/drawingcollection/getactivateditem-method/llms-full.txt) returns the activated drawing and [DrawingFrame.Activate](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-datavisualization/drawingframe/activate-method/llms-full.txt) activates one from code. [DrawingLayoutDialog](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/drawinglayoutdialog-method/llms-full.txt) opens the layout dialog box of a selected drawing, and the [DrawingActivated](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/drawingactivated-event/llms-full.txt) event reports the activation. Text frames and drawings are part of the Enterprise and Professional editions, as [Editions and Feature Availability](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/overview/editions/llms-full.txt) shows. Drawings are saved and loaded with DOCX and the TX Text Control format. [TXDrawingCore](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-processing/images-shapes/#render-shapes-as-svg-with-txdrawingcore) creates shapes as SVG without a control. The blog article [Inserting Shapes and Drawing Groups](https://www.textcontrol.com/blog/2020/07/24/inserting-shapes-and-drawing-groups/) adds groups of shapes, and [Adding Fold Marks and Punch Marks to Documents using Drawings in C#](https://www.textcontrol.com/blog/2024/07/19/adding-fold-marks-and-punch-marks-to-documents-using-drawings-in-csharp/) places lines behind the text of a header. ### Find and Remove Frames `GetItem` with a name or an ID returns a text frame or a drawing by the [FrameBase.Name](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/framebase/name-property/llms-full.txt) or [ID](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/framebase/id-property/llms-full.txt) your code or the **Properties** group gave it, or `null`. [TextFrameCollection.Remove](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textframecollection/remove-method/llms-full.txt) and [DrawingCollection.Remove](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol-datavisualization/drawingcollection/remove-method/llms-full.txt) delete a frame. [TextControl.Frames](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/reference/txtextcontrol/textcontrol/frames-property/llms-full.txt) holds the images, text frames, charts, barcodes and drawings together. ### Next Steps - [Images](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-editor/images/llms-full.txt): insert and arrange pictures. - [Charts and Barcodes](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-editor/charts-barcodes/llms-full.txt): the other kinds of frames. - [Headers and Footers](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-editor/headers-footers/llms-full.txt): frames and drawings that appear on every page. - [Images, Text Frames, and Shapes](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-processing/images-shapes/llms-full.txt): the same objects with `ServerTextControl`. --- ## Nearby - **Previous:** [Images](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-editor/images/llms-full.txt) - **Next:** [Charts and Barcodes](https://docs.textcontrol.com/tx-text-control-dotnet-winforms/document-editor/charts-barcodes/llms-full.txt)