Component#

Qualified name: delphivcl.Component

class Component#

Bases: Persistent

TComponent is the common ancestor of all component classes. TComponent is the base class for all components. Components are persistent objects that have the following capabilities:

IDE integration. The ability to appear on an IDE palette and be manipulated in a Form Designer. Ownership. The ability to manage other components. If component A owns component B, then A is responsible for destroying B when A is destroyed. Streaming and filing. Enhancements of the persistence features inherited from TPersistent. COM support. Components can be converted into ActiveX controls or other COM objects using wizards provided with Windows products. Components can serve as wrappers for COM objects. Note: COM features are present in all implementations of TComponent, including those provided for compatibility with OS X. However, COM features are Windows only and cannot be used in multi-device (cross-platform) applications. TComponent does not provide any user interface or display features. These features are provided by two classes that directly descend from TComponent:

TControl, in the FMX.Types unit, is the base class for visual components in applications built with the FireMonkey (FMX) framework. TControl, in the Vcl.Controls unit, is the base class for visual components in Windows-only (VCL) applications. Note: Only the FMX.Types unit and other FireMonkey-specific units can be used with OS X applications. That is, you cannot use VCL units in multi-device applications. Components that can be visible at run time are sometimes called visual components. Other components, which are never visible at run time, are sometimes called non-visual components. However it is more common to refer to visual components as controls and non-visual components simply as components. Do not create instances of TComponent. Use TComponent as a base class when declaring non-visual components that can appear on the component palette and be used in the Form Designer. Properties and methods of TComponent provide basic behavior that descendant classes inherit as well as behavior that components can override to customize their behavior.

Methods

`BeforeDestruction`	Performs any necessary actions before the first destructor is called.
`BeginInvoke`	Performs an asynchronous call to the method specified by either AProc or AFunc.
`BindMethodsToEvents`	Connects methods to component events if they are named using the following pattern: Prefix_ComponentName_EventName.
`Create`	Allocates memory and constructs a safely initialized instance of a component.
`Destroy`	Disposes of the component and its owned components.
`DestroyComponents`	Destroys all owned components.
`Destroying`	Indicates that the component and its owned components are about to be destroyed.
`EndFunctionInvoke`	Blocks the caller until the specified ASyncResult completes.
`EndInvoke`	Blocks the caller until the specified ASyncResult completes.
`ExecuteAction`	Executes an action.
`FindComponent`	Indicates whether a given component is owned by the component.
`FreeNotification`	Ensures that AComponent is notified that the component is going to be destroyed.
`FreeOnRelease`	Frees the interface reference for components that were created from COM classes.
`GetEnumerator`	Returns a TComponent enumerator.
`GetNamePath`	Returns a string used by the Object Inspector.
`GetParentComponent`	Returns the containing component.
`HasParent`	Verifies whether the component has a parent.
`InsertComponent`	Establishes the component as the owner of a specified component.
`IsImplementorOf`	Indicates whether the component implements a specified interface.
`ReferenceInterface`	Establishes or removes internal links that cause this component to be notified when the implementer of a specified interface is destroyed.
`RemoveComponent`	Removes a specified component specified from the component's Components list.
`RemoveFreeNotification`	Disables the destruction notification that was enabled by FreeNotification.
`SafeCallException`	Handles exceptions in methods declared using the safecall calling convention.
`SetSubComponent`	Identifies whether the component is a subcomponent.
`UpdateAction`	Updates the state of an action.

Attributes

`ClassName`	Returns the TObject.ClassName
`ComObject`	Specifies the interface reference implemented by the component.
`ComponentCount`	Indicates the number of components owned by the component.
`ComponentIndex`	Indicates the position of the component in its owner's Components property array.
`ComponentState`	Describes the current state of the component, indicating when a component needs to avoid certain actions.
`ComponentStyle`	Governs the behavior of the component.
`Components`	<Delphi indexed property Components of type TComponent at 21141642500>
`DesignInfo`	Contains information used by the Form designer.
`Name`	Specifies the name of the component as referenced in code.
`Observers`	Indicates the TObservers object added to the TComponent.
`Owner`	Indicates the component that is responsible for streaming and freeing this component.
`Tag`	Stores a NativeInt integral value as a part of a component.
`VCLComObject`	Represents information used internally by components that support COM.

BeforeDestruction()#: Performs any necessary actions before the first destructor is called. BeforeDestruction is called automatically immediately before the component’s first destructor executes. Do not call it explicitly in your applications. As implemented in TComponent, BeforeDestruction checks whether the Destroying method has been called, and if not, calls it. Descendants that override this method to perform other actions before a component is destroyed should call the inherited method first to ensure that this check takes place.

BeginInvoke(AProc: Proc, AContext: Object) → IAsyncResult#: Performs an asynchronous call to the method specified by either AProc or AFunc. The AContext parameter specifies the context where the method executes in. This context corresponds to the main thread. In case of a Tcontrol descendant, it executes in the context of the thread on which the closest window handle was created. BeginInvoke returns the results of the asynchronous execution in an interface IAsyncResult used as a return type. Performs an asynchronous call to the method specified by either AProc or AFunc. The AContext parameter specifies the context where the method executes in. This context corresponds to the main thread. In case of a Tcontrol descendant, it executes in the context of the thread on which the closest window handle was created. BeginInvoke returns the results of the asynchronous execution in an interface IAsyncResult used as a return type. Performs an asynchronous call to the method specified by either AProc or AFunc. The AContext parameter specifies the context where the method executes in. This context corresponds to the main thread. In case of a Tcontrol descendant, it executes in the context of the thread on which the closest window handle was created. BeginInvoke returns the results of the asynchronous execution in an interface IAsyncResult used as a return type. Performs an asynchronous call to the method specified by either AProc or AFunc. The AContext parameter specifies the context where the method executes in. This context corresponds to the main thread. In case of a Tcontrol descendant, it executes in the context of the thread on which the closest window handle was created. BeginInvoke returns the results of the asynchronous execution in an interface IAsyncResult used as a return type. Performs an asynchronous call to the method specified by either AProc or AFunc. The AContext parameter specifies the context where the method executes in. This context corresponds to the main thread. In case of a Tcontrol descendant, it executes in the context of the thread on which the closest window handle was created. BeginInvoke returns the results of the asynchronous execution in an interface IAsyncResult used as a return type. Performs an asynchronous call to the method specified by either AProc or AFunc. The AContext parameter specifies the context where the method executes in. This context corresponds to the main thread. In case of a Tcontrol descendant, it executes in the context of the thread on which the closest window handle was created. BeginInvoke returns the results of the asynchronous execution in an interface IAsyncResult used as a return type. Performs an asynchronous call to the method specified by either AProc or AFunc. The AContext parameter specifies the context where the method executes in. This context corresponds to the main thread. In case of a Tcontrol descendant, it executes in the context of the thread on which the closest window handle was created. BeginInvoke returns the results of the asynchronous execution in an interface IAsyncResult used as a return type. Performs an asynchronous call to the method specified by either AProc or AFunc. The AContext parameter specifies the context where the method executes in. This context corresponds to the main thread. In case of a Tcontrol descendant, it executes in the context of the thread on which the closest window handle was created. BeginInvoke returns the results of the asynchronous execution in an interface IAsyncResult used as a return type.

BindMethodsToEvents(prefix)#: Connects methods to component events if they are named using the following pattern: Prefix_ComponentName_EventName. Example: def handle_button1_OnClick(Sender): pass The function returns a list of tuples. Each tuple contains the name of the component, the name of the event and the method object assigned to the event. Note that the prefix parameter is optional and will default to “handle_”.

ComObject#: Specifies the interface reference implemented by the component. Use ComObject to assign a COM interface implemented by a component to an interface reference. This property is used by components that support COM interfaces. If the component is not a wrapper for a COM component, trying to read ComObject causes TComponent to raise an EComponentError exception.

ComponentCount#: Indicates the number of components owned by the component. Use the ComponentCount property to determine the number of components owned by a component, for example, when iterating through the components list to perform an action on all owned components. The ComponentCount property equals the number of items in the components list. This value is one more than the highest Components index, because the first components index is 0.

ComponentIndex#

Indicates the position of the component in its owner’s Components property array. Use ComponentIndex when iterating through the Components list of the component’s owner to perform an action on owned components. It can be used in conjunction with ComponentCount. ComponentIndex is used internally for iterative assignment procedures.

Note: The first component in the list has a ComponentIndex value of 0, the second has a value of 1, and so on. Therefore, when using ComponentIndex with ComponentCount, note that ComponentCount is always 1 more than the highest Components index.

ComponentState#: Describes the current state of the component, indicating when a component needs to avoid certain actions. ComponentState is a set of constants defined in the TComponentState type. Components use the ComponentState property to detect states in which certain kinds of actions are allowed or disallowed. For example, if a component needs to avoid certain behaviors at design time that it performs at run time, it can check for the csDesigning flag. ComponentState is read-only and its flags are set automatically when appropriate.

ComponentStyle#: Governs the behavior of the component. ComponentStyle governs how the component interacts with the streaming system and the Object Inspector. ComponentStyle is a read-only property. Typically, the value of the various component style flags are part of a component definition, specified in a component constructor. The one exception to this is the csSubComponent style, which can be set by calling the SetSubComponent method.

Components#: <Delphi indexed property Components of type TComponent at 21141642500>

Create(AOwner: Component)#

Allocates memory and constructs a safely initialized instance of a component. All objects have a Create method that constructs the object. TComponent redefines Create so that, for components, Create also:

Establishes the relationship of a component and its Owner, as indicated by the AOwner parameter. Sets the ComponentStyle property to csInheritable, meaning that the component can be inherited by a descendent form type. It is not necessary to explicitly create components added in the Form Designer. These components are created automatically when the application is run, and they are destroyed when the application is closed. For components created programmatically, that is, not created in the Form Designer, call Create and pass in an owner component as the AOwner parameter. The owner disposes of the component when it is destroyed. If the component is not owned, then use Free when it needs to be destroyed.

Tip: When passing in Self as the Owner parameter, consider what Self references. If a component creates another component in one of its methods, then Self refers to the first component and not the component being created, which is then owned by the first component. Note: The TComponent constructor is virtual in part to allow polymorphic instantiation of class references. This is critical to the streaming system and to the Form Designer. Do not forget to use the override directive when declaring a new component’s Create constructor.

DesignInfo#: Contains information used by the Form designer. DesignInfo is used internally. Do not use this property in applications.

Destroy()#

Disposes of the component and its owned components. Do not call Destroy directly. Call Free instead. Free verifies that the component is not nil, and only then calls Destroy. Never explicitly free a component in one of its own event handlers, nor free a component from the event handler of a component that it owns or contains. To destroy a form, call its Release method. Release waits for all the form’s event handlers and the event handlers of the form’s components to finish executing before destroying the form.

Note: A form owns all the controls and nonvisual components that are placed on it in design mode. When it is freed, all of these components are automatically freed as well. By default, all forms are owned by the global Application object. When an application terminates, it frees the global Application object, which frees all forms. For objects that are not components, and for components created with a nil owner, be sure to call Free after finishing with the object; otherwise the memory allocated for the object will be lost until the application terminates.

DestroyComponents()#: Destroys all owned components. DestroyComponents iterates through the components owned by the component, removing each from the list of owned components and destroying it. It is not necessary to call DestroyComponents directly. DestroyComponents is automatically called when the component is destroyed.

Destroying()#: Indicates that the component and its owned components are about to be destroyed. Destroying sets the csDestroying flag in the ComponentState property. It then calls the Destroying method for each owned component so that its csDestroying flag is also set. If csDestroying is already set, Destroying does nothing. It is not necessary to call Destroying directly. Destroying is automatically called when the component is destroyed.

EndFunctionInvoke(AsyncResult: IAsyncResult) → Object#: Blocks the caller until the specified ASyncResult completes. Returns the result from the method that BeginInvoke asynchronously executes. This result is immediately returned after the given IAsyncResult finishes. The result type corresponds to a TObject class type. EndInvoke raises any exception that may occur while the asynchronous method executes.

EndInvoke(ASyncResult: IAsyncResult)#: Blocks the caller until the specified ASyncResult completes. Returns the result from the method that BeginInvoke asynchronously executes. This result is immediately returned after the given IAsyncResult finishes. EndInvoke raises any exception that may occur while the asynchronous method executes.

ExecuteAction(Action: BasicAction) → Boolean#: Executes an action. ExecuteAction executes an action for the component. Action is a TBasicAction or any descendant of TBasicAction. ExecuteAction first checks whether the provided action is compatible with the component and then executes the action. The return value is a Boolean. A value of True is returned if the action was executed; otherwise, False is returned. Derived classes can override this method to implement a distinct way of handling actions.

FindComponent(AName: string) → Component#: Indicates whether a given component is owned by the component. FindComponent returns the component in the Components property array with the name that matches the string in the AName parameter. Use FindComponent to determine whether a given component is owned by another. Component name matches are not case sensitive.

FreeNotification(AComponent: Component)#: Ensures that AComponent is notified that the component is going to be destroyed. Use FreeNotification to register AComponent as a component that should be notified when the component is about to be destroyed. It is only necessary to register components this way when they are in a different form or have a different owner. For example, if AComponent is in another form and uses the component to implement a property, it must call FreeNotification so that its Notification method is called when the component is destroyed. For components with the same owner, the Notification method is called automatically when an application explicitly frees the component. This notification is not sent out when components are freed implicitly, because the Owner is already being freed.

FreeOnRelease()#: Frees the interface reference for components that were created from COM classes. FreeOnRelease is called when an interface implemented by the component is released. FreeOnRelease is used internally and calls the corresponding interface method. It should not be necessary to call FreeOnRelease directly.

GetEnumerator()#: Returns a TComponent enumerator. GetEnumerator returns a TComponentEnumerator reference, which enumerates the components contained within a specified containing component. To process all these subcomponents, call the TComponentEnumerator GetCurrent method within a While MoveNext do loop.

GetNamePath()#: Returns a string used by the Object Inspector. GetNamePath is used to determine the text to display in the Object Inspector for the name of the object being edited. GetNamePath is introduced in TPersistent so descendants such as collections can appear in the Object Inspector. TComponent overrides GetNamePath to return the component’s name. Do not call GetNamePath directly.

GetParentComponent()#: Returns the containing component. GetParentComponent returns a reference to the component that contains the current component, or nil if there is no container. Use HasParent to determine whether a component has a containing component. For example, a button on a panel on a form returns the panel, the panel returns the form, and the form returns nil.

HasParent()#: Verifies whether the component has a parent. Call HasParent to determine whether a specific component has a parent. Derived classes override this method to implement proper handling for parenting. Use GetParentComponent to retrieve the component reference.

InsertComponent(AComponent: Component)#: Establishes the component as the owner of a specified component. InsertComponent adds the component passed in the AComponent parameter to the end of the Components array property. The inserted component must have no name (no specified Name property value), or the name must be unique among all others in the Components list. When the owning component is destroyed, AComponent is also destroyed. Components are automatically inserted and removed when visually manipulating them in the form designer. Use InsertComponent when manually adding components to another Owner component’s Components list.

IsImplementorOf(I: IInterface) → Boolean#: Indicates whether the component implements a specified interface. Call IsImplementorOf to determine whether the component (or, if the component aggregates its interface with other components, whether the controlling component) supports the interface specified by I. IsImplementorOf is similar to the QueryInterface method, but it can handle a request for a nil (Delphi) or NULL (C++) interface, and it does not return an interface pointer. The streaming system that loads and saves components uses IsImplementorOf to resolve property values that are interfaces.

Name#

Specifies the name of the component as referenced in code. Use Name to change the name of a component to reflect its purpose in the current application. By default, the IDE assigns sequential names based on the type of the component, such as ‘Button1’, ‘Button2’, and so on. Use Name to refer to the component in code.

Warning: Changing Name at run time causes any references to the old name to become undefined. Any subsequent code that uses the old name will cause an exception.

Observers#: Indicates the TObservers object added to the TComponent. Observers is a read-only property that returns the TObservers added to the TComponent, in order to use the notifications provided by the observers either with LiveBindings or for the developers’ own purposes.

Owner#

Indicates the component that is responsible for streaming and freeing this component. Use Owner to find the owner of a component. The Owner of a component is responsible for two things: The memory for the owned component is freed when its owner’s memory is freed. This means that when a form is destroyed, all the components on the form are also destroyed. The Owner is responsible for loading and saving the published properties of its owned controls. By default, a form owns all components that are on it. In turn, the form is owned by the application. Thus, when the application shuts down and its memory is freed, the memory for all forms (and all their owned components) is also freed. When a form is loaded into memory, it loads all of the components that are on it. The owner of a component is determined by the parameter passed to the constructor when the component is created. For components created in the form designer, the form is automatically assigned as the Owner.

Warning: If a component has an Owner other than a form or data module, it will not be saved or loaded with its Owner unless you identify it as a subcomponent. To identify a component as a subcomponent, call the SetSubComponent method.

ReferenceInterface(I: IInterface, Operation: Operation) → Boolean#

Establishes or removes internal links that cause this component to be notified when the implementer of a specified interface is destroyed. Component writers use ReferenceInterface to ensure that properties whose values are interfaces are informed when the objects that implement those interfaces are destroyed. This notification must be in place for a property whose value is an interface to be saved with the component in a form file (that is, for such a property to persist as a published property). I is an interface pointer that is the value of the published property of interest. Operation indicates whether the notification link to the implementer of the interface should be established (opInsert) or removed (opRemove). ReferenceInterface returns True if it is successful in establishing or removing the notification link. If ReferenceInterface returns False when called with Operation set to opInsert, the specified interface cannot be stored as the value of a published property.

Note: A result of False does not necessarily indicate an error, merely that the interface cannot be stored by the property streaming system. For example, ReferenceInterface returns False when the specified interface employs true reference counting, independent of component lifetimes.

RemoveComponent(AComponent: Component)#: Removes a specified component specified from the component’s Components list. Components are automatically inserted and removed when visually manipulating them in the form designer. Use RemoveComponent to programmatically delete the component specified by AComponent from its Owner component.

RemoveFreeNotification(AComponent: Component)#: Disables the destruction notification that was enabled by FreeNotification. RemoveFreeNotification removes the component specified by the AComponent parameter from the internal list of objects to be notified that the component is about to be destroyed. AComponent is added to this list by a previous call to the FreeNotification method. Most applications have no need to call RemoveFreeNotification. It is used by TComponent to detect loops where two components are notifying each other of their impending destruction.

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 errors that might occur. TComponent calls the implementation of this method for the interface supported by the component, if it exists. If the component does not support interfaces, this method calls the SafeCallException method inherited from TObject, which returns E_UNEXPECTED. This is a default return value that is appropriate for classes that do not support any interfaces.

SetSubComponent(IsSubComponent: Boolean)#

Identifies whether the component is a subcomponent. Call SetSubComponent to indicate whether this component is a subcomponent. A subcomponent is a component whose Owner is a component other than the form or data module in which it resides. Unless such a component calls SetSubComponent with IsSubComponent set to True, its published properties will not be saved to the form file. IsSubComponent indicates whether the component is a subcomponent (True) or not (False). SetSubComponent is called at design time:

Either from the constructor of a component that always acts as a subcomponent. In this case, the component calls its own SetSubComponent method from the constructor with IsSubComponent set to True. Or immediately after constructing an instance of the subcomponent. In this case, the Owner calls the SetSubComponent method of a component it has just instantiated, with IsSubComponent set to True.

Tag#: Stores a NativeInt integral value as a part of a component. Tag has no predefined meaning. The Tag property can store any additional integer value for the convenience of developers. Often, Tag stores a pointer. A Tag value can be typecast to the appropriate pointer type. Notice that on 64-bit platforms, all pointer types are 8 bytes in size, while on 32-bit platforms, pointer types are 4 bytes. These pointer sizes correspond to sizes of NativeInt integral values on 64-bit and 32-bit platforms.

UpdateAction(Action: BasicAction) → Boolean#: Updates the state of an action. UpdateAction is used to update the state of an action. Action is a TBasicAction or any descendant. UpdateAction first checks whether the provided action is compatible with the component and then updates it. The return value is a Boolean. A value of True is returned if the action was updated, and a value of False, otherwise. Derived classes can override this method to implement a distinct way of handling action updates.

VCLComObject#: Represents information used internally by components that support COM. VCLComObject is for internal use only.