
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.
Up-Down Control Updates in Internet Explorer
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.
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.
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.
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.
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.
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 controls in Microsoft® Internet Explorer support the following new feature.
This section contains information about the following programming elements used with up-down controls.
| Functions |
| CreateUpDownControl |
| Notifications |
| NM_RELEASEDCAPTURE (up-down) |
| UDN_DELTAPOS |
| Structures |
| NM_UPDOWN |
| NMUPDOWN |
| UDACCEL |
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. |
This section contains information about the functions used with up-down controls.
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.
This section contains information about the messages used with up-down controls.
UDM_GETACCEL
wParam = (WPARAM) cAccels;
lParam = (LPARAM) (LPUDACCEL) paAccels;
Retrieves acceleration information for an up-down control.
If the cAccels parameter is zero and the paAccels parameter is NULL, the return value is the number of accelerators currently set for the control.
See also UDM_SETACCEL
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
wParam = 0;
lParam = 0;
Retrieves the handle to the current buddy window.
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
wParam = 0;
lParam = 0;
Retrieves the minimum and maximum positions (range) for an up-down control.
UDM_GETRANGE32
wParam = (WPARAM)(LPINT) pLow;
lParam = (LPARAM)(LPINT) pHigh;
Retrieves the 32-bit range of an up-down control.
Version 4.71
UDM_GETUNICODEFORMAT
wParam = 0;
lParam = 0;
Retrieves the UNICODE character format flag for the control.
See also UDM_SETUNICODEFORMAT
UDM_SETACCEL
wParam = (WPARAM) nAccels;
lParam = (LPARAM) (LPUDACCEL) aAccels;
Sets the acceleration for an up-down control.
See also UDM_GETACCEL
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.
UDM_SETBUDDY
wParam = (WPARAM) (HWND) hwndBuddy;
lParam = 0;
Sets the buddy window for an up-down control.
UDM_SETPOS
wParam = 0;
lParam = (LPARAM) MAKELONG((short) nPos, 0);
Sets the current position for an up-down control.
UDM_SETRANGE
wParam = 0;
lParam = (LPARAM) MAKELONG((short) nUpper, (short) nLower);
Sets the minimum and maximum positions (range) for an up-down control.
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
wParam = (WPARAM)(int) iLow;
lParam = (LPARAM)(int) iHigh;
Sets the 32-bit range of an up-down control.
Version 4.71
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.
See also UDM_GETUNICODEFORMAT
This section contains information about the notification messages sent by up-down controls.
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.
Version 4.71.
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.
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
This section contains information about the structures used with up-down controls.
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.
Version 4.70
See also UDN_DELTAPOS, WM_NOTIFY
typedef struct {
UINT nSec;
UINT nInc;
}UDACCEL, FAR *LPUDACCEL;
Contains acceleration information for an up-down control.
© 1997 Microsoft Corporation. All rights reserved. Terms of Use.