Spin Button Form Control

Database Access

Document - ID	Specification Owner	Last Change	Status
	Frank Schönheit	2003-11-05	final
Conforms to	
Applies to	OpenOffice.org Base, OpenOffice.org Writer, OpenOffice.org Calc, OpenOffice.org Impress
Task ID(s)	21605, 21606, 21607, 21614, 21793, 21795, 21796, 21853, 21948
Category	Feature

Abstract

We will provide OpenOffice.org with a new form control implementing a spin button.

i-Team Members

	Name	E-mail Address
Specification Owner	Frank Schönheit (FS)	fs@openoffice.org
User Experience	Christian Jansen (CJ)	cj@openoffice.org
Development	Frank Schönheit (FS)	fs@openoffice.org
Quality Assurance	Christoph Lukasiak (CLU)	clu@openoffice.org
Documentation	Uwe Fischer (UFI)	ufi@openoffice.org

Additional Stakeholders

	Name	E-mail Address
MSO Interoperability	Caolán McNamara (CMC)	cmc@openoffice.org

Approved for Implementation

	Approved by	Date
User Experience	CJ	2003-11-04
Development		
Quality Assurance	CLU	2003-11-04
Documentation	UFI	2003-11-05
String Review	Elizabeth Matthis (liz@openoffice.org)	27.11.03

Document Change History

Rev. Level	Change	Initials	Date
1.0	final release	fs	2003-11-05
1.01	additional context information for string review corrected typo in file format section string review	fs / liz	2003-11-19

Contents

Glossary	1

1	Motivation	1

2	Goals	1

3	Requirements and Dependencies	1

3.1	Requirements	1

3.2	Technical Dependencies	1

4	Detailed Specification	1

4.1	Keyboard Operations	2

4.2	Form Design User Interface	2

4.3	Properties	2

4.4	Events	3

4.5	Cell-bound Spin Buttons	3

4.6	File format	3

4.7	UNO API	3

4.8	String list	4

5	Notes	4

6	References	4

Glossary

Term	Description
spin button	a control consisting of two arrow buttons, as shown in Illustration 1. Illustration 1 There are horizontally as well as vertically oriented spin buttons.
host document	the document where a spin button (or any other form control) is embedded

Motivation

Competitive Applications – text processing applications as well as spreadsheet applications – feature a form control which acts as as spin button. To improve interoperability with such applications, such a control control will be implemented for OpenOffice.org, too.

Goals

Create a spin button form control for usage in OpenOffice.org Writer and OpenOffice.org Calc, which is equally compliant to it's counterpart control in competitive applications, as other OpenOffice.org form controls are to their counterparts.

Requirements and Dependencies

Requirements

Create a scroll bar form control which mirrors the functionality of the respective control in competitive products.

Technical Dependencies

n/a

Detailed Specification

A new form control will be created which can be embedded in all OpenOffice.org documents which support a form layer. As such, the usage of this control in general follows the paradigms which apply for the already existent form controls.

A Spin Button can be associated with an integer value, and an integer value range which limits this value. Though, unlike a scrollbar, a spin button does not have a visual representation of its value, but it can only be accessed and modified programmatically. This value, as well as all settings which can be made in the control property browser for a spin button control, do persist when the host document is saved.

For a vertical spin button, pressing the upper arrow button results in incrementing the associated value by a certain amount, and pressing the lower arrow button results in decrementing it.

For a horizontal spin button, the semantics of the buttons depends on the user interface orientation of OpenOffice.org. For a right-to-left user interface, the right hand button decrements the value, and the left hand button increments it. For a left-to-right interface, it's the other way round.

Keyboard Operations

Spin buttons can be operated by keyboard. This is indicated by the usual focus rectangle, which is draw around either the upper or the lower (right/left, respectively) arrow button. The following keyboard shortcuts are supported:

space: operates the currently focused direction, if not disabled

cursor up/down (vertical spin buttons only): If the arrow button which corresponds to the key pressed is already focused, this arrow button is pressed. If it is not yet focused, then only the focus is moved.
For instance, imagine a control where the upper arrow is focused. Pressing "cursor down" moves the focus rectangle to the lower arrow button, pressed "cursor down" again then operates the down arrow.

cursor right/left (horizontal spin buttons only): Analogous to cursor up/down

Form Design User Interface

While designing a form which is to contain a scrollbar control, the usual and well-known concepts from other form controls are used.

An icon which can be used to create a spin button will be placed in the form functions toolbar, in the first row, left beside the "Button" icon. The following images will be used for the different toolbox versions:

toolbar size / high contrast	no	yes
small		
large		

The slot for creating a spin button can be configured into toolbars and menus

In the form navigator, a spin button will be indicated with an icon which equals the normal-contrast, small toolbar icon.

A spin button can be converted into any other simple control, and vice versa, via the usual mechanisms which apply for all other controls, too.

The user interface name for the control, as it appears as tool tip in the toolbar, in the toolbar/menu configuration dialog, and in the control conversion menus, is "Spin Button"

The default name of a newly created spin button, as visible in the form navigator, will be "SpinButton". If necessary, a incrementing number will be appended to guarantee uniqueness. The name will be localized.

In opposite to most other form controls, a spin button will by default be created without any border.

Properties

All properties of the spin button control which the user can change appear on the "General" tab page of the property browser.

A number of properties will be reused, and share the semantics and their default value (applied to a newly created control) with other controls. In particular, these are: Name, Enabled, Print, Border, Tabstop, Order, Value min., Value max., Default Value, Incr./decrement value, Additional Information, Help text, and Help URL.

Additional properties exist for the spin button control, which share their semantics and default value with the scroll bar control. In particular, these are: Background Color, Orientation, Symbol color, and Delay.

Yet more additionally, spin buttons will allow to toggle the repeating behavior of their arrow buttons. For this, a new boolean property "Repeat" is introduced.

UI name	semantics	default	represented by
Repeat	specifies whether or not the spin button shows repeating behavior, which means that it is repeatedly triggered when the user keeps the mouse pressed.	"Yes"	drop down list box containing "Yes" and "No"

The new "Repeat" property is intersection-capable. This means that when in a document multiple objects are selected, which all support this property, then they can be changed at once, since they're displayed in the property browser.

In the control property browser, the following relative order of properties applies: Name, Enabled, Print, Value min., Value max., Default value, Incr./decrement value, Delay, Orientation, Background color, Symbol color, Border, Additional Information, Help text, Help URL

Events

As all other form controls, spin button controls allow to bind scripts (in particular Basic scripts) to certain events. These events can, as usual, be assigned to the control on the "Events" tab page of the control property browser.

A number of events which are already known from other control types are available for the spin button control, too, with the usual semantics. In particular, these are: When receiving focus, When losing focus, Key pressed, Key released, Mouse inside, Mouse moved while key pressed, Mouse moved, Mouse button pressed, Mouse button released, Mouse outside, While adjusting.

Cell-bound Spin Buttons

With the general possibility to link certain control types to cells in the spreadsheet document in which they are embedded, it's also possible to offer this feature for spin button controls. As for other controls, the linked cell will be defined on the "Data" tab page of the control property browser. In documents other than spreadsheet documents, the "Data" tab page will not be available for spin button controls.

The following table shows the relationship between a spin button control and the cell it is bound to.

Action	Reaction
The value associated with the spin button is changed by the user by pressing either of the arrow buttons.	The value associated with the spin button is copied into the linked cell
Enter a number or a formula evaluating to a number into the linked cell	The value which is associated with the spin button is adjusted to the value of the cell, respecting the minimum and the maximum value.
Enter text or a formula returning text or an error into the linked cell, or clear the linked cell	The value which is associated with the spin button is set to the minimum value.

File format

In OpenOffice.org's native XML file format, a spin button will be represented by the same element as a scrollbar, namely a form:value-range element.

For spin buttons, the same file persistence compatibility rules apply as for scroll bars. In particular, OpenOffice.org up to 1.1 will only import an empty shape where OpenOffice.org 2.0 saved a spin button, as will StarOffice 5.2.

UNO API

The following UNO services are defined for spin button controls:

com.sun.star.awt.UnoControlSpinButtonModel and com.sun.star.awt.UnoControlSpinButton: These services specify the basic, toolkit-level model, respectively control model, for spin buttons.

com.sun.star.form.component.SpinButton and com.sun.star.form.control.SpinButton extend the aforementioned services by functionality and/or semantics which is specific to the forms layer.

The following new interface will be defined to allow direct manipulation of a spin button control:

com.sun.star.awt.XSpinButton

String list

Item	English	German	Comments
Tooltip	Spin Button	Drehfeld	
Logical Control Name	SpinButton	Drehfeld	context: see Illustration 2; reached via: "Main Toolbar", "Show Form Functions", "Form Navigator"
(Property) Label	Repeat	Wiederholen	context: see Illustration 3; reached via: "Main Toolbar", "Show Form Functions", "Control Properties"

String contexts

Illustration 2 Form navigator with logical control names

reached via: "Main Toolbar", "Show Form Functions", "Form Navigator"

Illustration 3 property browser with property labels

reached via: "Main Toolbar", "Show Form Functions", "Control Properties"

References

Spin buttons controls share some characteristics with scroll bar controls, which are specified here.

Spin Button Form Control

Page 5

http://dba.openoffice.org/specifications/forms/spinbutton_form_control.sxw

2003-10-23T12:24:55