Spinbox Usage Guideline Bookmark this Guideline Printable Page


RCUI Document Version 5.0.1 for Oracle® Fusion Middleware 11g Release 1 Patch Set 1 (11.1.1.2.0)
Last Updated 21-Jan-2011

The Spinbox component accepts a number from a range of numeric values.

Guideline Contents

Note: Images in this guideline are provided as a general reference, and may not be exact representations of FusionFX pages.

Related Guidelines

Guideline Section For Information About
Slider All Alternative to Spinbox for selection of numeric values without fixed increments.
Input/Output Text All Alternative to Spinbox for entry of numeric values.
Select Choice All Alternative to Spinbox for selection from a fixed set of values.
Help Framework Help note window Help method used with spin boxes.
Message Framework All Message methods used with spin boxes.

Related ADF Elements

Refer to the ADF Faces Rich Client demos page to find demos and tag documentation for the ADF elements related to this component:

ADF Element Notes
af:inputNumberSpinbox Spinbox component.

General Principles Bookmark this Heading Return to Top

Purpose:

Allows users to select a single numeric value from a series of values.

Description:

  • A spin box consists of a text box with up and down arrows.
  • Users can click the up or down arrows to set the value for the box, or manually enter a value in the box.
 

Spin box

Spin Box

Examples:

  • A calendar may use a spin box for the selection of a Year value. The default would be the current year; the spin box would enable users to move forward or backward to select a different year.
  • When a database administrator must indicate how many concurrent users are allowed at a time, the "Number of Users" field could be a spin box. This would enable the DBA to quickly select a value higher or lower than the current setting.

Usage:

  • A spin box may be used within a toolbar, table cell, or form layout. A spin box may also be used as a stand-alone component.
  • Spin boxes are for numeric input only. Numbers may be whole number integers (positive or negative) or decimals.
  • Both Spinbox and Slider components can be used to specify a value in a range. The spin box is recommended when one or more of the following conditions exists:
    • The range is relatively large—up to several hundreds.
    • Ranges are well-defined with a commonly understood start point and end point, such as 1-31 days, 1-12 months, or 0-100 percent.
    • Data is literal rather than subjective, such as a number of items rather than a product evaluation from 1 - 10.
  • If the selected value is not meaningful to the user, and the range of values is small, consider using another selection-oriented component such a Select Radio group or Select Choice list, with descriptive labels instead of numbers. For example, instead of rating a product or service from 1 to 5, consider rating it from "Poor" to "Excellent", or "Very Dissatisfied" to "Very Satisfied".

Spinbox Sequence Bookmark this Heading Return to Top

Description:

The Spinbox sequence consists of a series of numbers with a predefined increment between each number.

Usage:

  • By default, a sequence does not have a minimum and maximum value. However, it is strongly recommended to provide a minimum and maximum value because most users do not require a range from infinity to negative infinity.
  • Use of decimals is available, when needed for data such as pricing, page margin widths, hours billed, and so forth.
  • When possible, use whole number increments for the sequence. Whole numbers are easier to comprehend than decimals.
  • Leading zeros may also be added to display numbers in the sequence. For instance, when displaying a list of departments or cost centers within a business, a product could use "01, 02, 03 . . .  10, 11," and so on.

Elements Bookmark this Heading Return to Top

The following image shows elements of a spin box.

Spin Box elements: Changed Field Indicator, Required Field Indicator, Help icon, prompt, the text box, the value in the text box, the up arrow, and down arrow.

Spin Box Elements

Prompt Bookmark this Heading Return to Top

Purpose:

Identifies the range of data within the spin box.

Usage:

  • Use of prompts is strongly recommended in a form layout. In a table layout, the column header is the prompt.
  • There is no limit to the number of characters allowed in the prompt, but product teams must make sure that the layout allows for prompts to become up to 100 percent longer in translation.
  • Prompts may be visually omitted when the function of the spin box is obvious to the product's users without displaying a label, typically because the preceding header helps identify the field. For example, a calendar application might use a spin box without a prompt to configure the duration of an appointment, with an Hours spin box followed by a Minutes spin box.
  • When a prompt is visually omitted, provide a hidden prompt label so that accessibility tools, such as screen readers, can still read a prompt for the data.

Box Bookmark this Heading Return to Top

Purpose:

Displays the default or selected number.

Description:

Users can click the up or down arrows to set the value for the box, or manually enter a value in the box.

Usage:

  • A spin box should be disabled when users are not able to select a value for the spin box, but it is necessary to display the box because it may be enabled in different contexts.
  • A spin box should be shown as read-only when data is displayed in a read-only page, such as a printable page. Read-only data may also be displayed when the user has permission to view the data, but not to edit it.
  • The recommended default width of the box is five characters (EMs) or 28 pixels; however, the width of the box can be set by product teams.

Value Bookmark this Heading Return to Top

Purpose:

Displays data in the text box.

Usage:

Same as Input/Output Text, except:

  • By default, spin boxes accept only numeric values as valid input; however, product teams may use a custom converter to create ranges that use non-numeric values, such as the letters of the alphabet.
  • Product teams can set any number within the range to be the default. For example:
    • The current year in a range of years.
    • The most commonly selected value.
    • The start of a range of values, where no single value is commonly selected.
  • Product teams should provide an error message for the cases in which the user types a value that is not in the sequence of valid values. See the Messaging Framework guideline for details.

Required Field Indicator Bookmark this Heading Return to Top

Purpose:

Identifies fields that must be completed before submitting the page. Optional element.

  • The Required Field Indicator does not appear if a spin box is disabled or read-only.
  • ADF provides ALT text and tooltips to indicate required fields. Product teams may additionally provide key notation to define the Required Field Indicator. Refer to Key Notation in the Headers guideline for information regarding usage.

Usage:

Same as Input/Output Text.

Help Text Bookmark this Heading Return to Top

Purpose:

Provides users with additional information about the spin box. Optional element.

Usage:

Same as Input/Output Text.

Changed Field Indicator Bookmark this Heading Return to Top

Purpose:

Indicates that the value in the spin box changed after page submission. Optional element.

  • ADF provides ALT text and tooltips to indicate changed fields. Product teams may additionally provide key notation to define the Changed Field Indicator. Refer to Key Notation in the Headers guideline for information regarding usage.

Usage:

Same as Input/Output Text.