Form Controls: Interoperability I

Database Access

Document - ID	Specification Owner	Last Change	Status
	Frank Schönheit	2004-06-18	final
Conforms to	
Applies to	All OpenOffice.org applications supporting a form layer
Task ID(s)	i24674
Category	Feature

Abstract

OpenOffice.org's form controls will be refit with various new properties, which allow to modify appearance-related aspects of them which previously could not be customized. This gives the designer of form documents more flexibility in the design of her documents, and it will improve the import of documents originating from competing office suites, where form controls already support equivalent appearance customizations.

i-Team Members (The specification owner is part of the i-Team)

	Name	E-mail Address
User Experience	Christian Jansen (CJ)	cj@openoffice.org
Development	Frank Schönheit (FS)	fs@openoffice.org
Quality Assurance	Marc Neumann (MSC)	msc@openoffice.org
Documentation	Uwe Fischer (UFI)	ufi@openoffice.org

Approved for Implementation

	Approved by	Date
User Experience	Christian Jansen	2004-05-03
Development		
Quality Assurance	Marc Neumann	2004-04-29
Documentation	Uwe Fischer	2004-05-03
String Review	Elizabeth Matthis	2004-06-14

Document Change History

Rev. Level	Change	Initials	Date
0.1	initial public revision	FS	2004-04-21
0.2	incorporated some changes from DV's review	FS	
0.3	added relative positions of the new properties some preliminary German texts "Style" property also available for Check Box columns in Table Controls centred" changed to "centered" (have to use en-US in specs) Added default for Graphics Alignment property	FS	2004-04-30
0.4	approvals	FS	2004-05-03
1.0	string review	FS	2004-06-18

Contents

Glossary	1

Legend	1

1	Motivation	1

2	User Scenarios	1

3	Goals	2

4	Requirements and Dependencies	2

4.1	Requirements	2

4.2	Technical Dependencies	2

5	Competitive Analyses	2

5.1	Microsoft Office	2

5.1.1	Property Names and Values	2

6	Detailed Specification	3

6.1	Refitting controls with known properties	3

6.1.1	Word break	3

6.1.2	Background color	3

6.1.3	Alignment	3

6.2	New simple control properties	4

6.2.1	Toggle (Push Button)	4

6.2.2	Take Focus on Click (Push Button)	4

6.2.3	Hide selection (text input controls)	5

6.2.4	Style (Check Box, Option Button)	5

6.2.5	Border color	6

6.3	Form controls with Images and Text	7

6.3.1	Control Layout	7

6.3.2	Compatibility	8

7	Future Tasks	8

8	References	9

9	Appendix	9

Glossary

Term	Description
property browser	A component for inspecting and modifying (form related) objects such as → form controls.
property	the smallest possible aspect of a → form control which can be modified in the → property browser
form control	Form controls are document elements which behave like well-known user interface elements in usual applications, such as option buttons, check boxes, input fields, and the like. Controls can appear in any of OpenOffice.org's document types.
inspection	the process of displaying and changing the properties of a form control in the → property browser
host application	the application type (Writer, Calc, Impress) which belongs to the document type where the form controls are embedded
text input controls	→ form controls which allow inputting text of some kind
content area	The area of a form control which can be used to draw its content (usually text and/or an image). That is, the content area is the whole control, less border (if present), less the space for a possible status bitmap (for Option Buttons and Check Boxes), less elements such as a drop down button.
text area	The part of the → content area which is used to draw the text label of a control.
image area	The part of the → content area which is used to draw an image.

Legend

Throughout the document, some character styles are used to indicate various things. In particular:

This kind of text denotes a property name, as to be seen in the property browser.

This kind of text denotes a form control type.

This kind of text denotes a property value, as to be seen in the property browser.

Motivation

Current (up to OpenOffice.org 1.x) form controls are missing some possibilities to customize their appearance. For instance, option buttons and check boxes still use the 3D-like images for indicating their mark, while modern user interfaces are not that 3D-centric anymore. Thus, OpenOffice.org 1.x does not allow to create modern-fashioned form documents. Since OpenOffice.org 2.0 will contain functionality to position itself in work flows centered around electronic forms, a change of this situation is not only desirable for database forms, but also for the newly created electronic forms.

Additionally, importing form documents from a well-known competing office suite currently loses some attributes when it comes to form controls, since OpenOffice.org form controls do not support all facets which their equivalents in the other office suite do support – for instance, OpenOffice.org check boxes to not support customizing their background color. One step to relaxing this situation is to add the appearance-related facets to OpenOffice.org's form controls, as described in this document.

User Scenarios

A user imports a Microsoft Word document containing form controls. In OpenOffice.org 1.x, chances are high that the very first visual impression she gets is the one of wrong appearance of the form controls, since too much appearance-related facets were not property imported.

Using the new eForms functionality in OpenOffice.org 2.0, users can create electronic forms support e.g. their company's workflow. Using the new customization possibilities described herein, these form documents will provide a more state-of-the-art visual impression than it would be possible with OpenOffice.org 1.x.

Goals

A number of new properties for various form controls is to be implemented. They will allow greater flexibility in designing the appearance of form documents, and at the same time mimic the respective functionality in Microsoft Office documents – in particular in Microsoft Word – as good as possible.

Requirements and Dependencies

Requirements

In OpenOffice.org, form controls are implemented on the top of VCL, which is it's low-level graphical toolkit. Not all of the functionality which is to be added is already present in this lower layer, so several VCL controls need to be refit with extended layout capabilities.

Technical Dependencies

n/a

Competitive Analyses

Microsoft Office

Property Names and Values

The newly introduced form control properties described in this document are inspired by the need to properly import Microsoft documents containing form controls. The following table contains a comparison of the property names suggested herein, and the names of the respective settings in Microsoft Office products. Note that Microsoft also seems to reuse the form control implementations across the various applications, so the things said here apply to at least Microsoft Word and Microsoft Excel. Note additionally that Microsoft does not seem to translate the property names in localized office versions.

new OpenOffice.org Microsoft Office English German not localized	Notes
Take Focus on Click		TakeFocusOnClick	
Hide selection	Auswahl verstecken	HideSelection	
Style	Stil	SpecialEffect	see 1. below
3D	3D	fmButtonEffectSunken	see 1. below
Flat	Flach	fmButtonEffectFlat	see 1. below
Above left	Oben links	fmPicturePositionAboveLeft	
Above centered	Oben zentriert	fmPicturePositionAboveCenter	
Above right	Oben rechts	fmPicturePositionAboveRight	
Below left	Unten links	fmPicturePositionBelowLeft	
Below centered	Unten zentriert	fmPicturePositionBelowCenter	
Below right	Unten rechts	fmPicturePositionBelowRight	
Left top	Links oben	fmPicturePositionLeftTop	
Left centered	Links zentriert	fmPicturePostitionLeftCenter	
Left bottom	Links unten	fmPicturePostitionLeftBottom	
Right top	Rechts oben	fmPicturePostitionRightTop	
Right centered	Rechts zentriert	fmPicturePostitionRightCenter	
Right bottom	Rechts unten	fmPicturePostitionRightBottom	
centered	Zentriert	fmPicturePostitionCenter	

Notes on the above table:

The naming discrepancy between SpecialEffect and Style, and it's respective values, is by intent. The reason is that in Microsoft Office, the same property is also used for other controls, with an extended semantics (there are additional possible values then, e.g. fmSpecialEffectRaised etc.). Since we do not have an equivalent for this extended semantics, we prefer consistency within OpenOffice.org (with the Border property) over consistency with Microsoft Office.

In Microsoft Office documents, there is no equivalent to the Toggle property we will introduce for Push Buttons. Instead, Microsoft Office knows a dedicated control type name Toggle Button, which behaves exactly like a ordinary button, except that it can be toggled.

Detailed Specification

There are two groups of changes to the properties of form controls: First, properties which are already known (and used) for certain control types will be supported by a broader variety of form controls than before. Second, some form controls will get completely new properties with new semantics.

Refitting controls with known properties

Word break

The boolean Word break property, as known from the Label Field , is made available for the Push Button, Option Button, and Check Box control types, too. That is, if this property is set to Yes, then text in those controls will repeatedly be wrapped into the next line, if it does not fit into the current line and there is enough space for a next line.

Background color

The Background color property, with the well-known semantics, will be made available for the Check Box and the Option Button control types.

Alignment

The Alignment property, known from all text input controls, will be made available for List Boxes and Combo Boxes, as well as for Push Buttons, Option Buttons, and Check Boxes. See the chapter "Form controls with Images and Text" for more details on how this new property interacts with the Image align property for those controls where both are available.

New simple control properties

Toggle (Push Button)

A new boolean property Toggle will be introduced for Push Button controls. In the property browser, it will displayed immediately after the Repeat Delay property.

If set to No (which is the default applied to newly created Push Buttons), the button will behave as usual, i.e. a single mouse click (or pressing the space key one time) will trigger the button (and thus any possibly associated action, such as submitting a form).

If Toggle is set to Yes, the button control will behave as follows:

A single mouse click (or pressing the space key once, while the control has the focus) toggles the control between the two states "selected" and "not selected" . Together with the fact that a button can be pressed (When the user presses the mouse over the button, it is "pressed" as long as the mouse is not released, and the mouse pointer hovers over the control), this gives us four possible state combinations, whose appearance can be seen in Illustration 1.

Illustration 1 Four possible states of a Push Button

Note 1: The "not selected" states are depicted for the sake of completeness only, they're not newly introduced.

Note 2: The difference between the "selected pressed" and "selected not pressed" states is rather small, only the text is moved a few pixels.

The Before commencing or When initiating events of a Push Button (with Toggle set to Yes) are called when a toggle operation is completed, that is, when the mouse button or key which initiated the toggling is released.

String list

Item	English	German	Comments
Fixed text	Toggle	Umschalten	see Illustration 6 for information where this string will appear

Take Focus on Click (Push Button)

A new boolean property Take Focus on Click will be introduced for Push Button controls. In the property browser, it will displayed immediately after the Toggle property.

If set to No, the button can be operated (i.e. clicked) with the mouse without grabbing the focus. If set to Yes (which is the default for newly created Push Buttons), then clicking onto the button with the mouse gives the focus to it, as soon as the mouse is released

String list

Item	English	German	Comments
Fixed text	Take Focus on Click	Fokussieren bei Klick	see Illustration 6 for information where this string will appear

Hide selection (text input controls)

Sometimes, it's desirable to have a visual feedback about the selected text in an input field, even if this field currently does not have the focus. OpenOffice.org 1.x text input controls always hide their selection when they lose the focus.

With the newly introduced boolean property Hide selection, the designer of a form can customize this behavior. When it's set to Yes (which is the default for newly created controls), the controls behave as ever: Selections are only visually indicated as long as the control has the focus. If the property is set to No, then the selection (if any) will always be visible.

In the property browser, Hide selection will displayed immediately after the Password character property.

String list

Item	English	German	Comments
Fixed text	Hide selection	Auswahl verstecken	see Illustration 6 for information where this string will appear

Style (Check Box, Option Button)

Up to OpenOffice.org 1.x, the images which are used by Check Boxes and Option Buttons to indicate their current selection respectively check state (check/selected, unchecked/not selected, indetermined) are fixed, and not customizable by the user. This is especially sad since the images used have a 3D look, which makes it impossible to create a form containing controls with consistent layout, if this layout should not include 3D effects.

A new property will be introduced for both Check Boxes and Option Buttons, named Style. It allows a list selection between the two values 3D and Flat. If set to 3D (which is the default for newly created controls), then the controls will look as before. If set to Flat, the images will be replaced with versions which do not show the 3D effects.

In the property browser, Style will displayed immediately after the Character set property.

Since Table Controls also support columns which are displayed as a checkbox, those columns will also be refit with the new Style property.

String list

Item	English	German	Comments
Fixed text	Style	Stil	see Illustration 6 for information where this string will appear
List Box entry	3D	3D	This is the same wording as currently used for the possible Border values, to reach consistency. fs->liz: I strongly suggest to replace the German version with a string which is really German – both in this case here, and for the Border property.
List Box entry	Flat	Flach	This is the same wording as currently used for the possible Border values, to reach consistency.

In general, 6 bitmaps are needed for Option Buttons, and 9 for Check Boxes: The control can be one of the three mentioned states "check"/"selected", "unchecked"/"not selected", "indetermined", and this can be combined with each one of the following operating states:

The control is currently not being operated.

The mouse has been pressed over the control/bitmap, not yet released, and is still hovering over the control.

The control is disabled.

See Illustration 2 and Illustration 3 for a list of all possible bitmaps for both control types.

Illustration 2 visual representations of the possible Option Button states Illustration 3 visual representations of the possible Check Box states

Border color

A new property Border color will be introduced for all controls types which support Border. It allows choosing an arbitrary color which is used to paint the border, in the very same way (with a color list box) as this is done for other color properties, for example Background color.

The setting of Border color is only respected when Border is set to Flat. Thus, if Border is anything else than Flat, the Border color input elements will be disabled.

In the property browser, Border color will displayed immediately after the Border property.

String list

Item	English	German	Comments
Fixed text	Border color	Umrandungsfarbe	see Illustration 6 for information where this string will appear

Form controls with Images and Text

The support for images in form controls, which are shown together with text, will be extended. Up to OpenOffice.org 1.x, only Push Buttons were able to show both text and image, with four possible relative alignments between the image and the text.

With OpenOffice.org 2.0, you can assign images (additionally to the already present text) to Push Buttons, Option Buttons, and Check Boxes. Furthermore, you can specify one of 13 possible alignments for the image, relative to the text.

For this, the list of possible values of the Graphics Alignment property , which specifies how the image is aligned relative to the text, is extended to contain the following choices: Above left, Above centered, Above right, Below left, Below centered, Below right, Left top, Left centered, Left bottom, Right top, Right centered, Right bottom, centered. See below for details on how a control is laid out for each of those alignments.

The default value for newly created controls will be Above centred.

String list

Item	English	German	Comments
List Box Entry	Above left	Oben links	
List Box Entry	Above centered	Oben zentriert	
List Box Entry	Above right	Oben rechts	
List Box Entry	Below left	Unten links	
List Box Entry	Below centered	Unten zentriert	
List Box Entry	Below right	Unten rechts	
List Box Entry	Left top	Links oben	
List Box Entry	Left centered	Links zentriert	
List Box Entry	Left bottom	Links unten	
List Box Entry	Right top	Rechts oben	
List Box Entry	Right centered	Rechts zentriert	
List Box Entry	Right bottom	Rechts unten	
List Box Entry	Centered	Zentriert	

see Illustration 6 for information where those strings will appear

Control Layout

For all control types which support both images and text, the following rules apply when laying out the control:

If no image is set at all, the text is laid out as usual, respecting the Alignment and Word break settings, if necessary.

The image area's width/height is the minimum of the image width/height, and the width/height (respectively) of the content area. That is, if the image is wider/higher than the content area, the image area is as wide/high as the content area. Else, it is as wide/high as the image.

The text area has at least the size needed to output the text (respecting a possible Word break setting), but is not larger than the content area.

If Graphics Alignment is one of the Above *, Below *, Left *, or Right * values, then the the following holds:

image area is placed above, below, at the left of, at the right of the text area, respectively.

The image area is aligned with the text area as specified by the second part of the Graphics Alignment value, which means that either the left, the right, the top, or the bottom border, or the horizontal/vertical axis of both areas are aligned.

If Graphics Alignment is Centered, then both the image and the text area are centered horizontally and vertically within the content area.

Within the text area, the text is always respecting the Alignment setting (Left, Center, Right).

If the union of the text and the image area is not wider than the content area, then the positioning of this union within the content area will respect the Alignment setting.

If there's not enough room for both the image and the text, drawing the image is preferred over drawing the text.

Below are some samples for illustrating these layout rules.

Illustration 4 An option button with Graphics Alignment = Above left and Alignment = Center Illustration 5 An option button with Graphics Alignment = Right top and Alignment = Right

Compatibility

In OpenOffice.org 1.x, the Graphics Alignment property for Push Buttons had 4 possible values: Left, Right, Top, Bottom. To guarantee interoperability between different OpenOffice.org versions, the old values need to be mapped to new values. The following table defines this mapping:

OpenOffice.org 1.x	→OpenOffice.org 2.0	→ OpenOffice.org 1.x
	Left top	Left
Left	Left centered	Left
	Left bottom	Left
	Right top	Right
Right	Right centered	Right
	Right bottom	Right
	Above left	Top
Top	Above centered	Top
	Above right	Top
	Below left	Bottom
Bottom	Below centered	Bottom
	Below right	Bottom

Future Tasks

The changes described in this document do not cover all differences between form controls in Microsoft Office and form controls in OpenOffice.org. Though they cover a lot of the most important visual aspects, there's a longer way to go. See the documents section at dba.openoffice.org for a document which analyses the missing functionality in OpenOffice.org's form controls in detail.

References

http://dba.openoffice.org/files/documents/13/1553/control_properties.sxc contains an analysis of form control interoperability issue

http://dba.openoffice.org/specifications/forms/prop_browser_enhancements.sxw is a specification for various changes to the property browser done for OpenOffice.org 2.0.

Appendix

For the linguistic review, Illustration 6 shows a screenshot of the property browser, which exemplarily is inspecting a Push Button. All new properties described in this document will appear in the property browser.

Illustration 6 Property browser for a Push Button

In OpenOffice.org 1.x, this was (misleadingly) named Multiline input.

Note that in OpenOffice.org's dialog editor, you can already create buttons which permanently are in the "selected" state

Note that in OpenOffice.org 1.x, this property was named Alignment, but renamed in the course of changes to the property browser described in the Property Browser Enhancements specification.

Form Controls: Interoperability I

Page 9

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

2004-04-14T14:28:21