TCustomMemo class

In unit StdCtrls

The base class for multi-line text controls.

Declaration

pascal

TCustomMemo = class(TCustomEdit)

Inheritance

Descends from it: TDBMemo TMemo

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.

Properties

`Lines`	public	Contains the individual lines of text in the multi-line edit control.
`HorzScrollBar`	public	The horizontal scrollbar for the control.
`VertScrollBar`	public	The vertical scrollbar for the control.
`ScrollBars`	public	Defines the vertical and/or horizontal scrollbars used in the control.
`WantReturns`	public	Allows the user to insert Return characters (line breaks) into the text.
`WantTabs`	public	Allows Tab characters to be entered into the text.
`WordWrap`	public	Allows long lines (paragraphs) to wrap into multiple display lines.

Methods

`WSRegisterClass`	protected	Registers this component class with the current WidgetSet.
`CreateParams`	protected	Updates creation flags used to create the handle for the control.
`InitializeWnd`	protected	Copies existing string values from the widgetset class.
`FinalizeWnd`	protected	Maintains resources in the class instance when the handle for the control is destroyed or re-created.
`RealGetText`	protected	Returns the textual content stored in Lines as a single String value.
`RealSetText`	protected	Replaces the value in Lines.Text.
`GetCachedText`	protected	Returns the cached Text property (FCaption).
`GetCaretPos`	protected	Get the value for the CaretPos property.
`KeyUpAfterInterface`	protected	Handles Key Up events forwarded from the LCL interface.
`SetCaretPos`	protected	Sets the position for the editing cursor or caret to the specified location.
`SetLines`	protected	Sets the value for the Lines property.
`SetWantReturns`	protected	Sets the value for the WantReturns property.
`SetWantTabs`	protected	Sets the value for the WantTabs property.
`SetWordWrap`	protected	Sets the value for the WordWrap property.
`SetScrollBars`	protected	Sets the value for the ScrollBars property.
`Loaded`	protected	Performs actions needed when the component has been loaded using the LCL streaming mechanism.
`CMWantSpecialKey`	protected	Handles control messages for Return and Tab keys when enabled in the control.
`WMGetDlgCode`	protected	Handles Tab, Return, and Escape characters in control messages.
`GetControlClassDefaultSize`	protected	Gets the default size used for new instances of the class.
`UTF8KeyPress`	protected	Implements the handler for UTF8 key press events in the control.
`CanShowEmulatedTextHint`	protected	Indicates if an emulated TextHint can be displayed for the control.
`Create`	public	Constructor for the class instance.
`Destroy`	public	Destructor for the class instance.
`Append`	public	Appends the specified text to the Lines in the control.
`ScrollBy`	public	Scrolls the visible area in the control by the specified amounts.