Jump to content

WinTrackRect

From EDM2

This function draws a tracking rectangle.

Syntax

WinTrackRect(hwnd, hps, ptiTrackinfo)

Parameters

hwnd (HWND) - Input
Window handle where tracking is to take place.
It is assumed that the style of this window is not WS_CLIPCHILDREN.
HWND_DESKTOP
Track over the entire screen.
Other
Track over specified window only.
hps (HPS) - Input
Presentation-space handle.
Used for drawing the clipping rectangle:
NULLHANDLE
The hwnd parameter is used to calculate a presentation space for tracking. It is assumed that tracking takes place within hwnd and that the style of this window is not WS_CLIPCHILDREN. Thus, when the drag rectangle appears, it is not clipped by any children within the window. If the window style is WS_CLIPCHILDREN and the application causes the drag rectangle to be clipped, it must explicitly pass an appropriate presentation space.
Other
Specified presentation-space handle.
ptiTrackinfo (PTRACKINFO) - In/Out
Track information.

Returns

rc (BOOL) - returns
Success indicator.
TRUE
Tracking successful.
FALSE
Tracking canceled, or the pointing device was already captured when this function was called.
Only one tracking rectangle can be in use at one time.

Remarks

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.
Left cursor
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.
Up cursor
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.
Right cursor
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.
Down cursor
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.
Esc
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 TF_GRIDis specified in the TRACKINFO structure, the interior of the tracking rectangle is restricted to multiples of the values of the cxGrid and cyGridparameters. 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 TF_GRIDis specified in the TRACKINFO structure. If not specified, the increments are the values of cxKeyboard and cyKeyboard; otherwise, 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.

Errors

Possible returns from WinGetLastError:

  • PMERR_INVALID_HWND (0x1001) - An invalid window handle was specified.

Related Messages

Example Code

This example shows how WinTrackRect can be used to allow a user size a rectangle on the screen. 

#define INCL_WINTRACKRECT
#include <os2.H>

BOOL MyTrackRoutine(HAB hab, HPS hps, PRECTL rcl)
{
  TRACKINFO track;

  track.cxBorder = 4;
  track.cyBorder = 4;   /* 4 pel wide lines used for rectangle */
  track.cxGrid = 1;
  track.cyGrid = 1;     /* smooth tracking with mouse */
  track.cxKeyboard = 8;
  track.cyKeyboard = 8; /* faster tracking using cursor keys */

  WinCopyRect(hab, &track.rclTrack, rcl);    /* starting point */

  WinSetRect(hab, &track.rclBoundary, 0, 0, 640, 480); /* bounding rectangle */

  track.ptlMinTrackSize.x = 10;
  track.ptlMinTrackSize.y = 10;  /* set smallest allowed size of rectangle */
  track.ptlMaxTrackSize.x = 200;
  track.ptlMaxTrackSize.y = 200; /* set largest allowed size of rectangle */

  track.fs = TF_MOVE; // Example flag - might need others depending on desired behavior

  if (WinTrackRect(HWND_DESKTOP, hps, &track) )
  {
    /* if successful copy final position back */
    WinCopyRect(hab, rcl, &track.rclTrack);
    return(TRUE);
  }
  else
  {
    return(FALSE);
  }
}

Related Functions

Retrieved from "https://www.edm2.com/index.php?title=WinTrackRect&oldid=84936"