[Lazarus] Message and Event handling structure

[Hans-Peter Diettrich]

In every control the incoming messages are processed in several steps, e.g.
WMLButtonDown --> DoMouseDown --> MouseDown --> FOnMouseDown

Does there exist some convention for the method names and their purpose?

For consistent documentation not every such method can be described as 
"event handler", this would not provide any useful information. Here is 
what I could find out so far:

1. TWinControl.WndProc receives windows (LCL? system? raw?) messages, 
filters or converts some messages, and then calls Dispatch for further 
processing. Q: why LM_, now WM_?

2. Dispatch searches the message handler in the VMT and invokes the 
matching one (else DefaultHandler). The handlers receive kind of 
"subclassed" message records, with wParam and lParam eventually broken 
down into smaller pieces.

3. WM<msg> processes a WM_<msg> message (why not LM_?), and eventually 
translates raw arguments in the Message record into internal data types 
or values.

4. Do<msg> eventually filters messages, depending on the control state, 
then calls <msg>.

5. DoOn<msg> (or only <msg>) essentially invokes an On<msg> handler, if 
installed. In the case of MouseDown it also invokes further methods, 
looks like the implementation of control state transitions.

6. An On<msg> handler at least gets notified of the event, sometimes it 
can establish its own processing, overriding the default processing in 
the control class.

Step 1 and 2 are common to all messages, deserve no further considertation.

Step 3 could be described as "message handler" or "message translator"?

Step 4 and 5 sometimes are combined into a single method, could be 
described as "event handler", because they deal with state transitions?

Step 5 could be named "event generator", according to the Delphi wording 
of "generates an <msg> event"? I started to describe such methods as 
"Invokes an On<msg> handler", but that's mostly rephrasing the obvious, 
contained in the method name.

The current docs frequently state "emulates <msg>" or "simulates an 
event", suggesting that these methods can be called during processing of 
a different message, e.g. from application code. If so, how can such 
methods be named? "message emulator" doesn't sound good to me, what 
about "message processor"?

Step 6 frequently is described as "event handler", what's definitely 
correct from the user POV, but how to name step 4 then?


Any suggestions and comments?

DoDi