Using IlvSpinBox

The class IlvSpinBox defines a composite gadget made up of two buttons and several fields of the type IlvTextField or IlvNumberField.

For text fields, you can define a list of predefined string values which the user can spin through using the buttons. For number fields, you can define a set of numeric values, within the specified value range, which the user can increment or decrement using the buttons.

You can also add graphic objects to a spin box.

A Spin Box

See Using IlvNumberField and Using IlvTextField.

This section covers the following topics:

• Adding and Removing Fields to a Spin Box

• Working with Text Fields

• Working with Numeric Fields

• Event Handling and Callbacks

Adding and Removing Fields to a Spin Box

When created, a spin box has no fields; it is composed only of two arrow buttons. You can add one or more IlvTextField or IlvNumberField to a spin box. Note, however, that you can use a spin box that has no fields to increment or decrement a value in your application.

Adding Fields

To add a field to a spin box, you can use either one of these two member functions, depending on the type of values you want to display (character strings or numbers).

void addField(IlvTextField* field,

const char** values,

IlUShort count,

IlUShort pos,

IlBoolean loop,

IlUShort at = 0,

IlBoolean redraw = IlFalse);

The values parameter holds the string values that you will spin through. The count parameter specifies the number of strings in values.

void addField(IlvNumberField* field,

IlDouble value,

IlDouble increment,

IlBoolean loop,

IlUShort at = 0,

IlBoolean redraw = IlFalse);

When you add a numeric field to a spin box, the buttons allow you to change the value of the numeric field within the value range specified by the numeric field itself (see Using IlvNumberField).

The value parameter is the initial value of the field. The increment parameter specifies the value that is added to or removed from the value of the numeric field when the user clicks the Increment or Decrement buttons.

If the loop parameter is set to IlTrue, the spin box returns to the first value when the user tries to increment the last value, and to the last value when the user tries to decrement the first value.

The at parameter lets you insert the field at a specific location in the spin box.

Here is a short example (spinbox is a pointer to an IlvSpinBox object):

const char* values[7] = {"Monday", "Tuesday", "Wednesday",

"Thursday","Friday","Saturday","Sunday"};

spinbox->addField(new IlvTextField(display,"",IlvRect(0,0,10,10)),

values, 7, 0, IlTrue);

Removing Fields

To remove a field from an IlvSpinBox, use removeObject. This member function also removes a graphic object added to the spin box as a decoration.

Adding Graphic Objects

You can add any graphic object to a spin box with the member function addObject. Graphic objects appearing in a spin box serve as decorations and do not have any specific behaviors.

Working with Text Fields

If the field in a spin box is of type IlvTextField, you can retrieve its array of predefined strings with getLabels and getLabelsCount.

You can add a predefined string to a text field with addLabel and remove it with removeLabel.

You can set or retrieve the contents of a text field with these member functions:

const char* getLabel(IlvTextField*) const;

void setLabel(IlvTextField* field,

const char*   label,

IlBoolean redraw = IlFalse);

void setLabel(IlvTextField* field,

IlUShort     index,

IlBoolean redraw = IlFalse);

Working with Numeric Fields

If the field in a spin box is of type IlvNumberField, you can set the increment specified with setIncrement and retrieve it with getIncrement.

The increment is the value that is added to or retrieved from the field value when the user clicks the spin box buttons.

You can set and retrieve the numeric value of a field with these member functions:

IlDouble getValue(IlvNumberField* field,

IlBoolean& error)const;

IlBoolean setValue(IlvNumberField* field,

IlDouble value);

Event Handling and Callbacks

The class IlvSpinBox defines two callback types, Increment and Decrement, which you can access using the following:

static IlvSymbol* IncrementCallbackType();

static IlvSymbol* DecrementCallbackType();

These callbacks are invoked when the user clicks the Increment and Decrement buttons. The active field, if any, is incremented/decremented just before the callback is invoked. The Main callback is called in both cases.

See Associating a Callback with a Gadget.