drawDeskTopRectangle

drawDeskTopRectangle(borderStyle: Integer;
                     x1:          Integer;
                     y1:          Integer;
                     x2:          Integer;
                     y2:          Integer;
                     borderColor: Integer;
                     borderWidth: Integer);

The drawDeskTopRectangle method of the Window class creates a transparent desktop window onto which the rectangle is drawn. Any white pixels are treated as being transparent.

This window is used for any subsequent calls to the drawDeskTopRectangle method made on the associated window and is repositioned and resized each time.

Each call to the method erases any previous drawing and draws the new rectangle pattern.

The drawing does not use the Xor operator to combine a draw pattern pixel with a background pixel on the desktop.

The window is destroyed if the effective rectangle passed in the call is the same as the previously drawn rectangle or the window on which the call was made is destroyed. This means that existing logic that redraws the previous rectangle drawn (double xor) will work correctly. However, the drawing will flash as the window is repeatedly created and destroyed.

To improve the user experience, change the logic to remove the second draw call to erase the rectangle, and redraw it only when the window is no longer required.

The window is also destroyed if a call is made with -1 as the first parameter (borderStyle).

Any window can have an associated drawing, thus allowing multiple rectangle patterns to be visible at once. Each drawing is independent of the other.

Use the drawDeskTopRectangleEx method if you want additional functionality; that is, you want the:

Inner part of the rectangle drawn using the value of the innerStyle parameter and the color specified in the innerColor parameter unless the value of the innerStyle parameter is -1.
Drawing window retained (that is, it is not destroyed) if the same rectangle is drawn a second time.
Drawing window destroyed only if both the borderStyle and innerStyle parameters have a value of -1 or the associated window is destroyed.

The parameters for the drawDeskTopRectangle method are listed in the following table.

Parameter	Description
borderStyle	-1 (destroy the drawing window)
	0 (hatch style 45 degrees left to right)
	1 (cross-hatch)
	2 (45 degree cross-hatch)
	3 (hatch style 45 degrees right to left)
	4 (horizontal)
	5 (vertical)
	6 (halftone)
	7 (solid)
	Any other value is treated as no drawing required (note that this method does not draw the inside of the rectangle and the rectangle border is not drawn if the value of the borderWidth parameter is less than or equal to zero)
x1, y1	Left and top corner positions of rectangle, respectively, in pixels relative to the client area of the window
x2, y2	Right and bottom corner positions of rectangle, respectively, in pixels relative to the client area of the window
borderColor	Color with which to draw the rectangle
borderWidth	Width of the inner area of the rectangle drawn with the pattern specified in the borderStyle parameter

If the width of the border area is greater than or equal to the width or height of the rectangle being drawn, the entire rectangle is filled with the specified pattern.

The methods in the following examples (in which inDragOver: Boolean, lastMouseX: Integer, and lastMouseY: Integer are form properties) show the use of this method to draw a dragging rectangle when the user drags the mouse over the ListBox control.

listBox1_dragOver(listBox: ListBox;
                  win:     Window;
                  x, y:    Real;
                  state:   Integer) updating;
vars
    w : Integer;
    h : Integer;
begin
    w := (listBox.clientWidth/2).Integer;
    h := (listBox.clientHeight/2).Integer;
    // draw in new position
    inDragOver := true;
    lastMouseX := x.Integer;
    lastMouseY := y.Integer;
    listBox.drawDeskTopRectangle(0, lastMouseX - w, lastMouseY - h,
                                 lastMouseX + w, lastMouseY + h, Red, 4);
end;

listBox1_dragDrop(listBox: ListBox; win: Window; x, y: Real) updating;
begin
    if inDragOver then
        listBox1.drawDeskTopRectangle(-1, lastMouseX - w, lastMouseY - h,
                                      lastMouseX + w, lastMouseY + h, Red, 4);
    endif;
end;

2016.0.02 (Service Pack 1) and higher