Normally, a window receives mouse messages only when the mouse is over the window. On occasions, a program may have the requirement of receiving messages even when the mouse moves outside the boundaries of the window. This section provides an example of such a case.
The first program of this section performs an operation that some drawing packages perform - drawing a filled rectangle. The output of the program is shown below.
In the above picture, a filled rectangle has already been drawn and another rectangle (that will replace the existing one) is in the process of being formed. The rectangular frame is drawn with foreground mix mode of mix::not (inverted color of the current client background). This implies that as the frame is moved, it may be redrawn to erase the existing frame and then drawn in the new position. The window data contains a couple of flags and some points to describe the rectangle being drawn and the frame used to size the new rectangle.
These variables are described in the following table.
| blocking | true when a frame is being used to define a new rectangle. |
| valid_box | true when a blocked rectangle is already defined. |
| start | The starting point of an existing rectangular block. |
| end | The ending point of an existing rectangular block. |
| box_start | The starting point of a rectangular frame being drawn. |
| box_end | The ending point of a rectangular frame being drawn. |
blocking and valid_box are initially false. When a left button down message is received:
This processing is shown below.
case message::left_button_down:
{
window_data* data = (window_data*)get_window_pointer(window_handle, 0);
data->start(0) = data->end(0) = low_part(parameter2);
data->start(1) = data->end(1) = high_part(parameter2);
draw_box_outline(window_handle, data->start, data->end);
set_cursor(load_cursor((handle)null, (const character*)cursor_identity::cross));
data->blocking = true;
set_capture(window_handle);
}
break;
The function draw_box_outline is shown below.
void draw_box_outline(handle window, point start, point end)
{
handle device_context = get_device_context(window);
set_foreground_mix(device_context,mix::not);
select_object(device_context,get_standard_object(standard_brush::null));
draw_rectangle(device_context,start(0),start(1),end(0),end(1));
release_device_context(window,device_context);
}
The border of the rectangle being drawn inverts the current value of the pixels in the client window. This means that the method may be used to erase an existing rectangle as well as draw a new rectangle. The value of the brush being standard_brush::null implies that the interior of the rectangle is left untouched.
When a left button up message is received, if blocking is in effect, the coordinates of the filled rectangle are replaced, the frame is removed, the cursor is reset and blocking is set to false and valid_box is set to true. The window is then invalidated. This code is shown below.
case message::left_button_up:
{
window_data* data = (window_data*)get_window_pointer(window_handle, 0);
if (data->blocking)
{
draw_box_outline(window_handle, data->start, data->end);
data->box_start = data->start;
data->box_end(0) = low_part(parameter2);
data->box_end(1) = high_part(parameter2);
set_cursor(load_cursor((handle)null, (const character*)cursor_identity::arrow));
data->blocking = false;
data->valid_box = true;
release_capture();
invalidate_rectangle(window_handle, (const irectangle*)null, true);
}
}
break;
The mouse move code is shown below.
case message::mouse_move:
{
window_data* data = (window_data*)get_window_pointer(window_handle, 0);
if (data->blocking)
{
set_cursor(load_cursor((handle)null, (const character*)cursor_identity::cross));
draw_box_outline(window_handle, data->start, data->end);
data->end(0) = low_part(parameter2);
data->end(1) = high_part(parameter2);
draw_box_outline(window_handle, data->start, data->end);
}
}
break;
If blocking is true, the cursor is set and the existing frame is removed via a call to the method draw_box_outline. The new position of the mouse is set and the frame is redrawn via a second call to draw_box_outline.
When a paint message is received, both the existing rectangle and the frame are drawn - as shown below.
case message::paint:
{
window_data* data = (window_data*)get_window_pointer(window_handle, 0);
paint paint_structure;
handle device_context = begin_paint(window_handle, &paint_structure);
if (data->valid_box)
{
select_object(device_context, get_standard_object(standard_brush::black));
draw_rectangle(device_context, data->box_start(0), data->box_start(1), data->box_end(0), data->box_end(1));
}
if (data->blocking)
{
set_foreground_mix(device_context, mix::_not);
select_object(device_context, get_standard_object(standard_brush::null));
draw_rectangle(device_context, data->start(0), data->start(1), data->end(0), data->end(1));
}
end_paint(window_handle, &paint_structure);
}
break;
So what is wrong with the previously presented program? When running the program, the operator should hold the mouse button down and move the cursor outside the bounds of the client area, then release the button. Upon reentering the client area, the program is unable to detect that the mouse button was released. The window stopped receiving mouse messages when the cursor was outside the window.
To fix this deficiency, a second version of the program is presented. Apart from setting the title string, the second version differs from the previous example only in three lines. The code for message::left_button_down has the additional line
set_capture(window);
and the messages message::left_button_up and message::character have a call to the function release_capture().
When the mouse is captured, the client window receives messages even when the mouse is over the system portion of the window. Whilst the mouse is captured, the system keyboard functions are also disabled. If the mouse is captured and a mouse button is not currently down, when the mouse passes over a window other than the window that has the mouse captured, messages are directed to that window. The mouse should only be captured when a button is depressed and the capture should be released when that button is released.