A Rich Text Form Control

Database Access

Document - ID	Specification Owner	Last Change	Status
	Frank Schönheit	2005-02-17	Final
Conforms to	
Applies to	all OpenOffice.org applications with a form layer
Task ID(s)	24385, 24386, 24387, 24388, 24389, 24390, 37338
Category	Feature

Abstract

Current form controls in OpenOffice.org offer very limited formatting possibilities only. A format (e.g. bold or italic text, font color, alignment of paragraphs, etc.) can only be applied to the whole text of a control, not to particular parts of it.

We will offer a new form control type, which can be embedded into all OpenOffice.org applications facilitating a form layer, and offers the user the possibility to edit so-called rich text.

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-03-17
Development		
Quality Assurance	Marc Neumann	2004-03-16
Documentation	Uwe Fischer	2004-03-16
String Review		

Document Change History

Rev. Level	Change	Initials	Date
1.0	final revision	FS	2004-03-17
1.0.1	incorporated changes from string review	FS	2004-04-06
1.0.2	consolidated the toolbar chapter, now that an application-wide toolbar specification is in-place	FS	2005-02-17

Contents

Glossary	1

Legend	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	Features	2

4.1.1	Character attributes	2

4.1.2	Paragraph attributes	2

4.1.3	Miscellaneous	2

4.2	Appearance and Behavior	3

4.2.1	Context Menu	3

4.2.2	Keyboard handling	4

4.2.3	Printing	4

4.2.4	Printer-dependent layout	4

4.2.5	Font	4

4.3	Integration into the host application	5

4.3.1	Text Box Formatting Toolbar	5

4.3.2	Font Attributes dialog	6

4.3.3	Paragraph Attributes dialog	6

4.4	Form Design User Interface	7

4.4.1	New control properties	7

4.4.2	Removed properties	8

4.4.3	Property dependencies	8

4.5	UNO API	9

4.6	File format	9

4.6.1	Definition	9

4.6.2	Writing	9

4.6.3	Reading	9

4.6.4	Compatibility	10

4.7	Future Tasks	10

5	Notes	10

6	References	10

Glossary

Term	Description
rich text	text which has detailed formatting information associated with it, e.g. font attributes (bold, italic, color, size) and paragraph attributes (such as alignment). Different portions of the text may have different (and completely independent) formatting attributes associated with them.
host application	for form controls, this is the application type (Writer, Calc, Impress) which belongs to the document type where the form controls are embedded
host document	for form controls, this is the concrete document where the controls are embedded
property browser	A UI component for inspecting and modifying (form related) objects such as controls and logical forms.
form component	a form control (more technically, and more precise: a control model), or a logical form. Controls can appear in any of OpenOffice.org's document types.
actuating property	a property of a → form component whose actual value has an effect on either the availability, or the value range, or the display of another property
depending property	a property of a → form component whose availability, or value range, or display depends on the actual value of another property

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 property value, as to be seen in the property browser.

Motivation

Current form controls in OpenOffice.org offer very limited formatting possibilities only. A format (e.g. bold or italic text, font color, alignment of paragraphs, etc.) can only be applied to the whole text of a control, not to particular parts of it.

Editing rich text (in the sense that formattings can be applies to isolated portions of the text) is desirable for various reasons. Not the least, if OpenOffice.org should support business workflows, it needs good form capabilities, which also includes rich text editing.

Goals

The goal is to provide a form control which allows editing of rich text, and seamlessly integrates into the host application (by e.g. using the toolbar functionality of the host application).

Requirements and Dependencies

Requirements

For the integration into the applications, the new toolbox concept needs to be taken into consideration.

Technical Dependencies

n / a

Detailed Specification

Though in the scope of this document, we are talking about a rich text control, we will not introduce a new dedicated control. Instead, we will refit the existing text field with a new mode, in which it allows entering formatted text. For more information about how the modes are switched, see chapter "New control properties".

So whenever the speech is about the "rich text control", we in real mean the new mode of the existing text field.

Features

As a general note, with the rich text control the user has nearly the same formatting possibilities as she has, for instance, with the text in shapes (e.g. an rectangular shape in a text document).

The available formattings divide into character attributes and paragraph attributes, depending on for which text unit (character or paragraph) they can be applied.

Character attributes

The following well-known character attributes are available for the text in a rich text control:

Font, Font style (bold/italic), Font size, Font Language, Underlining, Strikethrough, Text line color, Font color, Word line mode, Relief, Outline, Shadow, Position (Superscript/Subscript), Scaling, Kerning.

Additionally, the following character attributes are available when Asian Language support is enabled in the OpenOffice.org installation: Emphasis mark, Emphasis mark position.

Yet more additionally, the attributes Font, Font style, Font size and Font Language are available in an Asian and/or complex text version, if and only if "Asian language support" respectively "Complex text layout support" is enabled in the OpenOffice.org installation.

The semantics of these attributes follows their semantics in other contexts, for instance when used for the text in a shape. The reader is referred to the "Character" dialog for such text, in particular the well-known tab pages "Font", "Font effects", and "Position". Every attribute on these tab pages will be supported by the rich text control, and every attribute supported by the rich text control will be available on these tab pages.

Paragraph attributes

The following well-known paragraph attributes are available for the text in a rich text control:

Indent (Before text, After text, First line), Spacing (Above/Below paragraph), Line spacing, Alignment.

The semantics of these attributes follows their semantics in other contexts, for instance when used for the text in a shape. The reader is referred to the "Paragraph" dialog for such text, in particular the well-known tab pages "Indents & Spacing" and "Alignment". Every attribute on these tab pages will be supported by the rich text control, and every attribute supported by the rich text control will be available on these tab pages.

Additional paragraph settings are available when Asian language support is enabled in the OpenOffice.org installation. See chapter "Paragraph Attributes dialog" for more details on this.

Miscellaneous

The control does not support multi selection of text, nor does it support being bound to a database field.

Appearance and Behavior

In this new mode, the control displays, and allows editing, of text with associated formatting information. Illustration 1 shows an example for a rich text control.

Illustration 1 example of a rich text control

Context Menu

The rich text control supports a context menu, which is opened in the usual way. it's structure is shown in Illustration 2 to Illustration 5.

The "Font" and "Size" sub menus are not shown in this illustration, since they're filled automatically (at runtime) with the available fonts and sizes, as it happens with all menus of this type in every OpenOffice.org application.

All items in the context menu are pretty self-explaining, since they're reused from other places in OpenOffice.org, where the same functionality is offered in different contexts. Thus, the semantics of the menu items is not explained in detail here.

Illustration 2 main context menu Illustration 3 context menu - "Style" sub menu Illustration 4 context menu – "Line Spacing" sub menu Illustration 5 context menu – "Alignment" sub menu

String list

Item	English	German	Comments
menu entry	~Font	Sc~hrift	
menu entry	~Size	~Größe	
menu entry	St~yle	Sti~l	
menu entry	Bol~d	~Fett	
menu entry	~Italic	~Kursiv	
menu entry	~Underline	~Unterstreichen	
menu entry	~Strikethrough	~Durchstreichen	
menu entry	Shado~w	~Schatten	
menu entry	~Outline	K~ontur	
menu entry	Su~perscript	~Hochstellen	
menu entry	Su~bscript	~Tiefstellen	
menu entry	~Alignment	Aus~richtung	
menu entry	~Left	~Links	
menu entry	~Right	~Rechts	
menu entry	~Centered	~Zentriert	
menu entry	~Justified	~Blocksatz	
menu entry	~Line Spacing	Zeilenabs~tand	
menu entry	~Single	~Einzeilig	
menu entry	~1.5 lines	1,~5zeilig	
menu entry	~Double	~Zweizeilig	

Note that all these strings are re-used from other places in OpenOffice.org, where they're already used in the same way with the same semantics.

This context menu is the same all the time, no matter into which application the control is embedded.

Keyboard handling

Since the tabulator character is a valid character to be contained in rich text, we cannot use the TAB key to travel out of a rich text control (as we do with nearly all other form controls). Instead, when a rich text control is focussed, then pressing Ctrl+Tab moves the focus to the next, and Shift+Ctrl+Tab moves it to the previous control in the tabbing order. This behavior is consistent with the table form control, which also cannot use the TAB key for focus traveling.

Printing

The control is printable, i.e. if the Print property (also see chapter "New control properties") is set to true, the control content, with all formatting, appears on the document printout.

Printer-dependent layout

If a rich text control is embedded into a OpenOffice.org text document, it will respect the rendering reference device of the host document.

That is, the control will respect the "Use printer dependent metrics for document formatting" option (to be found in Tools|Options|Text document|Compatibility): If switched on, the text control will render it's content according to the document printer, if switched off, the control will render it's content according to the screen.

Font

In general, different portions of a rich text can be differently formatted. However, text portions to which the user did not explicitly assign a format have to be displayed in a default format. More precise, all character attributes (see chapter "Character attributes") have to be defaulted to certain reasonable values. These defaults are to be used for all such text portions which the user did not format herself, in particular, they are to be applied for newly entered text in a control which has just been created.

This default format will we determined at the time the control is being created. At this time, the document into which the control is being inserted is examined for a default font In all applications, it is taken from a "Default" style in the document. The style family which is used varies with the application, and is shown in the following table:

application	used style family
OpenOffice.org Writer	paragraph styles
OpenOffice.org Calc	cell styles
OpenOffice.org Impress	graphic object styles
OpenOffice.org Draw	graphic object styles

So, when a text field is created, no matter whether it's initially in rich text mode or not, the fonts which are used in rich text mode are immediately determined from a "Default" style of the host document. This holds for all three possible fonts: Western, Asian, and Complex text.

Integration into the host application

A rich text control integrates seamless into the host application, in the sense that any toolbar and menu functionality which deals with character or paragraph attributes, and which is normally applied to the host application, applies to the rich text control as long as it has the focus.

For instance, if a rich text control, embedded in a Writer document, is focused, then the "Bold" indicator in the object bar follows the "Bold" attribute of the cursor/selection in the control. I.e., the respective toolbar button is checked if the text is bold, unchecked if it isn't, and in indetermined state if the selected text in the control contains both bold and non-bold portions.
Additionally, if the "Bold" item in the object bar is pressed (or if the respective menu entry is chosen), then this is applied to the cursor/selection in the control as usual.

The same holds for the "Cut", "Copy", "Paste", and "Select All" functionality in both the main toolbar and the menu: As long as a rich text control is focused, they affect this control, and the text therein, rather than the host document.

As a canonic extension, this also applies to all other controls which allow input of text of any kind, for instance numeric fields. Note that this offers an improvement over the situation in OpenOffice.org 1.x, where those functionality's still applied to the host document, even if a control was focused, which was a very irritating behavior.

Text Box Formatting Toolbar

A new toolbar will be introduced in the course of this implementation, which is shown in Illustration 6.

Illustration 6 Text Box Formatting Toolbar

The toolbar is described in more detail in the OpenOffice.org Toolbar Content Specification.

String list

Item	English	German	Comments
List Box Entry / Menu Entry	Text Box Formatting	Textfeld Formatierung	to reach this: Choose "Customize" in the context menu of an arbitrary toolbar, in the dialog which then opens, drop down the "Toolbars" listbox in the upper left corner.

This object bar is shown as soon as a control which allows text input is focused. Note that this explicitly includes controls other that rich text controls, e.g. Numeric Fields.

Font Attributes dialog

When the "Font Attributes" item is chosen from the Form Object Bar, a dialog is offered to the user to change all font attributes at once. The dialog consists of the usual tab pages "Font", "Font Effects", and "Position". These pages and their functionality are not described in the scope of this document, since they're already existent in other contexts, and simply reused here. The dialog is shown in Illustration 7.

Illustration 7 Font Attributes Dialog

String list

Item	English	German	Comments
dialog title	Character	Zeichen	
tab page title	Font	Schrift	
tab page title	Font Effects	Schrifteffekt	
tab page title	Position	Position	

Paragraph Attributes dialog

When the "Format: Paragraph" item is chosen from the Form Object Bar, a dialog is offered to the user to change all paragraph attributes at once. The dialog consists of the usual tab pages "Indents & spacing", "Alignment", and "Tabs". These pages and their functionality are not described in the scope of this document, since they're already existent in other contexts, and simply reused here. The dialog is shown in Illustration 7.

When Asian language support is enabled in the OpenOffice.org installation (Tools|Options|Language Settings|Languages|Asian Language Support), then additionally, the tab page "Asian Typography" is visible.

Illustration 8 Paragraph Attributes dialog

String list

Item	English	German	Comments
dialog title	Paragraph	Absatz	
tab page title	Indents & Spacing	Einzüge und Abstände	
tab page title	Alignment	Ausrichtung	
tab page title	Asian Typography	Asiatische Typographie	
tab page title	Tabs	Tabulator	

Form Design User Interface

New control properties

Two new control properties will be introduced to cover the new features of the text field.

Text type

The Text type property replaces the existing Multiline property. It allows the user to chose from a list of values, namely Singleline, Multiline, and Multiline with formatting. The following mapping from old property values to new property valuesapplies:

OpenOffice.org 2.0	OpenOffice.org 1.x
Text type = Singleline	Multiline input = No
Text type = Multiline	Multiline input = Yes
Text type = Multiline with formatting	n/a

When Multiline with formatting is chosen, the control acts as rich text control, with all the features described in this document.

Automatic line break

The Automatic line break property specifies whether the text is automatically wrapped when the line end is reached. If set to Yes, which is the default, then implicit (so-called soft) line breaks are inserted into the text so that it does not exceed the control width, if possible. Explicit (hard) line breaks can, independent on the value of this property, always be entered by pressing the Enter key.

String list

Item	English	German	Comments
Fixed Text	Wrap text automatically	Automatischer Zeilenumbruch	This is the same wording as on the "Alignment" tab page of the "Format cell" dialog in OpenOffice.org Calc.
Fixed Text	Text type	Texttyp	
List box entry	Single-line	Einzeilig	
List box entry	Multi-line	Mehrzeilig	
List box entry	Multi-line with formatting	Mehrzeilig mit Formatierung	

Removed properties

Multiline input

The Multiline input property is superseded by Text type.

Property dependencies

Some properties which already exist for the Text field do not apply (or make sense) for a rich text control. For instance, a rich text control will not respect the Max. text length or the Alignment property.

With recent changes to the property browser, it is possible to make the the user aware of such interdependencies, by disabling properties which are not available with the current control settings. This feature is faciliated for the rich text control, too.

The following table lists all property relations where a depending property will be disabled in case of particular property values of an actuating property:

actuating property	trigger condition	depending properties
Text type	== Multiline with formatting	Max. text length, Default value, Character set, Alignment, Password characters
Text type	<> Multiline with formatting	Automatic line break

In addition, all 3 properties of an text field which are related to binding the control to a database field would need to be disabled in case of a rich text control, since it's currently not supported to store formatted text in a database field. However, this would lead to a Data tab page which contains only disabled controls. Thus, the complete tab page will be hidden for a rich text control, and shown for both other text types.

UNO API

The UNO service com.sun.star.form.component.TextField will be extended to optionally support the service com.sun.star.text.Text.

File format

Definition

As multiline text fields, rich text controls will be stored as form:textarea element. The definition of this element is extended, so that it is allowed to contain text:p elements.

The following modifications will be made to the respective chapter of the file format documentation:

Text area

Text areas (form:textarea) are now allowed to contain more than simple text. For this, the element definition is extended as follows:

XML Code:	<form:textarea>
Rules:	
DTD:	<!ELEMENT form:textarea (form:properties?, office:events?, text:p*)> <!ATTLIST form:textarea %current-value; %disabled; %max-length; %printable; %readonly; %tab-index; %tab-stop; %title; %value; %convert-empty; %data-field;>

Note the additional text:p element: It specifies that 0 up to n text paragraphs can be associated with a text area, describing the contained text and it's formatting. If both the current-value and one or more text:p elements are present, it's up to the application reading the document which information preferred.

Though the format specification above (which is to become part of the OASIS XML file format) suggests that it's not defined whether a current-value attribute or a text:p element is preferred, in case both of them are present, we will explicitly define this for OpenOffice.org.

Writing

Upong writing an edit field, the current-value attribute will always be written. Since it contains the current (unformatted) text of the control, this ensures that older versions of OpenOffice.org, which cannot interpret the text:p element, can at least read the pure text, without formatting information. See chapter "Compatibility" for more information.

If and only if a text field acts as rich text control, OpenOffice.org 2.0 will write the text:p element, containing the full descriptions of the current text, including the formatting.

Reading

Upon reading a form:text-area element, OpenOffice.org 2.0 will use the presence of a text:p sub element to determine whether the resulting edit field should act as rich text control. If such an element is present, the Text type property of the read control will be set to Multiline with formatting, and the value of a possibly present current-value attribute will be ignored.

If no text:p sub element is present, Text type will be set to Multiline, and the current-value attribute will be used to determine the current text of the control.

Compatibility

OpenOffice.org versions up to 1.1 are able to read the documents written by OpenOffice.org 2.0, which contain rich text controls. Rich text controls will be imported as ordinary multiline text fields, preserving the text content, but losing all formatting information. Storing such a document in OpenOffice.org 1.x, and loading it in OpenOffice.org 2.0, will lead to a text field whose Text type property is set to Multiline.

When storing a document which contains a rich text control in the binary file format of StarOffice up to version 5.2, then those older StarOffice versions will also create a multi line text field upon reading the document.

Future Tasks

The Rich Text OLE control known in the windows world can be bound to a file, which then is edited in the control – changes made are stored back to the file. It may be worth implementing this for our control, too.

Currently, rich text controls cannot be bound to database fields, which could be changed.

The control does not yet support bullets, which also holds for all other places using the same core implementation (text in shapes, text in spreadsheet cells). If the EditEngine (the core class providing this functionality) would support bullets, the rich text control could inherit this, too.

Notes

References

Toolbar concept: http://specs.openoffice.org/ui_in_general/toolbars/openoffice_org_toolbar_spec.sxw

A Rich Text Form Control

Page 10

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

Frank Schönheit

2004-01-14T14:52:37