INumericSpinButton

The INumericSpinButton class creates and manages numeric spin button control windows. INumericSpinButton extends the spin button function in IBaseSpinButton to include the ability to specify numeric ranges for the spin field.

Handlers derived from the following classes can handle events for INumericSpinButton objects:

Portability Considerations

The AIX environment supports only the first constructor, which creates an object of this class from a control ID, parent and owner windows, a rectangle, and a style.

AIX Considerations

The INumericSpinButton constructor creates objects of this class using the following Motif widgets:

The Open Class Library provides the behavior of an INumericSpinButton object via private callbacks and a default handler. The INumericSpinButton class uses a default handler derived from the class IKeyboardHandler. Therefore, attach user-defined handlers derived from IKeyboardHandler to the INumericSpinButton object rather than to its owner window. Doing so enables events to be dispatched to user-defined handlers before the default handler.

In addition, handlers derived from IEditVerifyHandler can be attached to INumericSpinButton objects.


INumericSpinButton - Member Functions and Data by Group

Constructors & Destructor

You can construct and destruct objects of this class.


[view class]
~INumericSpinButton
public:
virtual ~INumericSpinButton()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
INumericSpinButton


Overload 1
public:
INumericSpinButton(unsigned long id, IWindow* parent)

You can construct objects of this class by creating an object for the specified numeric spin button control.

id
A unique ID for the numeric spin button control.
parent
The parent dialog window.

Exception

IInvalidRequest The ID must be for a numeric-only spin button control.

Supported Platforms

Windows OS/2 AIX
Yes Yes No

Windows Considerations

This constructor can only be used to create an object with the pmCompatible style.


Overload 2
public:
INumericSpinButton(const IWindowHandle& handle)

You can construct objects of this class by creating an object for the specified numeric spin button control.

handle
The window handle of an existing numeric spin button control.

Exception

IInvalidRequest The handle must be for a numeric-only spin button control.

Supported Platforms

Windows OS/2 AIX
Yes Yes No

Windows Considerations

This constructor can only be used to create an object with the pmCompatible style.


Overload 3
public:
INumericSpinButton( unsigned long id, IWindow* parent, IWindow* owner, const IRectangle& initial = IRectangle ( ), const Style& style = defaultStyle ( ) )

You can construct objects of this class by creating the specified numeric spin button control and an object for it. The numeric spin button has an initial value of 0 and an initial range of (0,0).

windowId
A unique ID for the numeric spin button control.
parent
The parent window.
owner
The owner window.
initial
A rectangle defining the size and placement of the numeric spin button window. Optional.
style
The style of the control. Optional.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Limit and Spin

Use these members to manage the spin field for objects of this class.


[view class]
setLimit
public:
virtual INumericSpinButton& setLimit(unsigned long aNumber)

Sets the number of characters permitted in the spin field. The Open Class Library defines this limit as 255 at the time of construction.
Note: If you call this function with a limit that does not display all the numbers in the spin button range, erratic results can occur when the button is spun. For example, if the range is 1 to 100 and the limit is set to 2, the button spins up to 99 and then spins to 10 instead of 100. Spinning down, the button wraps from 1 to 10.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
spinDown
public:
virtual INumericSpinButton& spinDown( unsigned long spinBy = 1 )

Spins the button down the specified number of times.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
spinUp
public:
virtual INumericSpinButton& spinUp( unsigned long spinBy = 1 )

Spins the button up the specified number of times.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Notification Members

Use these members to enable notifications sent to observer objects.


[view class]
enableNotification
public:
virtual INumericSpinButton& enableNotification( bool enable = true )

Enables the numeric spin button control to send notifications to any observer objects added. If enable is false, these notifiations are disabled.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Number Range Operations

Use these members to query, modify, and validate the spin field contents and range.


[view class]
isSpinFieldValid
public:
virtual bool isSpinFieldValid( bool caseSensitive = false ) const

If the contents of the spin field are within the number range, true is returned. This function ignores the caseSensitive flag for numeric spin buttons.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
range
public:
virtual IRange range() const

Returns the number range of the spin button.

Exception

IAccessError The operating system's request to query the spin button's limits has failed.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setRange
public:
virtual INumericSpinButton& setRange( const IRange& aNewRange, bool override = false )

Sets the lower and upper limit of the spin button range.

aNewRange
The new lower and upper limit.
override
If you set override to true and the current value in the spin field is outside the new range, the current value in the spin field does not change. If override is false and the current value in the spin field is outside the new range, the current value in the spin field is set to the closest limit. The default is false.

Exception

IInvalidParameter The new range is invalid.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setValue
public:
virtual INumericSpinButton& setValue(long aValue)

Sets the displayed value of the spin field, regardless of the validity of the number.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
spinTo
public:
virtual INumericSpinButton& spinTo( long aValue, bool spinToClosest = false )

Spins the spin button until the specified value displays. If the specified value is out of range, one of the following happens:

Exception

IInvalidParameter The spin value is not valid.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
value
public:
virtual long value() const

Returns the current value displayed in the spin field.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Styles

These style members provide a set of valid styles for this class. Use these members to query and set the numeric spin button styles. You can use these styles with the styles in the following classes:


[view class]
convertToGUIStyle
public:
virtual unsigned long convertToGUIStyle( const IBitFlag& style, bool extendedOnly = false ) const

Converts a style object into a value appropriate for the presentation system. The default action is to return the base GUI styles for the platform. Extended styles, those defined by the application and the Open Class Library, are returned if you set extendedOnly to true.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
defaultStyle
public:
static Style defaultStyle()

Returns the default style. The default style is classDefaultStyle unless you have changed the style using setDefaultStyle.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setDefaultStyle
public:
static void setDefaultStyle(const Style& style)

Sets the default style for all subsequent numeric spin buttons.

style
Use the styles provided by INumericSpinButton Styles to specify the default style.

This member function is not thread safe. In a multithreaded application, it should only be called when a conflict is not possible. A conflict can arise if you set the default style on one thread at the same time that it is being queried on another. In this situation, the query would take place while the style is in an unknown state.

When you create a window class and do not specifically specify window styles in the constructor, the Open Class Library queries the default style. Therefore, the only safe place to call this member function is when no other application threads that create windows are active.

Another way to avoid a conflict in a multithreaded application is to specifically specify window styles on window construction, rather than calling this member function.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
classDefaultStyle
public:
static const Style classDefaultStyle

Provides the original default style for this class, which is the following: IBaseSpinButton::master | IBaseSpinButton::leftAlign | IBaseSpinButton::border3D | IWindow::visible.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
padWithZeros
public:
static const Style padWithZeros

Pads the displayed number with zeros at the front.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


INumericSpinButton - Inherited Member Functions and Data

Inherited Public Functions

IBaseSpinButton
IControl
INotifier
IWindow

Inherited Public Data

IWindow
INotifier
IBaseSpinButton

Inherited Protected Functions

IWindow
INotifier
IBaseSpinButton
IControl

Inherited Protected Data