ITextSpinButton

The ITextSpinButton class creates and manages text spin button controls. The text spin button maintains an array of text data.

Handlers derived from the following classes can handle events for ITextSpinButton 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 ITextSpinButton constructor creates objects of this class using the following Motif widgets:

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

Handlers derived from IEditVerifyHandler can be attached to ITextSpinButton objects.

OS/2 Considerations

Avoid adding duplicate items to the PM text spinbutton control. The results of the native PM control are unpredictable.


ITextSpinButton - Member Functions and Data by Group

Constructors & Destructor

You can construct and destruct objects of this class.


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
ITextSpinButton


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

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

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

Exception

IInvalidRequest. The ID is for a numeric only spin button, which is invalid for an ITextSpinButton.

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:
ITextSpinButton(const IWindowHandle& handle)

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

handle
The window handle of an existing text spin-button control.

Exception

IInvalidRequest. The handle is for a numeric-only spin button, which is invalid for an ITextSpinButton.

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:
ITextSpinButton( 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 text spin-button control and an object for it.

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

Exception

IInvalidRequest. The style is for a numeric-only spin button, which is invalid for an ITextSpinButton.

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 ITextSpinButton& 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 wraps to 10 instead of 1. Spinning down, the button wraps from 1 to 10.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
spinDown
public:
virtual ITextSpinButton& 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 ITextSpinButton& 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 ITextSpinButton& enableNotification( bool enable = true )

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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Set Text and Validate

Use these members to query and modify the text of the spin button and to validate the contents of the spin field.


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

If the contents of the spin field matches one of the text values in the text array, true is returned. If caseSensitive is set to true, the value in the text array must match exactly.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setText

Sets the displayed contents of the spin field, regardless of the validity of the text. This does not alter the contents of the spin button array.


Overload 1
public:
virtual ITextSpinButton& setText(const IResourceId& item)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual ITextSpinButton& setText(const char* string)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
text
public:
virtual IString text() const

Returns the displayed contents of the spin field.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Styles

These style members provide a set of valid styles for the ITextSpinButton class. 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 text spin buttons.

style
Use the styles provided by ITextSpinButton 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


Text List Operations

Use these members to manage the spin button object's text array.


[view class]
add

Adds a new item at the cursor or index position. One of the overloaded versions of this function lets you add an array of text strings to the spin button.


Overload 1
public:
virtual ITextSpinButton& add( const char* string, Cursor& cursor )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual ITextSpinButton& add( const IResourceId& item, Cursor& cursor )

Exception

IInvalidParameter The cursor is invalid.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
virtual ITextSpinButton& add( const char * const* stringArray, unsigned long index, unsigned long count )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
public:
virtual ITextSpinButton& add( const IResourceId& item, unsigned long index )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 5
public:
virtual ITextSpinButton& add( const char* string, unsigned long index )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
addAsFirst

Adds the item as the first item. You can also use this function to add an item to an empty ITextSpinButton object.


Overload 1
public:
virtual ITextSpinButton& addAsFirst( const IResourceId& item )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual ITextSpinButton& addAsFirst(const char* string)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
addAsLast

Adds the item as the last item. You can also use this function to add an item to an empty text ITextSpinButton object.


Overload 1
public:
virtual ITextSpinButton& addAsLast(const char* string)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual ITextSpinButton& addAsLast(const IResourceId& item)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
addAsNext

Adds the item following the current cursor position and sets the cursor on it.


Overload 1
public:
virtual ITextSpinButton& addAsNext( const char* string, Cursor& cursor )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual ITextSpinButton& addAsNext( const IResourceId& item, Cursor& cursor )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
elementAt

Returns the string at the cursor or index position.


Overload 1
public:
virtual IString elementAt(const Cursor& cursor) const

Exception

IInvalidParameter The cursor is invalid.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual IString elementAt(unsigned long index) const

Exception

IInvalidParameter The index is invalid.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
removeAll
public:
virtual ITextSpinButton& removeAll()

Removes all items in the spin button.

Exception

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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
removeAt
public:
virtual ITextSpinButton& removeAt(Cursor& cursor)

Removes the item at the cursor position and sets the cursor to the item following the removed item. If the last item is removed, the cursor is invalidated.

Exception

IInvalidParameter The cursor is invalid.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
replaceAt

Replaces the item at the cursor position.


Overload 1
public:
virtual ITextSpinButton& replaceAt( const IResourceId& item, Cursor& cursor )

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual ITextSpinButton& replaceAt( const char* newString, Cursor& cursor )

Exception

IInvalidParameter The cursor is invalid.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
spinTo

Spins the button to the specified cursor or index position.

This function is overloaded with a version that takes a text value (string) and, optionally, a boolean flag for controlling case sensitivity. If the string specified is valid, this version spins the button to string. If caseSensitive is set to true, the string must match exactly one of the values of the spin-button text array.


Overload 1
public:
virtual ITextSpinButton& spinTo( const char* string, bool caseSensitive = false )

Exception

IInvalidParameter The specified string cannot be found in the spin button.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
virtual ITextSpinButton& spinTo(const Cursor& cursor)

Exception

IInvalidParameter The cursor is invalid.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
virtual ITextSpinButton& spinTo(unsigned long index)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


ITextSpinButton - 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