Delphi - Component Notification - Components that link to other Components

Delphi - Component Notification
Components that link to other Components

When creating your own components, there are times where you will want to associate several components together in some cooperative task. Typically, this is accomplished by creating a published property (ie, a property that can be modified at design time using the Object Inspector).

A few components that exhibit this behavior are

Most controls can have an associated PopupMenu
Most controls can have an associated Action
TCustomTreeView, TCustomListView, TToolBar, TCoolBar (images)
TToolButton, (DropdownMenu, MenuItem)

There are many others.

Note: This is different than components that are composed of several components. In one case, the sub-components are created by the main component and will always be there. In the other (the subject of this page), the designer adds several separate components to a form and then associates them using the Object Inspector.

The Basics | VCL Examples | Exceptions | Basic Architecture | Designer

The Basics

This is pretty important, whenever any control saves a pointer (reference) to another control, that reference must be set to nil if the referenced component is deleted. Delphi handles this by letting the control that saves the pointer (the master) tell the referenced control "that it cares". When the referenced control is deleted, it looks at its notification list and tells all the controls pointing to it that it is being destroyed. It is the responsibility of each master control to set the associated pointer to nil.

FreeNotification (placed in the property setter) notifies the remote control that this control has a pointer (ie, that its Notification method must be called when the remote control is destroyed).

    property Component: TAnotherComponent read FComponent write SetComponent;

procedure TMyControl.SetComponent(Value: TAnotherComponent);
begin
  FComponent := Value;
  if Value <> nil then Value.FreeNotification(Self);
end;

You must also override the TControl.Notification method so that, when the associated control is deleted, your control will be able to set the pointer to nil.

  protected
    procedure Notification(AComponent: TComponent;
                            Operation: TOperation); override;

procedure TMyControl.Notification(AComponent: TComponent;
  Operation: TOperation);
begin
  inherited Notification(AComponent, Operation);
  if (Operation = opRemove) and (AComponent = FComponent) 
    then FComponent := nil;
end;

If this is not done, then the Delphi IDE will crash.

This applies only to controls that are associated using properties and does not apply to controls that are created and destroyed by a master control and saved to an internal variable (which is typically done in a creator).

Delphi VCL Examples

These examples are from the Delphi VCL.

Most controls have published properties for PopupMenu and Action. Typically, both of these can be set in the IDE at design time. If any of the associated components are deleted, then the controls that reference them must be told so that the related pointers can be set to nil. Note that both PopupMenus and Actions can be associated with multiple controls .. and that if a PopupMenu (or Action) is deleted, then all the associated controls need to be notified.

    property PopupMenu: TPopupMenu read FPopupMenu write SetPopupMenu;

procedure TControl.SetPopupMenu(Value: TPopupMenu);
begin
  FPopupMenu := Value;
  if Value <> nil then
  begin
    Value.ParentBiDiModeChanged(Self);
    Value.FreeNotification(Self);
  end;
end;

When an associated component is deleted, Notification is called and the parent component must set the pointer to nil.

procedure TControl.Notification(AComponent: TComponent;
  Operation: TOperation);
begin
  inherited Notification(AComponent, Operation);
  if Operation = opRemove then
    if      AComponent = PopupMenu then PopupMenu := nil
    else if AComponent = Action    then Action    := nil;
end;

These are some additional examples showing the typical code structure seen in the VCL (but with comments and additional spacing added by me). Notice that inherited is called so that the PopupMenu and Action properties are still handled.

  // Common technique when there is only one control
procedure TPageScroller.Notification(AComponent: TComponent;
  Operation: TOperation);
begin
  inherited Notification(AComponent, Operation);
  if (Operation = opRemove) and (AComponent = Control) then Control := nil;
end;

  // Shows testing for multiple components
procedure TCustomTreeView.Notification(AComponent: TComponent;
  Operation: TOperation);
begin
  inherited Notification(AComponent, Operation);
  if Operation = opRemove then
  begin
    if AComponent = Images      then Images      := nil;
    if AComponent = StateImages then StateImages := nil;
  end;
end;

Basically

If there is a single control, the a single line if is used
When there are multiple controls, then a begin .. end block with multiple if statements is used
The if .. else structure in TControl.Notification is atypical

Exceptions

TSpinButton is interesting because

FreeNotification is not called when FocusControl is associated with a component
Yet, FFocusControl is set to nil when the associated control is deleted

procedure TSpinButton.Notification(AComponent: TComponent;
  Operation: TOperation);
begin
  inherited Notification(AComponent, Operation);
  if (Operation = opRemove) and (AComponent = FFocusControl) then
    FFocusControl := nil;
end;

Based on examples (this is not the only one), it is clear that AComponent.FreeNotification is sometimes optional. However, the IDE works fine when it is called.

According to the TComponent.FreeNotification help

FreeNotification must be called for components in other forms that have references to the component. For components in the same form as the component, the Notification method is called automatically.

However, since it doesn't hurt to set a notification for components in the same form, it isn't worth the time to check. However, that means that Txyz.Notification will be called twice, once by the component being deleted and once by the form (because every component on the form is automatically called).

The code in the next section shows that FreeNotification checks and ignores components with the same parent (which covers components placed on the same form). It also shows that all the components owned by a component will be automatically called by TComponent.Notification.

Note: TObject -> TPersistent -> TComponent -> TControl

Basic Architecture

These are some of the gory details. I provide these for those that want a more complete understanding of how this works.

destructor TComponent.Destroy;
var
  I: Integer;
begin
  Destroying;
  if FFreeNotifies <> nil then
  begin
    for I := FFreeNotifies.Count - 1 downto 0 do
    begin
      TComponent(FFreeNotifies[I]).Notification(Self, opRemove);
      if FFreeNotifies = nil then Break;
    end;
    FFreeNotifies.Free;
    FFreeNotifies := nil;
  end;
  DestroyComponents;
  if FOwner <> nil then FOwner.RemoveComponent(Self);
  inherited Destroy;
end;

procedure TComponent.FreeNotification(AComponent: TComponent);
begin
  if (Owner = nil) or (AComponent.Owner <> Owner) then
  begin
    if not Assigned(FFreeNotifies) then FFreeNotifies := TList.Create;
    if FFreeNotifies.IndexOf(AComponent) < 0 then
    begin
      FFreeNotifies.Add(AComponent);
      AComponent.FreeNotification(Self);
    end;
  end;
  Include(FComponentState, csFreeNotification);
end;

procedure TComponent.RemoveNotification(AComponent: TComponent);
begin
  if FFreeNotifies <> nil then
  begin
    FFreeNotifies.Remove(AComponent);
    if FFreeNotifies.Count = 0 then
    begin
      FFreeNotifies.Free;
      FFreeNotifies := nil;
    end;
  end;
end;

procedure TComponent.RemoveFreeNotification(AComponent: TComponent);
begin
  RemoveNotification(AComponent);
  AComponent.RemoveNotification(Self);
end;

procedure TComponent.Notification(AComponent: TComponent;
  Operation: TOperation);
var
  I: Integer;
begin
  if (Operation = opRemove) and (AComponent <> nil) then
    RemoveFreeNotification(AComponent);
  if FComponents <> nil then
    for I := 0 to FComponents.Count - 1 do
      TComponent(FComponents[I]).Notification(AComponent, Operation);
end;

FFreeNotifies is a TList that keeps track of the components that must be notified when the component is destroyed.
FComponents is a TList that keeps track of all the components that are owned by the component.

Designer

When creating a form in design mode, there is another layer of complexity - a Designer object keeps track of what is on the form.

procedure TCustomForm.Notification(AComponent: TComponent;
  Operation: TOperation);
begin
  inherited Notification(AComponent, Operation);

  // other code here

  if FDesigner <> nil then
    FDesigner.Notification(AComponent, Operation);
end;

// from classes.pas
procedure NotifyDesigner(Self, Item: TPersistent; Operation: TOperation);
var
  Designer: IDesignerNotify;
begin
  GetDesigner(Self, Designer);
  if Designer <> nil then
    Designer.Notification(Item, Operation);
end;

Any time the form and the Designer get out of sync, Delphi crashes.

Author: Robert Clemenzi