TCustomMemo

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

The base class for multi-line text controls.

Declaration

Source position: stdctrls.pp line 901

Inheritance

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