3.7 Controls and the Mouse

Controls are implemented as small child windows. These windows do not look like normal application windows. Instead, they define a rectangular region of the application window that holds the control. In this sense, they are similar to subwindows. The difference is that these child windows are maintained by the host graphical system.

In the general model for graphical user interfaces, the system directs events to the window where the event occurred. This window owns the event. The effect of this is most noticeable when you examine what happens when controls interact with the mouse. As the mouse moves across the application screen, the various windows that the pointer passes over each receive the appropriate events. If you look at an application screen that has several controls, the application window receives those mouse events that occur when the pointer is in the application window, but not over any of the controls. When the mouse pointer is over a control, that control receives the mouse events.

This means that the setting of the runtime configuration variable MOUSE-FLAGS affects the behavior of the mouse only when it is not over a control. When the mouse is over a control, that control does its own mouse processing.

If you need to process the mouse while it is over a control, there are two options:

1. You can capture the mouse using the CAPTURE-MOUSE option of the W$MOUSE library routine. When the mouse is captured, all mouse events are directed to the current application window, even those that occur outside of the window altogether. It is advisable to capture the mouse only for short periods of time, because capturing the mouse prevents all other applications from using the mouse. Normally you capture the mouse to handle a user-initiated action such as dragging a screen object from one location to another.

2. You can disable the control. Disabled controls cannot receive input, so any associated mouse actions are directed to the owning application instead. To disable a control, use the ENABLED phrase of the Screen Section, DISPLAY, or MODIFY statements. For more about the ENABLED phrase, see section 6.4.9, Book 3, "Reference Manual."

Note that it is rare that your program would need to manage the mouse directly. In most cases, controls manage their own mouse messages without any intervention by the program.