3. The working with Spins

The spin button control (also called an up-down control) provides a pair of arrows that the user can click to adjust a value. This value is called the current position. The position stays within the range of the spin button. When the user clicks the up arrow, the position moves toward the maximum; and when the user clicks the down arrow, the position moves toward the minimum.

The spin button control is represented in MFC by class CSpinButtonCtrl.

The default range for the spin button has the maximum set to zero (0) and the minimum set to 100. Since the maximum value is less than the minimum value, clicking the up arrow will decrease the position and clicking the down arrow will increase it. Use CSpinButtonCtrl::SetRange to adjust these values.

Typically, the current position is displayed in a companion control. The companion control is called the "buddy window."

To the user, a spin button control and its buddy window often look like a single control. You can specify that a spin button control automatically position itself next to its buddy window, and that it automatically set the caption of the buddy window to its current position. You can use a spin button control with an edit control to prompt the user for numeric input.

Clicking the up arrow moves the current position toward the maximum, and clicking the down arrow moves the current position toward the minimum. By default, the minimum is 100 and the maximum is 0. Any time the minimum setting is greater than the maximum setting (for example, when the default settings are used), clicking the up arrow decreases the position value and clicking the down arrow increases it.

A spin button control without a buddy window functions as a sort of simplified scroll bar. For example, a tab control sometimes displays a spin button control to enable the user to scroll additional tabs into view.

The spins creation

The spins are described by CSpinButtonCtrl class. As the most of common controls, they are constructed by Create() functions. The standard sequence is the following:

You construct a CSpinButtonCtrl object in two steps. First call the constructor, then call Create, which creates the spin button control and attaches it to the CSpinButtonCtrl object.

BOOL CSpinButtonCtrl::Create( DWORD dwStyle, const RECT& rect, CWnd* pParentWnd, UINT nID );

dwStyle   Specifies the spin button control's style. Apply any combination of spin button control styles to the control;

rect   Specifies the spin button control's size and position. It can be either a CRect object or a RECT structure;

pParentWnd   A pointer to the spin button control's parent window, usually a CDialog. It must not be NULL;

nID   Specifies the spin button control's ID.

The following styles are specific to spin button controls:

20. UDS_HORZ   Causes the control's arrows to point left and right instead of up and down.

21. UDS_WRAP   Causes the position to "wrap" if it is incremented or decremented beyond the ending or beginning of the range.

22. UDS_ARROWKEYS   Causes the control to increment and decrement the position when the UP ARROW and DOWN ARROW keys are pressed.

23. UDS_SETBUDDYINT   Causes the control to set the text of the buddy window (using the WM_SETTEXT message) when the position changes. The text consists of the position formatted as a decimal or hexadecimal string.

24. UDS_NOTHOUSANDS   Does not insert a thousands separator between every three decimal digits.

25. UDS_AUTOBUDDY   Automatically selects the previous window in the Z-order as the control's buddy window.

26. UDS_ALIGNRIGHT   Positions the spin button control next to the right edge of the buddy window. The width of the buddy window is decreased to accommodate the width of the control.

27. UDS_ALIGNLEFT   Positions the spin button control next to the left edge of the buddy window. The buddy window is moved to the right and its width decreased to accommodate the width of the control.

On spin pressing, the WM_VSCROLL message is sent to the parent window. Here the standard function OnVScroll() is re-defined.

afx_msg void CWnd::OnVScroll( UINT nSBCode, UINT nPos, CScrollBar* pScrollBar );

Parameters:

nSBCode   Specifies a scroll-bar code that indicates the user's scrolling request.

nPos   Contains the current scroll-box position if the scroll-bar code is SB_THUMBPOSITION or SB_THUMBTRACK; otherwise not used. Depending on the initial scroll range, nPos may be negative and should be cast to an int if necessary.

pScrollBar  If the scroll message came from a scroll-bar control, contains a pointer to the control. If the user clicked a window's scroll bar, this parameter is NULL. The pointer may be temporary and should not be stored for later use.

Some functions of CSpinButtonCtrl class

int CSpinButtonCtrl::GetPos( ) const;

Function is used to retrieve the current position of a spin button control.

To set the current position for a spin button control, there is used such function:

int SetPos( int nPos );

nPos   New position for the control. This value must be in the range specified by the upper and lower limits for the control.

To set the upper and lower limits (range) for a spin button control.

void SetRange( int nLower, int nUpper );

nLower and nUpper   Upper and lower limits for the control. Neither limit can be greater than UD_MAXVAL or less than UD_MINVAL. In addition, the difference between the two limits cannot exceed UD_MAXVAL.

The default range for the spin button has the maximum set to zero (0) and the minimum set to 100. Since the maximum value is less than the minimum value, clicking the up arrow will decrease the position and clicking the down arrow will increase it.

To retrieve the upper and lower limits (range) for a spin button control use function GetRange().

void CSpinButtonCtrl::GetRange( int &lower, int& upper ) const;

lower   Reference to an integer that receives the lower limit for the control.

upper   Reference to an integer that receives the upper limit for the control.

The example program to work with spins is described in the next sections.