WAGINFO

  • Article

4/8/2010

The WAGINFO structure describes the Window Auto Gesture settings configured for a window. Window Auto Gesture enables the content in a window to scroll automatically in response to flick and pan gestures. This structure is used by the functions TKSetWindowAutoGesture and TKGetWindowAutoGesture

Syntax

typedef struct tagWAGI {
    size_t cbSize;
    DWORD dwFlags;
    UINT nOwnerAnimateMessage;
    UINT nAnimateStatusMessage;
    HBRUSH hExtentBrush;
    UINT nItemHeight;
    UINT nItemWidth;
    BYTE bHorizontalExtent;
    BYTE bVerticalExtent;
} WAGINFO

Parameters

  • cbSize
    The size of the structure in bytes.

  • dwFlags
    A bitmask that combines the following properties:

    WAGIF_OWNERANIMATE

    This flag is required.

    It indicates that each animation message identified by nOwnerAnimateMessage is sent to the window procedure. When this flag is set the window procedure is also responsible for manipulating the scroll bar positions and drawing the control content.

    WAGIF_VSCROLLABLE

    Enables vertical scrolling support for pan and flick. If not set, the vertical component of pan and flick will be ignored. Combine with WAGIF_HSCROLLABLE for omnidirectional scrolling, or scrolling in any arbitrary direction.

    WAGIF_HSCROLLABLE

    Enables horizontal scrolling support for pan and flick. If not set, the horizontal component of pan and flick will be ignored. Combine with WAGIF_VSCROLLABLE for omnidirectional scrolling, or scrolling in any arbitrary direction.

    WAGIF_LOCKAXES

    Ignored unless both WAGIF_VSCROLLABLE and WAGIF_HSCROLLABLE flags are also set. Setting this flag opts out of enabling scrolling in any arbitrary direction. Instead, scrolling will only happen along the horizontal or vertical axes. Note that for Windows Mobile 6.5, this setting is only applicable to flick messages. Handling of pan messages is unaffected unless the WAGIF_IGNOREPAN is set.

    WAGIF_IGNOREPAN

    Turns off automatic gesture handling of pan messages.

    WAGIF_IGNORESCROLL

    Turns off automatic gesture handling of flick messages.

  • nOwnerAnimateMessage
    The animation message ID that is sent to the window procedure to redraw the window content after a touch interaction. The message ID must be WM_USER or above. See TKGetAnimateMessageInfofor more information about the content of this message.

    Alternatively, you can set this value to 0 to receive the WM_HSCROLL or WM_VSCROLL message (or both) instead of WAG animation messages.

    When nOwnerAnimateMessage is set to 0, HorizontalExtent and bVerticalExtent are ignored.

  • nAnimateStatusMessage
    The message ID that is sent to the window procedure to indicate a state change for the animation, such as start or end. The message must be WM_USER or above.

    A value of 0 indicates that no animation status messages should be sent.

    The lParam value contains the status information that identifies the animation state that the control is entering. The following values are possible:

    • WAG_STATUS_ANIMATION_START
    • WAG_STATUS_ANIMATION_END
    • WAG_STATUS_ANIMATION_CHANGE

    WAG_STATUS_ANIMATION_CHANGE indicates that the scrolling input mode has changed.

    The wParam value contains more information about the lParam value.

    • If lParam is WAG_STATUS_ANIMATION_START or WAG_STATUS_ANIMATION_CHANGE, the valid wParam values are WAG_STATUS_ANIMATION_CONTINUOUS (indicating continuous input, or pan) or WAG_STATUS_ANIMATION_DISCRETE (a single input event, such as a flick).
    • If lParam is WAG_STATUS_ANIMATION_END, then wParam is WAG_STATUS_ANIMATION_ FINISHED (the animation finished without any interruptions) or WAG_STATUS_ANIMATION_INTERRUPTED (the animation was interrupted, such as tapping a list that is scrolling because of a previous flick).

  • nItemHeight
    The height of each item in the scroll range, in pixels.

    A scroll range is the area that supports scrolling. If this value is 0, then the item height is automatically calculated using the following formula:

    nItemHeight = <window client height> / <vertical scroll bar page size>.

    When the value is 0, the height is recalculated if the window size changes.

  • nItemWidth
    The width of each item in the scroll range, in pixels.

    A scroll range is the area that supports scrolling. If this value is 0, then the item width is automatically calculated using the following formula:

    nItemWidth = <window client width> / <horizontal scroll bar page size>.

    When the value is 0, the width is recalculated if the window size changes.

  • bHorizontalExtent
    The percentage of the viewable window height that can be extended beyond the scroll range in the horizontal axis, from 0 to 100. The default bHorizontalExtent value is 0.

    Once the extent limit is hit, no more pan messages are processed.

    If nOwnerAnimateMessage is set to 0, bHorizontalExtent and bVerticalExtent are ignored.

  • bVerticalExtent
    The percentage of the viewable window width that can be extended beyond the scroll range in the vertical axis, from 0 to 100. The default bVerticalExtent value is 0.

    Once the extent limit is hit, no more pan messages are processed.

    If nOwnerAnimateMessage is set to 0, bHorizontalExtent and bVerticalExtent are ignored.

Remarks

A call to TKSetWindowAutoGesture fails unless dwFlags includes WAGIF_OWNERANIMATE.