Object#

Qualified name: delphivcl.Object

class Object#

Bases: object

TObject is the ultimate ancestor of all objects and components. TObject encapsulates fundamental behavior common to objects by introducing methods that:

Create, maintain, and destroy instances of the object by allocating, initializing, and freeing required memory. Respond when object instances are created or destroyed. Return class-type and instance information on an object and runtime type information (RTTI) about its published properties. Support message handling. Support interfaces implemented by the object. Use TObject as an immediate base class when declaring simple objects that do not need to persist (are not saved and reloaded) and that do not need to be assigned to other objects. Much of the capability of objects is established by methods that TObject introduces. Many of these methods are used internally by IDEs and are not intended for users to call directly. Others are overridden in descendant objects that have more complex behavior. Although TObject is the based object of a component framework, not all objects are components. All component classes descend from TComponent.

Note: TObject is never directly instantiated. Although it does not use programming language features that prevent instantiation, TObject is an abstract class.

Methods

`AfterConstruction`	Responds after the last constructor has executed.
`BeforeDestruction`	Responds before the first destructor executes.
`ClassInfo`	Returns a pointer to the run-time type information (RTTI) table for the object type.
`ClassName`	Returns a string indicating the type of the object instance (as opposed to the type of the variable passed as an argument).
`ClassNameIs`	Determines whether an object is of a specific type.
`ClassParent`	Returns the type of the immediate ancestor of a class.
`ClassType`	Returns the class reference for the object's class.
`CleanupInstance`	Performs finalization on long strings, variants, and interface variables within a class.
`Create`	Constructs an object and initializes its data before the object is first used.
`DefaultHandler`	Provides the interface for a method that processes message records.
`Destroy`	Disposes of an object instance.
`Dispatch`	Calls message-handling methods for the object, based on the contents of the Message parameter.
`DisposeOf`	DisposeOf forces the execution of the destructor code in an object.
`Equals`	Checks whether the current instance and the Obj parameter are equal.
`FieldAddress`	Returns the address of a published object field.
`Free`	Destroys an object and frees its associated memory, if necessary.
`FreeInstance`	Deallocates memory allocated by a previous call to the NewInstance method.
`GetHashCode`	Returns an integer containing the hash code.
`GetInterface`	Retrieves a specified interface.
`GetInterfaceEntry`	Returns the entry for a specific interface implemented in a class.
`GetInterfaceTable`	Returns a pointer to a structure containing all of the interfaces implemented by a given class.
`InheritsFrom`	Determines the relationship of two object types.
`InitInstance`	Initializes a newly allocated object instance to all zeros and initializes the instance's virtual method table pointer.
`InstanceSize`	Returns the size in bytes of each instance of the object type.
`MethodAddress`	Returns the address of a class method by name.
`MethodName`	Returns the name of a class method by address.
`NewInstance`	Allocates memory for an instance of an object type and returns a pointer to that new instance.
`QualifiedClassName`	Returns the qualified name of the class.
`SafeCallException`	Handles exceptions in methods declared using the safecall calling convention.
`SetProps`	Sets several properties in one call
`ToList`	If the object is a container (TStrings, TComponent...), it returns the content of the sequence as a Python list object.
`ToString`	Returns a string containing the class name.
`ToTuple`	If the object is a container (TStrings, TComponent...), it returns the content of the sequence as a Python tuple object.
`UnitName`	Returns the name of the unit where the class is defined.
`UnitScope`	Returns the class's unit scope.

AfterConstruction()#: Responds after the last constructor has executed. AfterConstruction is called automatically after the object’s last constructor has executed. Do not call it explicitly in your applications. The AfterConstruction method implemented in TObject does nothing. Override this method when creating a class that performs an action after the object is created. For example, TCustomForm overrides AfterConstruction to generate an OnCreate event.

BeforeDestruction()#

Responds before the first destructor executes. BeforeDestruction is called automatically before the object’s first destructor executes. Do not call it explicitly in your applications. The BeforeDestruction method implemented in TObject does nothing. Override this method when creating a class that performs an action before the object is destroyed. For example, TCustomForm overrides BeforeDestruction to generate an OnDestroy event.

Note: BeforeDestruction is not called when the object is destroyed before it is fully constructed. That is, if the object’s constructor raises an exception, the destructor is called to dispose of the object, but BeforeDestruction is not called.

ClassInfo()#: Returns a pointer to the run-time type information (RTTI) table for the object type. ClassInfo provides access to the RTTI table for a given object type. Some classes do not provide run-time type information. For these classes, ClassInfo returns nil (Delphi) or NULL (C++). All classes descended from TPersistent do provide run-time type information.

ClassName()#

Returns a string indicating the type of the object instance (as opposed to the type of the variable passed as an argument). Use ClassName to obtain the class name from an object instance or class reference. This is useful for differentiating object instances that are assigned to a variable that has the type of an ancestor class.

Note: In C++ code, call ClassName as a method to obtain an object’s class name. Use the global static function to obtain the class name from a metaclass object.

ClassNameIs(Name: string) → Boolean#

Determines whether an object is of a specific type. ClassNameIs determines whether an object instance or class reference has a class name that matches a specified string. This is useful to query objects across modules or shared libraries.

Note: In C++ code, call ClassNameIs as a method to compare an object’s class name. Use the global static function to compare the class name from a metaclass object.

ClassParent()#

Returns the type of the immediate ancestor of a class. ClassParent returns the name of the parent class for an object instance or class reference. For TObject, ClassParent returns nil (Delphi) or NULL (C++). Avoid using ClassParent in application code.

Note: In Delphi code, use the is or as operators instead of ClassParent. Note: In C++ code, use a dynamic cast or the InheritsFrom method instead of ClassParent.

ClassType()#

Returns the class reference for the object’s class.

Note: ClassType dynamically determines the type of an object and returns its class reference, or metaclass. Avoid using ClassType in application code.

Note: In Delphi code, use the is or as operators instead of ClassType. Note: In C++ code, use a dynamic cast or the InheritsFrom method instead of ClassType.

CleanupInstance()#: Performs finalization on long strings, variants, and interface variables within a class. Do not call CleanupInstance directly. CleanupInstance is called automatically when the object instance is destroyed. CleanupInstance releases all long strings and variants. It sets long strings to empty and variants to Unassigned.

Create()#

Constructs an object and initializes its data before the object is first used. Create constructs an object. The purpose, size, and behavior of objects differ greatly. The Create constructor defined by TObject allocates memory but does not initialize data. Descendant objects usually define a constructor that creates the particular kind of object and initializes its data.

Note: If an exception escapes from a constructor, the object’s destructor is called to clean up the failed instance.

DefaultHandler(Message)#

Provides the interface for a method that processes message records. DefaultHandler is called by Dispatch when it cannot find a method for a particular message. DefaultHandler provides message handling for all messages for which an object does not have specific handlers. Descendant classes that process messages override DefaultHandler according to the types of messages they handle.

Note: In a Delphi message-handling method, calling inherited results in a call to the ancestor’s DefaultHandler method only if that ancestor does not specify a message method for the particular message being handled. Otherwise, calling inherited results in a call to the specific handler for that type of message.

Destroy()#

Disposes of an object instance. Do not call Destroy directly. Call Free instead. Free verifies that the object reference is not nil before calling Destroy. The Destroy method defined by TObject deallocates memory. Descendent objects usually define a destructor that is customized for that particular kind of object. When declaring a Destroy method in a descendant, always add the override directive to the declaration and call the inherited Destroy as the last statement in the overriding method. Because Destroy is a virtual method, overriding it ensures that the proper inherited behavior occurs.

Note: If an exception escapes from the constructor, the destructor is called to destroy the partially constructed object instance that failed to initialize completely. Therefore, destructors should check that allocated resources such as handles were actually allocated before trying to release them, since their value might be zero. Destroy should be implemented so that it calls Free on all subobjects created within the object’s constructor (that is, allocated by the constructor). Unlike Destroy, Free provides a safeguard when destroying objects that are nil.

Dispatch(Message)#: Calls message-handling methods for the object, based on the contents of the Message parameter. Call Dispatch to automatically pass messages to the appropriate message handler. Dispatch determines whether a message is in the list of message handlers declared for the object. If the object does not handle the message, Dispatch then examines the message-handler list of the ancestor class, and continues checking ancestors until it either finds a specific handler or runs out of ancestors, in which case it calls DefaultHandler. The only assumption Dispatch makes about the data in Message is that the first two bytes contain a message ID?that is, an integer that determines which message handler Dispatch calls. Although any kind of data can be passed to Dispatch, most TObject descendants expect a message record such as TMessage or a specific data structure type.

DisposeOf()#

DisposeOf forces the execution of the destructor code in an object. It was an artifact from previous versions when the Delphi Mobile compilers supported Automatic Reference Counting. In current versions of Delphi, DisposeOf is used as a wrapper that invokes TObject.Free.

type

TMySimpleClass = class private

stringMember: String; constructor Create(const Text: String); destructor Destroy;

end;

constructor TMySimpleClass.Create(const Text: String); begin

stringMember := Text;

end;

destructor TMySimpleClass.Destroy; begin

// this will be executed on calling the DisposeOf method.

end;

var

myObject: TMySimpleClass;

begin

myObject := TMySimpleClass.Create(‘This is a code snippet indicating the usage of the DisposeOf method’); try

// Use ‘myObject’ here

finally: myObject.DisposeOf;

end;

end.

Equals(Obj: Object) → Boolean#

Checks whether the current instance and the Obj parameter are equal. The function has one Obj parameter of the TObject type. By default, the Equals method shows whether the addresses corresponding to the current object and the Obj object are identical. The method returns a boolean value that represents the equality between the two addresses.

Note: Equals is supposed to be overridden in user-derived classes, to provide consumer objects with an equality determining function. For example, in the FMX.Types.TBounds class, Equals also returns True if the Rect properties of the current object and of the Obj object are equal. In the FMX.StdActns.TBaseValueRange class, Equals also returns True if all the properties of the current object and of the Obj object are equal.

FieldAddress(Name: ShortString) → Pointer#: Returns the address of a published object field. FieldAddress is used internally by the component streaming system to access a specified published field of an object. FieldAddress returns a pointer to the field, if it exists. If the object has no published field by that name, FieldAddress returns nil (Delphi) or NULL (C++). Programs should access and manipulate fields by using properties instead of FieldAddress. Returns the address of a published object field. FieldAddress is used internally by the component streaming system to access a specified published field of an object. FieldAddress returns a pointer to the field, if it exists. If the object has no published field by that name, FieldAddress returns nil (Delphi) or NULL (C++). Programs should access and manipulate fields by using properties instead of FieldAddress.

Free()#

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.

FreeInstance()#: Deallocates memory allocated by a previous call to the NewInstance method. All destructors call FreeInstance automatically to deallocate memory that was allocated by overriding NewInstance. Do not call FreeInstance directly. FreeInstance should be overridden if NewInstance was overridden to change the way the object’s instance data was allocated. Like NewInstance, FreeInstance uses the value returned from InstanceSize to deallocate the object’s memory.

GetHashCode()#

Returns an integer containing the hash code. By default, calling GetHashCode on an object returns an integer representing the virtual address at which the object is stored.

Notes: GetHashCode is supposed to be overridden in user-derived classes, to provide consumer objects with an integer hash code representation. The sign of the hash code depends on the address of the particular object instance. Negative hash code can appear for object instances that reside at higher memory locations.

GetInterface(IID: GUID, Obj) → Boolean#

Retrieves a specified interface. GetInterface retrieves the interface designated by a GUID or type name. The basic implementation of GetInterface uses the GUID specified in the IID parameter. If the specified interface is supported by the class, it is returned in the Obj parameter, and GetInterface has a return value of True. Otherwise, Obj contains nil (Delphi) or NULL (C++), and GetInterface returns False.

Note: In Delphi code, IID can be an interface name. The compiler automatically translates this name into the corresponding GUID. Note: In C++ code, use the templated version of GetInterface to obtain an interface from a DelphiInterface object. GetInterface is equivalent to the as operator (Delphi) and dynamic casts (C++), except that GetInterface does not raise an exception if the interface is not supported.

GetInterfaceEntry(IID: GUID) → PInterfaceEntry#

Returns the entry for a specific interface implemented in a class. GetInterfaceEntry returns the class entry for the interface specified by the IID parameter.

Note: In Delphi Code, IID can be an interface name. The compiler replaces this name with the actual GUID. Note: COM objects can use GetInterfaceEntry to automate dispatch calls to a dual-IDispatch interface.

GetInterfaceTable()#: Returns a pointer to a structure containing all of the interfaces implemented by a given class. GetInterfaceTable returns the interface entries for the class. This list contains only interfaces implemented by this class, not its ancestors. To find the ancestor list, iteratively call ClassParent and then call GetInterfaceTable on the value it returns. To find the entry for a specific interface, use the GetInterfaceEntry method instead.

InheritsFrom(AClass: Class) → Boolean#

Determines the relationship of two object types. Use InheritsFrom to determine whether a particular class type or object is an instance of a class or one of its descendants. InheritsFrom returns True if the object type specified in the aClass parameter is an ancestor of the object type or the type of the object itself. Otherwise, it returns False.

Note: InheritsFrom is similar to the Delphi is operator, but applies to class references. Note: In C++ code, a nonstatic version of InheritsFrom is provided. This call is useful in determining whether a descendant class method or property can be used, given a variable of a base class. For example, use InheritsFrom to determine whether the Sender parameter in an event handler is of a particular class type or one of its descendants.

InitInstance(Instance: Pointer) → Object#: Initializes a newly allocated object instance to all zeros and initializes the instance’s virtual method table pointer. You should not call InitInstance directly. InitInstance is called by NewInstance when an object is created. When overriding NewInstance, be sure to call InitInstance as the last statement. InitInstance is not virtual, so you cannot override it. Instead, initialize any data for an object in the constructor.

InstanceSize()#: Returns the size in bytes of each instance of the object type. InstanceSize indicates how many bytes of memory are required for a class’s instance data. InstanceSize is called from methods that allocate and deallocate memory. InstanceSize is not a virtual method, so it cannot be overridden. InstanceSize should be called only when implementing a custom version of NewInstance.

MethodAddress(Name: ShortString) → Pointer#

Returns the address of a class method by name.

Note: You can use MethodAddress for published methods only. There are situations when it is useful to invoke an object method without hard coding the method name in advance. Call MethodAddress to dynamically retrieve the address of such a method by specifying the method Name as a string. An easy way to invoke the method is to define a procedure or function data type, such as:

type TProc = procedure of object;

Assign the object name and the MethodAddress method to a TMethod variable, such as:

MethodVar.Data?:= Pointer(ObjectInstanceName); MethodVar.Code?:= ObjectInstanceName.MethodAddress(‘MethodNameString’);

Pass this in a call to a variable of the procedure or function type:

Proc?:= TProc(MethodVar); Proc; Returns the address of a class method by name.

type TProc = procedure of object;

Assign the object name and the MethodAddress method to a TMethod variable, such as:

MethodVar.Data?:= Pointer(ObjectInstanceName); MethodVar.Code?:= ObjectInstanceName.MethodAddress(‘MethodNameString’);

Pass this in a call to a variable of the procedure or function type:

Proc?:= TProc(MethodVar); Proc;

MethodName(Address: Pointer) → string#: Returns the name of a class method by address. There are situations when it is useful to invoke an object method without hard coding the method name in advance. Call MethodAddress to dynamically retrieve the address of such a method by specifying the method name as a string. MethodName is the opposite of this process–by supplying an Address method, the name of the method is returned as a string.

NewInstance()#

Allocates memory for an instance of an object type and returns a pointer to that new instance. All constructors call NewInstance automatically. NewInstance calls InstanceSize to determine how much memory containing a particular instance to allocate from the heap. Do not call NewInstance directly. Override NewInstance only for special memory allocation requirements. For example, when allocating a large number of identical objects that all need to be in memory at the same time, you can allocate a single block of memory for the entire group, then override NewInstance to use part of that larger block for each instance. If you override NewInstance to allocate memory, you may need to override FreeInstance to deallocate the memory.

Note: By default, NewInstance calls InitInstance.

QualifiedClassName()#

Returns the qualified name of the class. QualifiedClassName returns the class’s unit scope concatenated with the class name. Example:

uses: SysUtils, SyncObjs;
begin: Writeln(TEvent.QualifiedClassName); // displays System.SyncObjs.TEvent

SafeCallException(ExceptObject: Object, ExceptAddr: Pointer) → HRESUL#: Handles exceptions in methods declared using the safecall calling convention. SafeCallException handles exceptions in methods that use the safecall calling convention. Some classes that implement interfaces override this method to handle possible errors. As implemented in TObject, SafeCallException simply returns E_UNEXPECTED. This is the appropriate response for classes that do no support interfaces.

SetProps(prop1=val1, prop2=val2...)#: Sets several properties in one call

ToList()#: If the object is a container (TStrings, TComponent…), it returns the content of the sequence as a Python list object.

ToString()#

Returns a string containing the class name. By default, the ToString returns a string containing the class name of the instance that is being called. For example, calling ToString on a TButton instance returns a string containing “TButton”.

Note: ToString is intended to be overridden in user-derived classes, to provide consumer objects with a string representation.

ToTuple()#: If the object is a container (TStrings, TComponent…), it returns the content of the sequence as a Python tuple object.

UnitName()#: Returns the name of the unit where the class is defined. UnitName can be used to obtain the unit where a specific class is defined. For example, calling UnitName on TButton returns the Vcl.StdCtrls string.

UnitScope()#

Returns the class’s unit scope. The class’s unit scope is currently equivalent with the class’s unit name.

uses: SysUtils, SyncObjs;
begin: Writeln(TEvent.UnitScope); // displays System.SyncObjs // …