[Overview][Constants][Types][Classes][Procedures and functions][Index] | Reference for unit 'StdCtrls' (#lcl)

# TCustomMemo

[Properties (by Name)] [Methods (by Name)] [Events (by Name)]

The base class for multi-line text controls.

## Declaration

Source position: stdctrls.pp line 902

`type TCustomMemo = class(TCustomEdit)`
`protected`
`class procedure WSRegisterClass; override;` |  | Registers this component class with the current WidgetSet.
`procedure CreateParams(); override;` |  | Updates creation flags used to create the handle for the control.
`procedure InitializeWnd; override;` |  | Copies existing string values from the widgetset class.
`procedure FinalizeWnd; override;` |  | Maintains resources in the class instance when the handle for the control is destroyed or re-created.
`function RealGetText; override;` |  | Returns the textual content stored in Lines as a single String value.
`procedure RealSetText(); override;` |  | Replaces the value in Lines.Text.
`function GetCachedText(); override;` |  | Returns the cached Text property (FCaption).
`function GetCaretPos; override;` |  | Get the value for the CaretPos property.
`procedure KeyUpAfterInterface(); override;` |  | Handles Key Up events forwarded from the LCL interface.
`procedure SetCaretPos(); override;` |  | Sets the position for the editing cursor or caret to the specified location.
`procedure SetLines();` |  | Sets the value for the Lines property.
`procedure SetWantReturns();` |  | Sets the value for the WantReturns property.
`procedure SetWantTabs();` |  | Sets the value for the WantTabs property.
`procedure SetWordWrap();` |  | Sets the value for the WordWrap property.
`procedure SetScrollBars();` |  | Sets the value for the ScrollBars property.
`procedure Loaded; override;` |  | Performs actions needed when the component has been loaded using the LCL streaming mechanism.
`procedure CMWantSpecialKey(); message;` |  | Handles control messages for Return and Tab keys when enabled in the control.
`procedure WMGetDlgCode(); message;` |  | Handles Tab, Return, and Escape characters in control messages.
`class function GetControlClassDefaultSize; override;` |  | Gets the default size used for new instances of the class.
`procedure UTF8KeyPress(); override;` |  | Implements the handler for UTF8 key press events in the control.
`function CanShowEmulatedTextHint; override;` |  | Indicates if an emulated TextHint can be displayed for the control.
`public`
`constructor Create(); override;` |  | Constructor for the class instance.
`destructor Destroy; override;` |  | Destructor for the class instance.
`procedure Append();` |  | Appends the specified text to the Lines in the control.
`procedure ScrollBy(); override;` |  | Scrolls the visible area in the control by the specified amounts.
`property Lines: TStrings; [rw]` |  | Contains the individual lines of text in the multi-line edit control.
`property HorzScrollBar: TMemoScrollbar; [rw]` |  | The horizontal scrollbar for the control.
`property VertScrollBar: TMemoScrollbar; [rw]` |  | The vertical scrollbar for the control.
`property ScrollBars: TScrollStyle; [rw]` |  | Defines the vertical and/or horizontal scrollbars used in the control.
`property WantReturns: Boolean; [rw]` |  | Allows the user to insert Return characters (line breaks) into the text.
`property WantTabs: Boolean; [rw]` |  | Allows Tab characters to be entered into the text.
`property WordWrap: Boolean; [rw]` |  | Allows long lines (paragraphs) to wrap into multiple display lines.
`end;`

## Inheritance

`TCustomMemo` |  | The base class for multi-line text controls.
`TCustomEdit` |  | The base class for controls presenting editable text.
`TWinControl` |  | Implements a windowed control which can contain other child controls.
`TControl` |  | The base class for visible controls.
`TLCLComponent` |  | The base class for LCL components which have an associated widget.
`TComponent`
?
`TObject`

## Description

TCustomMemo is a TCustomEdit descendant which implements the base class used for a multi-line edit control. TCustomMemo extends TCustomEdit with additional properties and methods needed for the control. Overridden methods are provided to create and initialize the control using style flags needed for the widgetset class.

The textual values in the multi-line control can be accessed using the Lines property. An individual line of text can be accessed by its ordinal position in the list of values. For example:

    // var sContent: String;
    sContent := AMemo.Lines[2];

This provides access to the third value in List (index positions are zero-based).

The values for all of the text in Lines can be retrieved as a single String using the Text property in the TStrings class instance. Each line of text is separated by the LineEnding character sequence for the host platform or operating system. For example:

    // var sContent: String; ...
    sContent := AMemo.Lines.Text;

Please note: There is a difference in TCustomMemo / TMemo between the Text and Lines properties. Text is actually the Caption for the control as inherited from TControl. Lines is the multi-line TStrings instance specific to the memo control. Setting the control value using Text does NOT cause the Modified property to be updated. Setting the value using the Lines property does cause the Modified property to be updated.

This is important if an OnChange event handler is used to detect changes to the value in the control, and you need to identify whether the change was performed in program code. You can identify a programmatic change by manipulating the value in Modified.

For changes in program code, set Modified to False before setting the value using the Text property. If Modified is False when OnChange is signalled, the change occurred in program code. Modified can be set as desired in your program code after the value is assigned to Text. For example:

    // use Modified and Text to track program changes
    procedure TForm1.Button1Click(Sender: TObject);
    begin
      Memo1.Modified := False;
      Memo1.Text := 'Whiskey' + LineEnding + 'Tango' + LineEnding + 'Foxtrot';
      Memo1.Modified := True;
    end;

    procedure TForm1.Memo1Change(Sender: TObject);
    begin
      if not TCustomMemo(Sender).Modified then
        StaticText1.Caption := 'Memo changed in code'
      else
        StaticText1.Caption := 'Memo changed by user';
    end;

Changes entered by the user are applied when methods update the Lines property in the control. As a result, Modified is set to True. If Modified is True in OnChange, the change was triggered by user interaction with the control.

The value in Modified is retained when the control gains or loses focus whether by keyboard navigation or by using the mouse.

The text displayed in the control uses the attributes defined in the Font property. No capabilities are provided for formatting individual characters, words, or lines in the content for the control.

Both horizontal and vertical scrollbars can be used in the control. Use the ScrollBar property to define the scrollbars displayed for the control. It can be used to enable automatic scrollbars which are only displayed when the content for the control does not fit within its bounds.

Use the Append method to add a line of text to the values in Lines.

Use the WantTabs and WantReturns properties to determine whether the corresponding keys are captured and stored in Lines. This affects the way control messages are applied to the control.

Use WordWrap to indicate if the control should automatically wrap a line of text longer than the visible area for the control.

Applications should not create instances of TCustomMemo; use TMemo instead.

## See also

TCustomMemo.ScrollBars |  | Defines the vertical and/or horizontal scrollbars used in the control.
TCustomMemo.HorzScrollBar |  | The horizontal scrollbar for the control.
TCustomMemo.VertScrollBar |  | The vertical scrollbar for the control.
TCustomMemo.Lines |  | Contains the individual lines of text in the multi-line edit control.
TCustomMemo.WordWrap |  | Allows long lines (paragraphs) to wrap into multiple display lines.
TCustomMemo.WantTabs |  | Allows Tab characters to be entered into the text.
TCustomMemo.WantReturns |  | Allows the user to insert Return characters (line breaks) into the text.
TCustomEdit.Modified |  | True when the value in Text has been changed using the keyboard.
TCustomEdit.Text |  | The text displayed and edited for the control.
TCustomEdit.OnChange |  | Event handler signalled when the text for the control is changed.
TCustomEdit |  | The base class for controls presenting editable text.
TMemo |  | Control used to display and edit multi-line text.
TControl.Font |  | The font to be used for text display in this control.