System.TObject.Free

• Up to Parent: TObject

Delphi

procedure Free;

C++

void __fastcall Free();

Properties

Type	Visibility	Source	Unit	Parent
procedure function	public	System.pas systobj.h	System	TObject

Description

Destroys an object and frees its associated memory, if necessary.

Use Free to destroy an object. Free automatically calls the destructor if the object reference is not nil. Any object instantiated at run time that does not have an owner should be destroyed by a call to Free, so that it can be properly disposed of and its memory released. Unlike Destroy, Free is successful even if the object is nil; if the object was never initialized, Free would not result in an error.

When you call Free for a component, it calls Free for all components that it owns—that is, all components in its component list. Since a form owns all the controls and other components that are created on it in design mode, those components are automatically freed when the form is freed. By default, all forms are owned by the Application object; when the application terminates, it frees the Application object, which frees all forms. For objects that are not components, or for components created with a nil owner, be sure to call Free after you are finished with them; otherwise the allocated memory will not be usable until after the application terminates.

Warning: Never explicitly free a component within one of its own event handlers or the event handler of a component it owns or contains. For example, do not free a button or the form that owns the button in its OnClick event handler.

To free a form, call its Release method, which destroys the form and releases the memory allocated for it after all its event handlers and those of the components it contains are through executing.

Note: In C++ code, do not use Free to destroy an object. Use the delete keyword.

See Also

• Destroy

• Release

• Owner

• FreeAndNil

Code Examples

• TMenuItems (Delphi)