Up-Down Controls

Up-Down Controls


An up-down control is a pair of arrow buttons that the user can click to increment or decrement a value, such as a scroll position or a number displayed in a companion control. The value associated with an up-down control is called its current position. An up-down control is most often used with a companion control, which is called a buddy window.

arrowy.gifAbout Up-Down Controls

arrowy.gifUp-Down Control Updates in Internet Explorer

arrowy.gifUp-Down Control Reference

About Up-Down Controls

To the user, an up-down control and its buddy window often look like a single control. You can specify that an up-down control automatically position itself next to its buddy window and that it automatically set the caption of the buddy window to its current position. For example, you can use an up-down control with an edit control to prompt the user for numeric input. The following illustration shows an up-down control with an edit control as its buddy window, a combination that is sometimes referred to as a spinner control.

Up-down control with an edit control as its buddy window.

An up-down control without a buddy window functions as a sort of simplified scroll bar. For example, a tab control sometimes displays an up-down control to enable the user to scroll additional tabs into view. The following illustration shows an up-down control in the upper-right corner of a tab control.

Up-down control in the upper-right corner of a tab control.

You can create an up-down control and specify its buddy window in several ways. The UPDOWN_CLASS value specifies an up-down control's window class. You can specify this window class in a dialog box template or in a call to the CreateWindowEx function. Another way is to use the CreateUpDownControl function to create an up-down control and, at the same time, specify its buddy window, current position, and minimum and maximum positions.

The UPDOWN_CLASS window class is registered when the common controls dynamic-link library (DLL) is loaded. If you create an up-down control without using the CreateUpDownControl function, you must ensure that the DLL is loaded. You can do so by using the InitCommonControls function.

CreateUpDownControl enables you to specify a buddy window. If you create an up-down control without using this function, you can assign a buddy window by specifying the UDS_AUTOBUDDY window style or by using the UDM_SETBUDDY message. If UDS_AUTOBUDDY is specified, the up-down control automatically selects the previous window in the z-order as its buddy window. This window might be the previous control in a dialog box template. You can use UDM_SETBUDDY to assign a specific buddy window to an up-down control. To determine an up-down control's current buddy window, use the UDM_GETBUDDY message. An up-down control and its buddy window must have the same parent window.

An up-down control notifies its parent window when its current position changes by sending it a UDN_DELTAPOS notification message and a WM_VSCROLL or WM_HSCROLL message. A vertical up-down control (which does not have the UDS_HORZ style) sends a WM_VSCROLL message. A horizontal up-down control (which has the UDS_HORZ style) sends a WM_HSCROLL message.

About Up-Down Control Styles

Using window styles, you can manipulate characteristics of an up-down control, such as how it positions itself relative to its buddy window, whether it sets the text of its buddy window, and whether it processes the UP ARROW and DOWN ARROW keys.

An up-down control with the UDS_ALIGNLEFT or UDS_ALIGNRIGHT style aligns with the left or right edge of its buddy window. The width of the buddy window is decreased to accommodate the width of the up-down control.

An up-down control with the UDS_SETBUDDYINT style sets the caption of its buddy window whenever the current position changes. The control inserts a thousands separator between every three digits of a decimal string unless the UDS_NOTHOUSANDS style is specified. If the buddy window is a list box, an up-down control sets its current selection instead of its caption.

You can specify the UDS_ARROWKEYS style to provide a keyboard interface for an up-down control. If this style is specified, the control processes the UP ARROW and DOWN ARROW keys. The control also subclasses the buddy window so that it can process these keys when the buddy window has the focus.

If you use an up-down control for horizontal scrolling, you can specify the UDS_HORZ style. This style causes the up-down control's arrows to point left and right instead of up and down.

By default, the current position does not change if the user attempts to increment it or decrement it beyond the maximum or minimum value. You can change this behavior by using the UDS_WRAP style, so the position "wraps" to the opposite extreme. For example, incrementing past the upper limit wraps the position back to the lower limit.

Position and Acceleration

After an up-down control is created, you can change the control's current position, minimum position, and maximum position by sending messages. You can also change the radix base used to display the current position in the buddy window and the rate at which the current position changes when the up or down arrow is clicked.

To retrieve the current position of an up-down control, use the UDM_GETPOS message. For an up-down control with a buddy window, the current position is the number in the buddy window's caption. Because the caption may have changed (for example, the user may have edited the text of an edit control), the up-down control retrieves the current caption and updates its current position accordingly.

The buddy window's caption may be either a decimal or hexadecimal string, depending on the radix base (that is, either base 10 or 16) of the up-down control. You can set the radix base by using the UDM_SETBASE message and retrieve the radix base by using the UDM_GETBASE message.

The UDM_SETPOS message sets the current position of a buddy window. Note that unlike a scroll bar, an up-down control automatically changes its current position when the up and down arrows are clicked. An application, therefore, does not need to set the current position when processing the WM_VSCROLL or WM_HSCROLL message.

You can change the minimum and maximum positions of an up-down control by using the UDM_SETRANGE message. The maximum position may be less than the minimum, and in that case clicking the up arrow button decreases the current position. To put it another way, up means moving towards the maximum position. To retrieve the minimum and maximum positions for an up-down control, use the UDM_GETRANGE message.

You can control the rate at which the position changes when the user holds down an arrow button by setting the up-down control's acceleration. The acceleration is defined by an array of UDACCEL structures. Each structure specifies a time interval and the number of units by which to increment or decrement at the end of that interval. To set the acceleration, use the UDM_SETACCEL message. To retrieve acceleration information, use the UDM_GETACCEL message.

Default Up-Down Controls Message Processing

This section describes the standard Windows messages processed by an up-down control.
Message Processing performed
WM_CREATE Allocates and initializes a private data structure and saves its address as window data.
WM_DESTROY Frees data allocated during WM_CREATE processing.
WM_ENABLE Invalidates the window.
WM_KEYDOWN Changes the current position in the case of an UP ARROW or DOWN ARROW key.
WM_KEYUP Completes the position change.
WM_LBUTTONDOWN Captures the mouse. If the buddy window is an edit control or list box, it sets the focus to the buddy window. If the mouse is over the up or down button, it begins changing the position and sets a timer.
WM_LBUTTONUP Completes the position change and releases the mouse capture if the up-down control has captured the mouse. If the buddy window is an edit control, it selects all the text in the edit control.
WM_PAINT Paints the up-down control. If the wParam parameter is non-NULL, the control assumes that the value is an HDC and paints using that device context.
WM_TIMER Changes the current position if the mouse is being held down over a button and a sufficient interval has elapsed.

Up-Down Control Updates in Internet Explorer

Up-down controls in Microsoft® Internet Explorer support the following new feature.

Full 32-bit Range
The up-down control now supports a full 32-bit range. The UDM_SETRANGE32 and UDM_GETRANGE32 messages have been added to support this feature. The up-down control uses signed integers for its range, so it is necessary to set the range from -0x7FFFFFFF to +0x7FFFFFFF to utilize the full 32-bit range.

Up-Down Control Reference

This section contains information about the following programming elements used with up-down controls.

Up-Down Control Styles

Functions
CreateUpDownControl

Messages
UDM_GETACCEL
UDM_GETBASE
UDM_GETBUDDY
UDM_GETPOS
UDM_GETRANGE
UDM_GETRANGE32
UDM_GETUNICODEFORMAT
UDM_SETACCEL
UDM_SETBASE
UDM_SETBUDDY
UDM_SETPOS
UDM_SETRANGE
UDM_SETRANGE32
UDM_SETUNICODEFORMAT

Notifications
NM_RELEASEDCAPTURE (up-down)
UDN_DELTAPOS

Structures
NM_UPDOWN
NMUPDOWN
UDACCEL

Up-Down Control Styles

The following styles are used when creating up-down controls:
UDS_ALIGNLEFT Positions the up-down control next to the left edge of the buddy window. The buddy window is moved to the right, and its width is decreased to accommodate the width of the up-down control.
UDS_ALIGNRIGHT Positions the up-down control next to the right edge of the buddy window. The width of the buddy window is decreased to accommodate the width of the up-down control.
UDS_ARROWKEYS Causes the up-down control to increment and decrement the position when the UP ARROW and DOWN ARROW keys are pressed.
UDS_AUTOBUDDY Automatically selects the previous window in the z-order as the up-down control's buddy window.
UDS_HORZ Causes the up-down control's arrows to point left and right instead of up and down.
UDS_HOTTRACK Version 4.70. Not currently implemented.
UDS_NOTHOUSANDS Does not insert a thousands separator between every three decimal digits.
UDS_SETBUDDYINT Causes the up-down 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.
UDS_WRAP Causes the position to "wrap" if it is incremented or decremented beyond the ending or beginning of the range.

Up-Down Control Functions

This section contains information about the functions used with up-down controls.

CreateUpDownControl
HWND CreateUpDownControl(
    DWORD dwStyle, 	
    int x, 	
    int y, 	
    int cx, 	
    int cy, 	
    HWND hParent, 	
    int nID, 	
    HINSTANCE hInst	
    HWND hBuddy, 	
    int nUpper, 	
    int nLower, 	
    int nPos	
);

Creates an up-down control.

dwStyle
Window styles for the control. This parameter should include the WS_CHILD, WS_BORDER, and WS_VISIBLE styles, and it may include any of the window styles specific to the up-down control.
x
Horizontal coordinate, in client coordinates, of the upper-left corner of the control.
y
Vertical coordinate, in client coordinates, of the upper-left corner of the control.
cx
Width, in pixels, of the up-down control.
cy
Height, in pixels, of the up-down control.
hParent
Handle to the parent window of the up-down control.
nID
Identifier for the up-down control.
hInst
Handle to the module instance of the application creating the up-down control.
hBuddy
Handle to the window associated with the up-down control. If this parameter is NULL, the control has no buddy window.
nUpper
Upper limit (range) of the up-down control.
nLower
Lower limit (range) of the up-down control.
nPos
Position of the control.

Up-Down Control Messages

This section contains information about the messages used with up-down controls.

UDM_GETACCEL
UDM_GETACCEL 
    wParam = (WPARAM) cAccels; 
    lParam = (LPARAM) (LPUDACCEL) paAccels; 

Retrieves acceleration information for an up-down control.

cAccels
Number of elements in the array specified by paAccels.
paAccels
Address of an array of UDACCEL structures that receive acceleration information.

See also UDM_SETACCEL

UDM_GETBASE
UDM_GETBASE 
    wParam = 0; 
    lParam = 0; 

Retrieves the current radix base (that is, either base 10 or 16) for an up-down control.

UDM_GETBUDDY
UDM_GETBUDDY 
    wParam = 0; 
    lParam = 0; 

Retrieves the handle to the current buddy window.

UDM_GETPOS
UDM_GETPOS 
    wParam = 0; 
    lParam = 0; 

Retrieves the current position of an up-down control.

When processing this message, the up-down control updates its current position based on the caption of the buddy window. The up-down control returns an error if there is no buddy window or if the caption specifies an invalid or out-of-range value.

UDM_GETRANGE
UDM_GETRANGE 
    wParam = 0; 
    lParam = 0; 

Retrieves the minimum and maximum positions (range) for an up-down control.

UDM_GETRANGE32
UDM_GETRANGE32
    wParam = (WPARAM)(LPINT) pLow;
    lParam = (LPARAM)(LPINT) pHigh;

Retrieves the 32-bit range of an up-down control.

pLow
Address of a signed integer that receives the lower limit of the up-down control range. This parameter may be NULL.
pHigh
Address of a signed integer that receives the upper limit of the up-down control range. This parameter may be NULL.

Version 4.71

UDM_GETUNICODEFORMAT
UDM_GETUNICODEFORMAT
    wParam = 0;
    lParam = 0;

Retrieves the UNICODE character format flag for the control.

See also UDM_SETUNICODEFORMAT

UDM_SETACCEL
UDM_SETACCEL 
    wParam = (WPARAM) nAccels; 
    lParam = (LPARAM) (LPUDACCEL) aAccels; 

Sets the acceleration for an up-down control.

nAccels
Number of UDACCEL structures specified by aAccels.
aAccels
Address of an array of UDACCEL structures that contain acceleration information. Elements should be sorted in ascending order based on the nSec member.

See also UDM_GETACCEL

UDM_SETBASE
UDM_SETBASE 
    wParam = (WPARAM) nBase;    
    lParam = 0; 

Sets the radix base for an up-down control. The base value determines whether the buddy window displays numbers in decimal or hexadecimal digits. Hexadecimal numbers are always unsigned, and decimal numbers are signed.

nBase
New base value for the control. This parameter can be 10 for decimal or 16 for hexadecimal.
UDM_SETBUDDY
UDM_SETBUDDY 
    wParam = (WPARAM) (HWND) hwndBuddy; 
    lParam = 0; 

Sets the buddy window for an up-down control.

hwndBuddy
Handle to the new buddy window.
UDM_SETPOS
UDM_SETPOS 
    wParam = 0; 
    lParam = (LPARAM) MAKELONG((short) nPos, 0);  

Sets the current position for an up-down control.

nPos
New position for the up-down control. This parameter must be in the range specified by the upper and lower limits for the control.
UDM_SETRANGE
UDM_SETRANGE 
    wParam = 0; 
    lParam = (LPARAM) MAKELONG((short) nUpper, (short) nLower); 

Sets the minimum and maximum positions (range) for an up-down control.

nUpper and nLower
Maximum position and minimum position for the up-down control. Neither position can be greater than the UD_MAXVAL value or less than the UD_MINVAL value. In addition, the difference between the two positions cannot exceed UD_MAXVAL.

The maximum position can be less than the minimum position. Clicking the up arrow button moves the current position closer to the maximum position, and clicking the down arrow button moves towards the minimum position.

UDM_SETRANGE32
UDM_SETRANGE32
    wParam = (WPARAM)(int) iLow;
    lParam = (LPARAM)(int) iHigh;

Sets the 32-bit range of an up-down control.

iLow
Signed integer value that represents the new lower limit of the up-down control range.
iHigh
Signed integer value that represents the new upper limit of the up-down control range.

Version 4.71

UDM_SETUNICODEFORMAT
UDM_SETUNICODEFORMAT
    wParam = (WPARAM)(BOOL)fUnicode;
    lParam = 0;

Sets the UNICODE character format flag for the control. This message allows you to change the character set used by the control at run time rather than having to re-create the control.

fUnicode
Determines the character set that is used by the control. If this value is nonzero, the control will use UNICODE characters. If this value is zero, the control will use ANSI characters.

See also UDM_GETUNICODEFORMAT

Up-Down Control Notification Messages

This section contains information about the notification messages sent by up-down controls.

NM_RELEASEDCAPTURE (up-down)
NM_RELEASEDCAPTURE
    lpnmh = (LPNMHDR) lParam; 

Notifies an up-down control's parent window that the control is releasing mouse capture. This notification is sent in the form of a WM_NOTIFY message.

lpnmh
Address of an NMHDR structure that contains additional information about this notification message.

Version 4.71.

UDN_DELTAPOS
UDN_DELTAPOS 
    lpnmud = (LPNMUPDOWN) lParam;

Sent by the operating system to the parent window of an up-down control when the position of the control is about to change. This happens when the user requests a change in the value by pressing the control's up or down arrow. The UDN_DELTAPOS message is sent in the form of a WM_NOTIFY message.

lpnmud
Address of an NMUPDOWN structure that contains information about the position change.

The iPos member of this structure contains the current position of the control. The iDelta member of the structure is a signed integer that contains the proposed change in position. If the user has clicked the up button, this is a positive value. If the user has clicked the down button, this is a negative value.

The UDN_DELTAPOS notification is sent before the WM_VSCROLL or WM_HSCROLL message, which actually changes the control's position. This lets you examine, allow, modify, or disallow the change.

See also WM_COMMAND

Up-Down Control Structures

This section contains information about the structures used with up-down controls.

NMUPDOWN
typedef struct _NM_UPDOWN {
    NMHDR hdr;
    int   iPos;
    int   iDelta;
} NMUPDOWN, FAR *LPNMUPDOWN;

Contains information specific to up-down control notification messages. It is identical to and replaces the NM_UPDOWN structure.

hdr
NMHDR structure that contains additional information about the notification message.
iPos
Signed integer value that represents the up-down control's current position.
iDelta
Signed integer value that represents the proposed change in the up-down control's position.

Version 4.70

See also UDN_DELTAPOS, WM_NOTIFY

UDACCEL
typedef struct { 
    UINT nSec; 
    UINT nInc; 
}UDACCEL, FAR *LPUDACCEL;

Contains acceleration information for an up-down control.

nSec
Amount of elapsed time, in seconds, before the position change increment specified by nInc is used.
nInc
Position change increment to use after the time specified by nSec elapses.

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.