Component

Qualified name: delphifmx.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.
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 parent of a component.
HasParent	Indicates whether the component has a parent to handle its filing.
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	Returns the owned component count
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	Returns an iterator over the owned components
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	Returns the Component Owner
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.

Type:

IInterface

ComponentCount

Returns the owned component count

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.

Type:

int

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.

Type:

ComponentState

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.

Type:

ComponentStyle

Components

Returns an iterator over the owned components

DesignInfo

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

Type:

int

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) → None

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) → bool

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: str) → 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) → None

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 parent of a component.

HasParent()

Indicates whether the component has a parent to handle its filing.

InsertComponent(AComponent: Component) → None

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) → bool

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.

Type:

str

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.

Type:

Observers

Owner

Returns the Component Owner

ReferenceInterface(I: IInterface, Operation: Operation) → bool

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) → None

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) → None

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) → int

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: bool) → None

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.

Type:

int

UpdateAction(Action: BasicAction) → bool

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.

Type:

Pointer