rwlogo
Rogue Wave Views 5.6

Rogue Wave Views
Gadgets Package API Reference Guide

Product Documentation:

Rogue Wave Views
Documentation Home

List of all members | Public Member Functions | Static Public Member Functions | Friends
IlvSpinBox Class Reference

Gadget class. More...

#include <ilviews/gadgets/spinbox.h>

Inheritance diagram for IlvSpinBox:
IlvGadget IlvSimpleGraphic IlvGraphic

Public Member Functions

 IlvSpinBox (IlvDisplay *display, const IlvRect &rect, IlvOrientation arrowOrientation=IlvVertical, IlUShort thickness=IlvDefaultGadgetThickness, IlvPalette *palette=0)
 Constructor. More...
 
 IlvSpinBox (IlvDisplay *display, const IlvPoint &point, IlvOrientation arrowOrientation=IlvVertical, IlUShort thickness=IlvDefaultGadgetThickness, IlvPalette *palette=0)
 Constructor. More...
 
void addField (IlvTextField *field, const char **values, IlUShort count, IlUShort pos, IlBoolean loop, IlUShort at=0, IlBoolean redraw=IlFalse)
 Adds a text field to the spin box. More...
 
void addField (IlvNumberField *field, IlDouble value, IlDouble increment, IlBoolean loop, IlUShort at=0, IlBoolean redraw=IlFalse)
 Adds a numeric field to the spin box. More...
 
void addLabel (IlvTextField *field, const char *label)
 Adds a new string to the predefined strings associated with the specified text field. More...
 
void addObject (IlvGraphic *object, IlUShort at=0, IlBoolean redraw=IlFalse)
 Adds the specified object to the spin box as a decoration. More...
 
virtual void computeArrowRects (IlvRect &decrArrow, IlvRect &incrArrow, IlvRect &internal, const IlvTransformer *t) const
 Is called to compute the bounding boxes of spin box items. More...
 
IlvTextFieldgetActiveField () const
 Returns the field (numeric field or text field) that is currently active. More...
 
IlvOrientation getArrowLayout () const
 Returns the position of the spin box arrows. More...
 
IlvOrientation getArrowOrientation () const
 Returns the orientation of the spin box arrows. More...
 
IlvArrowButtongetDecrementButton () const
 Returns a pointer to the decrement button. More...
 
IlDouble getIncrement (IlvNumberField *field) const
 Returns the increment value set for the specified numeric field. More...
 
IlvArrowButtongetIncrementButton () const
 Returns a pointer to the increment button. More...
 
const char * getLabel (IlvTextField *field) const
 Returns the label displayed by the specified text field. More...
 
const char ** getLabels (IlvTextField *field) const
 Returns an array containing the predefined strings associated with the specified text field. More...
 
IlUShort getLabelsCount (IlvTextField *field) const
 Returns the number of predefined strings associated with the specified text field. More...
 
IlvGraphicgetObject (IlUShort index) const
 Returns the graphic object specified by index. More...
 
IlUShort getObjectPosition (IlvGraphic *object) const
 Returns the index of the specified graphic object. More...
 
IlUInt getPeriod () const
 Returns the period of time that elapses before a value is incremented or decremented when the user clicks on a spin box arrow. More...
 
IlUShort getPosition (IlvTextField *field, IlBoolean &error) const
 Returns the index of the label of the specified text field in the predefined strings array. More...
 
IlDouble getValue (IlvNumberField *field, IlBoolean &error) const
 Returns the value of the specified numeric field. More...
 
IlBoolean isDecrementSensitive () const
 Indicates whether the increment button is sensitive. More...
 
IlBoolean isField (IlvGraphic *object) const
 Checks whether the specified object is a field of the spin box. More...
 
IlBoolean isIncrementSensitive () const
 Indicates whether the increment button is sensitive. More...
 
IlBoolean isLoop (IlvTextField *field) const
 Indicates whether the specified field is in the loop mode. More...
 
IlUShort objectCount () const
 Returns the number of graphic objects (fields and decorations) that the spin box contains. More...
 
void removeLabel (IlvTextField *field, IlShort index)
 Removes the predefined string located at the specified index from the specified text field. More...
 
void removeObject (IlvGraphic *object, IlBoolean redraw=IlFalse)
 Removes the specified object from the spin box. More...
 
void setArrowLayout (IlvOrientation orientation, IlBoolean redraw=IlFalse)
 Sets the position of the spin box arrows. More...
 
void setArrowOrientation (IlvOrientation orientation, IlBoolean redraw=IlFalse)
 Sets the orientation of the spin box arrows. More...
 
void setDecrementSensitive (IlBoolean value, IlBoolean redraw=IlFalse)
 Specifies whether the decrement button should be sensitive. More...
 
void setIncrement (IlvNumberField *field, IlDouble value)
 Sets the increment value of the specified numeric field. More...
 
void setIncrementSensitive (IlBoolean value, IlBoolean redraw=IlFalse)
 Specifies whether the increment button should be sensitive. More...
 
void setLabel (IlvTextField *field, const char *label, IlBoolean redraw=IlFalse)
 Sets the label of the specified text field. More...
 
void setLabel (IlvTextField *field, IlUShort index, IlBoolean redraw=IlFalse)
 Sets the label of the specified text field to one of its predefined strings. More...
 
void setLoop (IlvTextField *field, IlBoolean loop)
 Specifies whether the specified field should operate in the loop mode. More...
 
void setPeriod (IlUInt period)
 Sets the period of time that elapses before a value is incremented or decremented when the user clicks on a spin box arrow. More...
 
IlBoolean setValue (IlvNumberField *field, IlDouble value, IlBoolean redraw=IlFalse)
 Sets the value of the specified numeric field. More...
 

Static Public Member Functions

static IlSymbolDecrementCallbackType ()
 Returns the callback type of the Decrement callback. More...
 
static IlSymbolIncrementCallbackType ()
 Returns the callback type of the Increment callback. More...
 

Friends

class IlvDefaultSpinBoxLFHandler
 

Detailed Description

Gadget class.

Library: ilvadvgdt

The IlvSpinBox class 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. For numeric fields, you can define a set of numeric values which the user can increment or decrement using the buttons, within the specified range.

You can also add any graphic objects to a spin box. These additional objects are considered as decorations and thus have no specific behavior.

A Spin Box

See Also
IlvArrowButton, IlvNumberField, IlvTextField.

Constructor & Destructor Documentation

IlvSpinBox::IlvSpinBox ( IlvDisplay display,
const IlvRect rect,
IlvOrientation  arrowOrientation = IlvVertical,
IlUShort  thickness = IlvDefaultGadgetThickness,
IlvPalette palette = 0 
)

Constructor.

Initializes a new instance of the IlvSpinBox class. The spin box created by this constructor has no fields. You can use one of the addField methods to add one or more fields to the spin box.

Parameters
displayThe connection to the display.
rectThe size and position of the spin box.
arrowOrientationThe orientation of the spin box arrows. Valid values are: IlvVertical or IlvHorizontal.
thicknessThe thickness of the spin box.
paletteThe palette of the spin box.
See Also
addField
IlvSpinBox::IlvSpinBox ( IlvDisplay display,
const IlvPoint point,
IlvOrientation  arrowOrientation = IlvVertical,
IlUShort  thickness = IlvDefaultGadgetThickness,
IlvPalette palette = 0 
)

Constructor.

Initializes a new instance of the IlvSpinBox class. The spin box created by this constructor has no fields. You can use one of the addField methods to add one or more fields to the spin box.

Parameters
displayThe connection to the display.
pointThe position of the spin box.
arrowOrientationThe orientation of the spin box arrows. Valid values are: IlvVertical or IlvHorizontal.
thicknessThe thickness of the spin box.
paletteThe palette of the spin box.
See Also
addField

Member Function Documentation

void IlvSpinBox::addField ( IlvTextField field,
const char **  values,
IlUShort  count,
IlUShort  pos,
IlBoolean  loop,
IlUShort  at = 0,
IlBoolean  redraw = IlFalse 
)

Adds a text field to the spin box.

Parameters
fieldThe text field to be added.
valuesAn array of the strings appearing in the text field.
countThe number of elements in the values array.
posThe index in the values array of the first string.
loopA Boolean value specifying whether the text field returns to the first value when the last value is incremented, or to the last value when the first value is decremented.
atThe position in the spin box where the new text field will be inserted.
redrawA Boolean value specifying whether the spin box should be redrawn.
See Also
removeObject
void IlvSpinBox::addField ( IlvNumberField field,
IlDouble  value,
IlDouble  increment,
IlBoolean  loop,
IlUShort  at = 0,
IlBoolean  redraw = IlFalse 
)

Adds a numeric field to the spin box.

When you add a numeric field to a spin box, the buttons allow you to modify the displayed value within the value range specified by the numeric field (see the class IlvNumberField).

Parameters
fieldThe numeric field to be added.
valueThe initial value of the field.
incrementThe increment value that is added to or removed from the numeric field when clicking the arrow buttons.
loopA Boolean value specifying whether the numeric field returns to the first value when the last value is incremented, or to the last value when the first value is decremented.
atThe position in the spin box where the number field will be inserted.
redrawA Boolean value specifying whether the spin box should be redrawn.
See Also
removeObject
void IlvSpinBox::addLabel ( IlvTextField field,
const char *  label 
)

Adds a new string to the predefined strings associated with the specified text field.

The new string specified by label is added at the end of the predefined string array.

Parameters
fieldThe text field of the spin box.
labelThe string to be added.
See Also
removeLabel, getLabel
void IlvSpinBox::addObject ( IlvGraphic object,
IlUShort  at = 0,
IlBoolean  redraw = IlFalse 
)

Adds the specified object to the spin box as a decoration.

Objects added to a spin box with this method are used as decorations and thus are not active. The size of these objects is not modified by the spin box.

Parameters
objectThe graphic object to be added.
atThe position where the object will be inserted in the spin box.
redrawA Boolean value specifying whether the spin box should be redrawn.
See Also
removeObject
virtual void IlvSpinBox::computeArrowRects ( IlvRect decrArrow,
IlvRect incrArrow,
IlvRect internal,
const IlvTransformer t 
) const
virtual

Is called to compute the bounding boxes of spin box items.

Parameters
decrArrowThe returned bounding box of the decrement arrow.
incrArrowThe returned bounding box of the increment arrow.
internalThe internal bounding box where to draw the objects of the spin box.
tThe transformer.
static IlSymbol* IlvSpinBox::DecrementCallbackType ( )
static

Returns the callback type of the Decrement callback.

The Decrement callback is invoked when the user clicks on the decrement button. The active field, if any, is decremented just before invoking the callback.

Returns
The callback type for the Decrement callback.
See Also
IncrementCallbackType, IlvGraphic::setCallback
IlvTextField* IlvSpinBox::getActiveField ( ) const

Returns the field (numeric field or text field) that is currently active.

The active field is the field that has the keyboard focus in the spin box. You can change the active field by clicking on another field of the spin box.

Returns
The field (numeric or text) that is currently active.
IlvOrientation IlvSpinBox::getArrowLayout ( ) const

Returns the position of the spin box arrows.

Returns
The position of the spin box arrows, which can be IlvRight (arrows are located on the right side of the spin box), IlvLeft (arrows are located on the left side), and IlvCenter (arrows are located on both sides of the spin box).
See Also
setArrowLayout
IlvOrientation IlvSpinBox::getArrowOrientation ( ) const

Returns the orientation of the spin box arrows.

Returns
The orientation of the spin box arrows, which can be IlvHorizontal or IlvVertical.
See Also
setArrowOrientation
IlvArrowButton* IlvSpinBox::getDecrementButton ( ) const

Returns a pointer to the decrement button.

Returns
A pointer to the decrement button.
See Also
getIncrementButton
IlDouble IlvSpinBox::getIncrement ( IlvNumberField field) const

Returns the increment value set for the specified numeric field.

Parameters
fieldThe numeric field of the spin box.
Returns
The increment value set for field. This value is added to or removed from the field value when the arrows buttons are clicked.
See Also
setIncrement
IlvArrowButton* IlvSpinBox::getIncrementButton ( ) const

Returns a pointer to the increment button.

Returns
A pointer to the increment button.
See Also
getDecrementButton
const char* IlvSpinBox::getLabel ( IlvTextField field) const

Returns the label displayed by the specified text field.

Parameters
fieldThe text field of the spin box.
Returns
The label displayed by /a field. This is equivalent to calling IlvTextField::getLabel for the text field.
See Also
setLabel
const char** IlvSpinBox::getLabels ( IlvTextField field) const

Returns an array containing the predefined strings associated with the specified text field.

Parameters
fieldThe text field of the spin box.
Returns
An array containing the predefined strings defined for field.
See Also
getLabel, setLabel
IlUShort IlvSpinBox::getLabelsCount ( IlvTextField field) const

Returns the number of predefined strings associated with the specified text field.

Parameters
fieldThe text field of the spin box.
Returns
The number of predefined strings associated with field.
See Also
setLabel
IlvGraphic* IlvSpinBox::getObject ( IlUShort  index) const

Returns the graphic object specified by index.

Parameters
indexThe index of the graphic object to be retrieved.
Returns
The graphic object, whether a field or a decoration, specified by index.
See Also
objectCount, getObjectPosition
IlUShort IlvSpinBox::getObjectPosition ( IlvGraphic object) const

Returns the index of the specified graphic object.

Parameters
objectThe graphic object.
Returns
The position of object, whether a field or a decoration, within the spin box.
See Also
getObject
IlUInt IlvSpinBox::getPeriod ( ) const

Returns the period of time that elapses before a value is incremented or decremented when the user clicks on a spin box arrow.

The default value is 200.

Returns
The period of time that elapses before a value is incremented or decremented when the user clicks on a spin box arrow.
See Also
setPeriod
IlUShort IlvSpinBox::getPosition ( IlvTextField field,
IlBoolean error 
) const

Returns the index of the label of the specified text field in the predefined strings array.

Parameters
fieldThe text field of the spin box.
errorA Boolean value specifying whether an error occurred. If the field can be edited, the label might not correspond to any of the strings in the array. In this case, the returned value is the last correct index edited in this field and the parameter error is set to IlTrue.
Returns
The index of the label of field in the predefined string array.
See Also
getLabel
IlDouble IlvSpinBox::getValue ( IlvNumberField field,
IlBoolean error 
) const

Returns the value of the specified numeric field.

Parameters
fieldThe numeric field of the spin box.
errorA Boolean value specifying whether an error occurs when the number field value is converted to a double value. If field can be edited, the numeric field value might be incorrect, that is, it might be out of the bounds defined in IlvNumberField. In this case, the parameter error is set to IlTrue.
Returns
The value of field. If field can be edited, the returned value is the last correct edited value.
See Also
setValue(IlvNumberField*, IlDouble, IlBoolean)
static IlSymbol* IlvSpinBox::IncrementCallbackType ( )
static

Returns the callback type of the Increment callback.

The Increment callback is invoked when the user clicks on the increment button. The active field, if any, is incremented just before invoking the callback.

Returns
The callback type for the Increment callback.
See Also
DecrementCallbackType, IlvGraphic::setCallback
IlBoolean IlvSpinBox::isDecrementSensitive ( ) const

Indicates whether the increment button is sensitive.

Returns
IlTrue if the increment button is sensitive and IlFalse> otherwise.
See Also
setDecrementSensitive, isIncrementSensitive
IlBoolean IlvSpinBox::isField ( IlvGraphic object) const

Checks whether the specified object is a field of the spin box.

Parameters
objectThe graphic object to be checked.
Returns
IlTrue if object is a field of the spin box (that is, if this object was added using one of the addField methods of the class).
See Also
addField
IlBoolean IlvSpinBox::isIncrementSensitive ( ) const

Indicates whether the increment button is sensitive.

Returns
IlTrue if the increment button is sensitive and IlFalse> otherwise.
See Also
setIncrementSensitive, isDecrementSensitive
IlBoolean IlvSpinBox::isLoop ( IlvTextField field) const

Indicates whether the specified field is in the loop mode.

Parameters
fieldThe spin box field.
Returns
IlTrue if field returns to the first value when the last value is incremented, or to the last value when the first value is decremented.
See Also
setLoop
IlUShort IlvSpinBox::objectCount ( ) const

Returns the number of graphic objects (fields and decorations) that the spin box contains.

Returns
The number of graphic objects (fields and decorations) contained in this spin box.
See Also
addField, addObject
void IlvSpinBox::removeLabel ( IlvTextField field,
IlShort  index 
)

Removes the predefined string located at the specified index from the specified text field.

Parameters
fieldThe text field of the spin box.
indexThe index of the string to be removed.
See Also
addLabel, setLabel
void IlvSpinBox::removeObject ( IlvGraphic object,
IlBoolean  redraw = IlFalse 
)

Removes the specified object from the spin box.

The object parameter can be a spin box field (added by addField) or a decoration object (added by addObject).

Parameters
objectThe graphic object to be removed.
redrawA Boolean value specifying whether the spin box should be redrawn.
See Also
addObject, addField
void IlvSpinBox::setArrowLayout ( IlvOrientation  orientation,
IlBoolean  redraw = IlFalse 
)

Sets the position of the spin box arrows.

Changing the layout does not have any effect if the spin box contains no object.

Parameters
orientationThe new position of the spin box arrows. Valid values are: IlvRight (arrows are located on the right side of the spin box), IlvLeft (arrows are located on the left side), and IlvCenter (arrows are located on both sides of the spin box).
redrawA Boolean value specifying whether the spin box should be redrawn.
See Also
getArrowLayout
void IlvSpinBox::setArrowOrientation ( IlvOrientation  orientation,
IlBoolean  redraw = IlFalse 
)

Sets the orientation of the spin box arrows.

Parameters
orientationThe new orientation of the spin box arrows. Valid values are: IlvHorizontal or IlvVertical.
redrawA Boolean value specifying whether the spin box should be redrawn.
See Also
getArrowOrientation
void IlvSpinBox::setDecrementSensitive ( IlBoolean  value,
IlBoolean  redraw = IlFalse 
)

Specifies whether the decrement button should be sensitive.

When the decrement button is set to nonsensitive, you can no longer decrement the field value. If a field is not in loop mode (see IlvSpinBox::setLoop) and cannot be edited, the arrow buttons become insensitive automatically when the first value allowed for the field has been reached.

Parameters
valueA Boolean value specifying whether the decrement button should be sensitive (IlTrue).
redrawA Boolean value specifying whether the spin box should be redrawn.
See Also
isDecrementSensitive, IlvGraphic::setSensitive, setIncrementSensitive
void IlvSpinBox::setIncrement ( IlvNumberField field,
IlDouble  value 
)

Sets the increment value of the specified numeric field.

Parameters
fieldThe numeric field of the spin box.
valueThe new increment value of field. This value is added to or removed from the field value when the arrow buttons are clicked.
See Also
getIncrement
void IlvSpinBox::setIncrementSensitive ( IlBoolean  value,
IlBoolean  redraw = IlFalse 
)

Specifies whether the increment button should be sensitive.

When the increment button is set to nonsensitive, you can no longer increment the field value. If a field is not in loop mode (see IlvSpinBox::setLoop) and cannot be edited, the arrow buttons become insensitive automatically when the last value allowed for the field has been reached.

Parameters
valueA Boolean value specifying whether the increment button should be sensitive (IlTrue).
redrawA Boolean value specifying whether the spin box should be redrawn.
See Also
isIncrementSensitive, IlvGraphic::setSensitive, setDecrementSensitive
void IlvSpinBox::setLabel ( IlvTextField field,
const char *  label,
IlBoolean  redraw = IlFalse 
)

Sets the label of the specified text field.

Parameters
fieldThe text field of the spin box.
labelThe new label to which field is set.
redrawA Boolean value specifying whether the spin box should be redrawn.
See Also
getLabel
void IlvSpinBox::setLabel ( IlvTextField field,
IlUShort  index,
IlBoolean  redraw = IlFalse 
)

Sets the label of the specified text field to one of its predefined strings.

Parameters
fieldThe text field of the spin box.
indexThe index of the predefined string.
redrawA Boolean value specifying whether the spin box should be redrawn.
See Also
getLabel
void IlvSpinBox::setLoop ( IlvTextField field,
IlBoolean  loop 
)

Specifies whether the specified field should operate in the loop mode.

Parameters
fieldThe spin box field.
loopA Boolean value specifying whether field should operate in the loop mode. If loop is set to IlTrue, field returns to the first value when the last value is decremented or to the last value when the first value is decremented.
See Also
isLoop
void IlvSpinBox::setPeriod ( IlUInt  period)

Sets the period of time that elapses before a value is incremented or decremented when the user clicks on a spin box arrow.

Parameters
periodThe new period expressed in milliseconds.
See Also
getPeriod
IlBoolean IlvSpinBox::setValue ( IlvNumberField field,
IlDouble  value,
IlBoolean  redraw = IlFalse 
)

Sets the value of the specified numeric field.

Parameters
fieldThe numeric field of the spin box.
valueThe new double value to which field is set.
redrawA Boolean value specifying whether the spin box should be redrawn.
Returns
A Boolean value specifying whether an error occurs when setting field to value.
See Also
getValue(IlvNumberField*, IlBoolean&)

© Copyright 2012, Rogue Wave Software, Inc. All Rights Reserved.
Rogue Wave is a registered trademark of Rogue Wave Software, Inc. in the United States and other countries. All other trademarks are the property of their respective owners.