A modest proposal for a new property

[hh]

@Quentin L.

Hopefully the following citation can help all of us to understand
better what's going on. Especially point (1) relates to our current
discussion:

Posted by Mark Waddingham in a long thread (2015) in the LC Builder
forum, not hard to find. It still describes at about the current state.

"Okay so there are two things here... How things work at the moment (1)
and how I propose things should evolve (2).

The code you write in LCB (let's call it the 'widget implementation') 
sits at the same level as the C++ code in the engine which controls 
the 'legacy' controls. There's a C++ wrapper control in the engine 
(MCWidget) which provides a host environment for the LCB code. It 
manipulates and marshals various parts of the event stream and other 
aspects of the engine to give a reasonably 'clean' set of events 
which the widget implementation sees. From the high-level perspective 
you have a widget object on which you can set a script (let's call 
this the 'script object'). You can think of it as the script object 
being the realization of a widget implementation in the LiveCode 
environment.

(1) At the moment widget implementations are entirely responsible for 
dispatching all messages to their script object. This means that if a 
widget implementation does not react to, or post the mouse event 
messages, the script object will not see them. This mirrors how the 
legacy controls are written in the engine - they, for the most part, 
individually control what event messages are sent to the script 
objects and when.

(2) My proposal is to change this slightly to ensure there is a 
reasonable level of 'default behavior' in widgets, generalizing and 
improving the current (although not entirely consistent) default 
behavior amongst the existing legacy controls. Using a mouse click as 
an example, here is my current suggestion of how it would work:

The engine receives a mouseDown event on a widget.
A mouseDown message is sent to the script object of the widget.
If the mouseDown message is handled (and not passed) then the script 
object will have been considered to have 'grabbed' the mouse click 
gesture and will then receive the mouseUp / mouseRelease message at 
some later date - the widget implementation will not see the 
OnMouseDown event or the subsequent OnMouseUp.
If, on the other hand, the mouseDown message is not handled then the 
widget will receive the OnMouseDown event and subsequently the 
OnMouseUp event. In this case script would still receive the 
mouseUp / mouseRelease message *after* the widget has processed the 
OnMouseUp event - this is to ensure that (just like widgets) the 
script object always gets matched pairs of mouseDown / mouseUp.

With this logic, the script of a widget can choose to 'block' the 
widget implementation from processing the mouse click gesture but if 
it chooses not to then the widget will handle it.

For the other mouse events, such as mouseEnter / mouseLeave / 
mouseMove then they are just notifications so script and the widget 
will get the events to process.

This logic should mean that any widget which does not handle mouse 
click events will still allow the script object to handle them 
(without any additional work); and widgets that do handle mouse click 
events still generate the script messages which you might expect.

Let's take an example of a push button widget. I'm imagining here 
that the push button widget will dispatch a 'clicked' message to 
script when a mouseUp event is received within its bounds. The order 
of events would be as follows:

In the case the script object passes (or does not handle) the 
mouseDown event:
mouseDown to script object
OnMouseDown to widget
...
OnMouseUp to widget
clicked to script object
mouseUp to script object

In the case the script object handles (and does not pass) the 
mouseDown event:
mouseDown to script object
...
mouseUp to script object

This hopefully gives the best of both worlds - script can control 
whether widgets handle the mouse gestures, and still get notification 
about significant points in the gesture; whilst widgets are 
guaranteed to get a mouse gesture to process in entirety (if script 
decides it should be so) and thus an opportunity to reinterpret the 
gesture as a higher-level event (such as clicked, or 'barClicked' in 
the example of a graphing widget as suggested by Trevor)."