Scrollbar Form Control

Database Access / Forms

Document - ID	Specification Owner	Last Change	Status
	Frank Schönheit	2003-11-10	final
Conforms to	
Applies to	OpenOffice.org Writer, OpenOffice.org Calc, OpenOffice.org Impress
Task ID(s)	21277, 21283, 21556, 21566, 21794, 21797, 21952
Category	Feature

Abstract

We will provide OpenOffice.org Writer and OpenOffice.org Calc with a new form control implementing a scrollbar.

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
XML file format	Daniel Vogelheim (DVO)	dvo@openoffice.org
Basic Dialog Editor	Thomas Benisch (TBE)	tbe@openoffice.org
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
XML file format	DVO	2003-10-16
String Review	Elizabeth Matthis	2003-11-07

Document Change History

Rev. Level	Change	Initials	Date
1.0	final release	fs	2003-11-10

Contents

Glossary	1

1	Motivation	1

2	Goals	1

3	Requirements and Dependencies	1

3.1	Requirements	1

3.2	Technical Dependencies	2

4	Detailed Specification	2

4.1	Form Design User Interface	2

4.1.1	Form Functions Tool Bar	2

4.1.2	Menu/Toolbox configuration	2

4.1.3	Form Navigator	2

4.1.4	"Replace With" functionality	2

4.2	Properties	3

4.2.1	Reused properties	3

4.2.2	Specific properties	3

4.2.3	Property Order	4

4.3	Events	4

4.3.1	Reused Events	5

4.3.2	New Events	5

4.4	Cell-bound Scrollbars	5

4.5	File format	5

4.5.1	File Format Compatibility	8

4.6	Scroll Position Handling	8

4.7	UNO API	8

4.8	String list	8

5	Future Tasks	9

6	Notes	9

7	References	10

Glossary

Term	Description
simple form control	form controls which do not have child elements. Currently this means all form control types except grid controls.
scrollbar	Illustration 1 The optical representation of a position (or value) within a continuous range of values. Can be horizontal (as shown above), or vertical (above image rotated by 90 degrees). Scrollbars should be well known from any modern desktop.
scrollbar arrow button	number 1 in Illustration 1. Used to perform →small steps
scrollbar thumb	number 2 in Illustration 1. Used to change the value represented by the scrollbar in an absolute way.
scrollbar background area	number 3 in Illustration 1 - everything except the arrow buttons and the thumb. Used to perform →large steps.
small step	A small step in a scrollbar is performed when the user clicks one of the arrow buttons of the scrollbar. With this, the value of the scrollbar is either decremented or incremented, depending on which of the arrow buttons has been clicked.
large step	A large step in a scrollbar is performed when the user clicks onto the empty space of a scrollbar. With this, the value of the scrollbar is either decremented or incremented, depending on whether the click happened before or behind the thumb.

Motivation

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

Goals

Create a scrollbar 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 scrollbar has always a direction associated with. This means that for a horizontal scrollbar, the represented value is the lower the more the thumb is positioned on the left. For a vertical scrollbar, the represented value is the lower the more the thumb is positioned at the top.

If the user interface of OpenOffice.org is orientated right-to-left, then for a horizontal scrollbar, the represented value is the lower the more the thumb is positioned on the right.

When a new scrollbar is created by the user, by drawing a rectangle with the mouse, the initial orientation of the scrollbar is horizontal in case the width of the rectangle is greater than its height, and vertical otherwise.

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.

Form Functions Tool Bar

There will be an additional icon in the "Form Functions" toolbar, denoting a scrollbar control. The icon will be positioned on the left hand side of the "Push Button" icon, as shown in Illustration 2.

Illustration 2 The icon will be the icon which, in the control toolbar in the Basic dialog editor, is used to indicate a vertical scrollbar. This holds for all resolutions and modi (normal/high contrast) of the icon.

The tooltip for the item will be "Scroll Bar".

Menu/Toolbox configuration

As all toolbox items which create form controls, the toolbox item described in the previous chapter can be configured into toolboxes as well as menus. In the configuration dialog, the item will appear with a name which equals the tool tip.

Form Navigator

In the form navigator, the scrollbar controls will be indicated with the following icon: . Again, this icon (in all resolutions and modi) is reused from the "Vertical scrollbar" icon in the Basic dialog editor.

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

In opposite to the current behavior for other form controls, this logical control name is to be localized.

"Replace With" functionality

As for all other form control types, scroll bar controls can be exchanged – in both directions – with every other simple controls.

Thus, the "Replace With" context menu of all other simple form controls, which is accessible from within the form navigator as well as the document view, will get a new entry "Scroll Bar". When chosen, the control is converted to a scrollbar.

In turn, for scrollbar controls there will be a "Replace With" context menu which contains all other simple control types. When chose, the scroll bar is converted to the target control type.

As usual, when converting control types, as much settings as possible will be preserved. In particular, all properties which exist for the source and for the target control will be transferred.

Properties

The properties of the scroll bar control will be shown on the "General" page of the property browser.

Reused properties

A number of properties which are available for scrollbars are already known from other control types, and share the well-known semantics. In particular:

UI name	semantics	default
Name	specifies a logical name for the control	n/a
Enabled	specifies whether or not a control is enabled	Yes
Print	specifies whether the control should be printed together with the document	Yes
Tabstop	specifies whether the control can be focused using the "Tab" key	Default (which effectively evaluates to "No")
Order	specifies the relative tabbing order of this control	0
Background Color	specifies the background color of a control For a scrollbar, this color is used for the Thumb, as well as the arrow buttons. Slightly darker, respectively lighter, versions of this color will be used to draw the 3D-frames of the arrow buttons and the thumb. A darker version of this color will be used to draw the background area of the scrollbar. When set to "Standard", then the office-wide default colors for scrollbars (technically: the respective colors from the Application::GetSettings) will be used.	Standard
Border	specifies the type of the border of the control	3D Look
Additional Information	specifies additional string information to be associated with the control. This information is not evaluated by OpenOffice.org itself, but usually used programmatically.	
Help text	specifies a help text which will appear as tool tip over the control	
Help URL	specifies a help URL to be used for the control, referring to user defined help content.	

Specific properties

The following properties are specific to the scroll bar control:

UI name	semantics	default	represented by
Scroll value min	denotes the minimum value which the scrollbar can represent	0	numeric input field
Scroll value max	denotes the maximum value which the scrollbar can represent	100	numeric input field
Default Scroll value	denotes the default scroll value of the control. As usual, this default value is applied in every situation where the form which the control belongs to is reset. In the property browser, no check for plausibility of this value is made. See chapter Future Tasks for a note on this.	0	numeric input field
Orientation	This describes whether the control is a horizontal or a vertical scroll bar.	depends on size ratio of created control	drop down list box, containing the entries Horizontal Vertical
Line increment	This property denotes the number of units by which the scrollbar's value is adjusted with a small step.	1	numeric input field
Block increment	his property denotes the number of units by which the scrollbar's value is adjusted with a large step.	10	numeric input field
Delay	specifies the amount of milli seconds which should pass between repeated triggers of the scrollbar. That is, if the user clicks with the mouse onto an arrow button, onto the background area, and keeps the mouse pressed, then the button will repeatedly be triggered, changing the scrollbar value every time. The delay between two such triggers is specified with this property.	50	numeric input field
Symbol color	specifies the color which is used to paint the arrows on the arrow buttons. When set to "Standard", then the office-wide default colors for scrollbars (technically: the respective colors from the Application::GetSettings) will be used.	Standard	color list box, containing an additional "Standard" entry
Visible Size	Specifies the size of scroll bar thumb in "value units". I.e. a value of ( "Scroll value max." minus "Scroll value min." ) / 2 would result in a thumb which occupies half the of the background area. If set to 0, then the thumb's width will equal its height.	0	numeric input field

All of these new properties are intersection-capable. This means that when in a document multiple objects are selected, which all support one or more of these properties, then they can be changed at once, since they're displayed in the property browser.

Property Order

As usual, a property of the control will be represented by one line in the property browser, in the following order:

Name, Enabled, Print, Tabstop, Order, Scroll value min, Scroll value max, Line increment, Block Increment, Delay, Visible size, Orientation, Background color, Symbol color, Border. Additional information, Help text, Help URL

Events

As all other form controls, scroll bar 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.

Reused Events

A number of events which are available for scrollbars are already known from other control types, and share the well-known 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

New Events

There will be one new event to bind a script to, which will be added to the end of the event list.

While adjusting

This event is triggered when the value represented by the scroll bar control is adjusted. The parameter of the method can be a com.sun.star.awt.AdjustmentEvent.

Cell-bound Scrollbars

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 scroll bar 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 scroll bar controls.

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

Action	Reaction
Move the scroll bar thumb by any means	The value represented by the scrollbar is copied into the linked cell
Enter a number or a formula returning a number into the linked cell	The scrollbar thumb is moved to the position which represents the value to which the cell content evaluates. If this value is greater than the upper limit of the scrollbar range, then the thumb is moved to this upper limit. Similarly, if the value is less than then lower limit of the scrollbar range, then the thumb is moved to this lower limit.
Enter text or a formula returning text or an error into the linked cell, or clear the linked cell	The thumb is moved to the lower limit of the scrollbar range.

Note that in Microsoft Excel, scroll bar controls whose minimum value is less than 0, and which are bound to cells, don't transfer negative values to this cell. This means that when the scrollbar is positioned at "-1", the bound sheet cell shows 65535. OpenOffice.org will not mirror this behavior.

(Note on the note: In real, it's more complex in Excel: If the minimum is small enough, e.g. -100000, then from some point on, the scrollbar does transfer negative values. But in any case, entering a value like 65000 into the cell is ambiguous, since it could mean "-536" or "65000", which cannot be decided.)

File format

In OpenOffice.org's native XML file format, we will introduce a new form control type to make scrollbars persistent. We will not explicitly focus on scrollbars here, but follow a more generic approach. Note that this implies that some attributes of scroll bar controls will not be reflected in XML attributes, but in the generic form:property-value tags, since they are specific to scroll bar controls and do not make sense in a generic context as we will describe it below.

The following chapter will be added to our file format documentation:

Value Range

the <form:value-range> element defines a control which allows the user to select a value from a continuous number range. Possible representations include scroll bars and spin buttons.

XML Code:	<form:value-range>
Rules:	
DTD:	<!ELEMENT form:value-range (form:properties?, office:events?)> <!ATTLIST form:value-range %disabled; %printable; %tab-index; %tab-stop; %title; %min-value; %max-value; %current-value; %value; %step-size; %page-step-size; %delay-for-repeat; %orientation;>

The attributes you can associate with an <form:value-range> element are:

Name and Service Name. See section 6.3 for information about these attributes.

Control, ID, Current Value, Value, Disabled, Minimum Value, Maximum Value, Printable, Tab Index, Tab Stop, and Read Only. See section 6.4 for information about these attributes.

Step Size, Page Step Size, Repeat Delay, Orientation. See below for information about these attributes.

Minimum Value

The form:min-value attribute specifies the minimum value that a user can enter into a control.

XML Code:	form:min-value
Rules:	
DTD:	<!ENTITY % min-value "form:min-value %integer; #IMPLIED">

Maximum Value

The form:max-value attribute specifies the minimum value that a user can enter into a control.

XML Code:	form:max-value
Rules:	
DTD:	<!ENTITY % max-value "form:max-value %integer; #IMPLIED">

Step Size

The form:step-size attribute specifies the increment to be used for a control representing a value.

XML Code:	form:step-size
Rules:	
DTD:	<!ENTITY % step-size "form:step-size %positiveInteger; '1'">

Page Step Size

The form:page-step-size attribute specifies a second-level increment to be used for a control representing a value. In the user interface, this is usually associated with the user pressing the "Page Up" or "Page Down" key.

XML Code:	form:page-step-size
Rules:	
DTD:	<!ENTITY % page-step-size "form:page-step-size %positiveInteger; #IMPLIED">

Repeat Delay

The form:delay-for-repeat attribute specifies a time-out, in milliseconds, to be used before a pressed mouse button results in repeating an action.

XML Code:	form:delay-for-repeat
Rules:	
DTD:	<!ENTITY % delay-for-repeat "form:delay-for-repeat %positiveInteger; #IMPLIED">

Orientation

The form:orientation attribute specifies the orientation of the control, which could be either horizontal or vertical.

XML Code:	form:orientation
Rules:	
DTD:	<!ENTITY % orientation "form:orientation (horizontal|vertical) #IMPLIED">

Additionally, the following line needs to be added to the event table in chapter "OpenOffice.org Event Types":

Value of script:event-name Attribute	Applies To	Description of Event
on-adjust	Value Range	Occurs when the value of a Value Range element has been adjusted.

As usual, the BackgroundColor property of the control will be saved as style, and not as property on the control element itself. The same holds for the newly introduced SymbolColor property.

Note that the form:linked-cell attribute will, in the DTD, also be declared as allowed attribute for the form:value-range element. However, it will not appear in the file format specification document, as this attribute is neither present in OpenOffice.org 1.1, nor will it be present in OpenOffice.org 2.0, where the representation of form control bindings (of arbitrary types) in the XML file format will be finalized.

File Format Compatibility

When saving a document which contains a scrollbar control in either OpenOffice.org's native file format, or in any older StarOffice file format, there will necessarily a loss when the file is read in older OpenOffice.org or StarOffice versions.

As a general rule, it holds that OpenOffice.org itself can read both the OpenOffice.org format and older StarOffice formats lossless.
In older OpenOffice.org versions (up to 1.1), scrollbars will not be read, but an empty shape will appear in the document (which is the usual behavior for unknown form controls, and thus not limited to scroll bar controls).
When loading such documents in StarOffice 5.2, scroll bar controls will be replaced with a place holder control (a hidden control), and an empty shape will be created (again, this is the usual behavior in StarOffice 5.2 when unknown control types are encountered).

Scroll Position Handling

The scroll position of a scrollbar control is a persistent property (like it is e.g. the text of an input field which is not bound to a database or a spreadsheet cell). As such, it is saved when saving the document, and restored upon reloading. Additionally, changing the scroll position creates an Undo action.

As usual, this does not hold when the scrollbar is bound to a spreadsheet cell, in which case neither the value is saved, nor changing the value leads to an own Undo action. However, here of course the value of the associated cell is saved, and changes to it can be undone, so effectively, the behavior is the same as for unbound scroll bars.

UNO API

The following changes/extensions will be implemented for this feature:

The optional properties ScrollValueMin, BackgroundColor, SymbolColor, and RepeatDelay will be added to the service description of the com.sun.star.awt.UnoControlScrollBarModel.

The new services com.sun.star.form.component.ScrollBar and com.sun.star.form.control.ScrollBar will be specified, which extend the com.sun.star.awt.UnoControlScrollBarModel respectively com.sun.star.awt.UnoControlScrollBar service.

String list

Item	English	German	Comments
Tool tip Context Menu	Scrollbar	Bildlaufleiste	
Logical Control Name	Scrollbar	Bildlaufleiste	
Property UI Name	Scroll value min	Min. Bildlaufwert	
Property UI Name	Scroll value max	Max. Bildlaufwert	see 1. below
Property UI Name	Default scroll value	Standard Bildlaufwert	
Property UI Name	Orientation	Ausrichtung	see 1. below
Property Value UI String	Horizontal	Horizontal	see 1. below
Property Value UI String	Vertical	Vertikal	see 1. below
Property UI Name	Small change	Kleine Änderung	
Property UI Name	Large Change	Große Änderung	
Property UI Name	Delay	Verzögerung	
Property UI Name	Symbol color	Symbolfarbe	
Property UI Name	Visible size	Sichtbare Größe	see 1. below
Event UI Name	While adjusting	Beim Justieren	see 1. below

Annotations:

1. this name is already used for the same purpose in the Basic dialog editor

Future Tasks

In the future, the scroll bar control should support customized mouse pointers which are used when the mouse hovers over the control. This is to be done together for all other control types, too, which are also missing this feature.

An "AutoOrientation" should be allowed. Competitive applications allow this value for the "Orientation" property. When chosen, then scrollbar automatically changes its orientation depending on the relationship between its height and width. With the current VCL and UNO control concept, this would be really hard and error-prone to implement.

We should have a "ProportionalThumb" property? In theory, it can be simulated when you know the control size, and the range limits. However, this is laborious ....

Currently, the property browser does not checks for plausibility of given values, e.g. it does not control whether the default value is greater than the minimum, and less than the maximum value. This is consistent with the property browser behavior for other controls (e.g. a numeric control), but in the future, we should generally changes this and add as much cross-property logic as possible and reasonable.

Notes

Icon position in the form functions toolbox is subject to change as soon as new controls are implemented, or the toolbox gets re-organized (which both will happen on the way to OpenOffice.org 2.0).

References

Specification: Form Controls Linked to Spreadsheet Cells, located in the specification section of OpenOffice.org Calc.

Scrollbar Form Control

Page 2

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

Frank Schönheit

2003-10-15T14:16:33