The WinTrackRect call provides general-purpose pointing-device tracking. It draws a rectangle and enables the user to position the entire rectangle, or size a specific side or corner, as required. The resulting rectangle is then returned to the application, which can use this new information for size and position data. The window manager interface for moving and sizing windows by means of the wide sizing borders uses this function, for example.

This function enables the caller to control such limiting values as:

• A maximum and minimum tracking size
  
• Absolute tracking-position limits
  
• The tracking rectangle side widths
  
• A restriction of tracking rectangle movements to a predefined positional grid.

It automatically calls WinLockWindowUpdate to prevent output in the window hwnd and its descendants while tracking. When tracking has been completed, output is enabled before this function returns. It also determines which button of the pointing device is depressed at the start of the operation, and only completes the tracking operation when the same button is released.

If the parameter of the TRACKINFO structure specified by the value is included, the pointing device pointer is positioned at the center of the tracking rectangle. Otherwise, the pointing device pointer is not moved from its current position and delta is established between the pointing device position and the part of the tracking rectangle that it moves (the delta is kept constant).

While moving or sizing with the keyboard interface, the pointing device pointer is repositioned with the tracking rectangle's new size or position.

While tracking, these keys are active:

Enter

Accepts the new position or size.

Moves the pointing device pointer and tracking rectangle left.

If the pointing device pointer is on the upper or lower edge of the tracking rectangle, the pointer is moved to the top-left or bottom-left corner respectively.

Moves the pointing device pointer and tracking rectangle up.

If the pointing device pointer is on the left or right edge of the tracking rectangle, the pointer is moved to the top-left or top-right corner respectively.

Moves the pointing device pointer and tracking rectangle right.

If the pointing device pointer is on the upper or lower edge of the tracking rectangle, the pointer is moved to the top-right or bottom-right corner respectively.

Moves the pointing device pointer and tracking rectangle down.

If the pointing device pointer is on the left or right edge of the tracking rectangle, the pointer is moved to the bottom-left or bottom-right corner respectively.

Cancels the current tracking operation. The value of the tracking rectangle is undefined on exit.

The pointing device and the keyboard interface can be intermixed. The caller need not include the value to use the keyboard interface, as this value simply initializes the position of the pointing device pointer.

If is specified in the TRACKINFO structure, the interior of the tracking rectangle is restricted to multiples of the values of the parameters. The default values for these are the system font character width and half the system font character height, respectively.

Tracking movements using the keyboard arrow keys depend on whether or not is specified in the TRACKINFO structure, If not specified, the increments are the values of the keyboard arrow keys do not cause tracking.

The tracking rectangle is usually logically "on top" of objects it tracks, so that the user can see the old size and position while tracking the new. Thus, it is possible for a window "below" the tracking rectangle to be updated while part of the tracking rectangle is "above" it.

Because the tracking rectangle is drawn in exclusive-OR mode, no window can draw below the tracking rectangle (and thereby obliterate it) without first notifying the tracking code, because unwanted areas of the tracking rectangle can be left behind. If the window doing the drawing is clipped out from the window in which the tracking is occurring, this problem does not arise.

To prevent a window that is currently processing a WM_PAINT message drawing over the tracking rectangle, the tracking rectangle is considered as a system-wide resource, only one of which can be in use at any time. If there is a risk of the currently-updating window drawing on the tracking rectangle, the tracking rectangle is removed while that window and its child windows update, and it is then replaced. This is done during the WinBeginPaint and WinEndPaint functions. If the tracking rectangle overlaps, it is removed in the WinBeginPaint function. In the WinEndPaint function, all the child windows are updated by means of the WinUpdateWindow function before the tracking rectangle is redrawn.

WinTrackRect has a modal loop within it. The loop has a HK_MSGFILTER hook and a MSGF_TRACK hook code.

Note: The rectangle tracked by this function stays within the specified tracking bounds and dimensions. If the rectangle passed is out of these bounds, or it is too large or too small, it is modified to a rectangle that meets these limits.