TObject::Dispatch Method

Calls message-handling methods for the object, based on the contents of the Message parameter.

Pascal

procedure Dispatch(var Message); virtual;

C++

virtual Dispatch(var  Message);

Description

Call System::TObject::Dispatch to automatically pass messages to the appropriate message handler.

System::TObject::Dispatch determines whether a message is in the list of message handlers declared for the object. If the object does not handle the message, System::TObject::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 System::TObject::DefaultHandler.

The only assumption System::TObject::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 System::TObject::Dispatch calls. Although any kind of data can be passed to System::TObject::Dispatch, most System::TObject descendants expect a message record such as TMessage or a specific data structure type.

Delphi Examples:

Copy Code

{
This example demonstrates the use of message dispatching
on TObject and any descendants. Using the same techniques
a form of message based OOP can be acheived where an object
"implements" a certain interface based on messages.
}

{ Define the object interface messages }
const
  INTF_MESSAGE_LOWER_STR = 1;
  INTF_MESSAGE_UPPER_STR = 2;

type
  { String container message that will be passed }
  TStrCntrMessage = packed record
    MessageId : Word;
    MsgText   : String;
  end;

  { String handler object that will serve requests }
  TStringHandler = class
  private
    procedure StrUpCase(var AMessage : TStrCntrMessage);
      message INTF_MESSAGE_UPPER_STR;

    procedure StrLowCase(var AMessage : TStrCntrMessage);
      message INTF_MESSAGE_LOWER_STR;

  public
    procedure DefaultHandler(var Message); override;

  end;

{ TStringHandler }

procedure TStringHandler.DefaultHandler(var Message);
var
  MessageId : Word absolute Message;
begin
  { Display out message then pass control to default handler }
  MessageDlg('Unhandled message ' + IntToStr(MessageId) +
    ' received!', mtInformation, [mbOK], 0);

  inherited;
end;

procedure TStringHandler.StrLowCase(
  var AMessage: TStrCntrMessage);
begin
  AMessage.MsgText := LowerCase(AMessage.MsgText);
end;

procedure TStringHandler.StrUpCase(
  var AMessage: TStrCntrMessage);
begin
  AMessage.MsgText := UpperCase(AMessage.MsgText);
end;

{ TForm2}

procedure TForm2.FormCreate(Sender: TObject);
var
  Hndlr: TStringHandler;
  Msg: TStrCntrMessage;
begin
  { Create object instance, dispatch a message and free it }
  Hndlr := TStringHandler.Create();

  { Lower-case a string using messaging }
  Msg.MessageId := INTF_MESSAGE_LOWER_STR;
  Msg.MsgText := 'Hello World';

  Hndlr.Dispatch(Msg);

  MessageDlg('Lower-cased string: ' + Msg.MsgText,
    mtInformation, [mbOK], 0);

  { Upper-case a string using messaging }
  Msg.MessageId := INTF_MESSAGE_UPPER_STR;
  Msg.MsgText := 'Hello World';

  Hndlr.Dispatch(Msg);

  MessageDlg('Upper-cased string: ' + Msg.MsgText,
    mtInformation, [mbOK], 0);

  Hndlr.Free;
end;