Navigation Bar Form Control

Database Access

Document - ID	Specification Owner	Last Change	Status
	Frank Schönheit	2004-07-15	final
Conforms to	
Applies to	OpenOffice.org Base
Task ID(s)	24409, 24410, 24411, 24412, 24413, 24414
Category	Feature

Abstract

This document specifies a form control which can be placed in any OpenOffice.org application supporting a form layer, and offers (nearly) all the functionality known from the Form Navigation Toolbar, such as navigating, filtering, and sorting a database form. An arbitrary number of instance of this control can be placed in a document, and the availability of functionality can be customized per control instance.

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

Approved for Implementation

	Approved by	Date
User Experience	cj@openoffice.org	2004-02-20
Development		
Quality Assurance	clu@openoffice.org	2004-03-03
Documentation	ufi@openoffice.org	2004-02-17
String Review		

Document Change History

Rev. Level	Change	Initials	Date
0.8 – draft	initial public revision	FS	
1.0	added proper icons added approvals	FS	2004-03-09
1.0.1	incorporated changes from linguistic review	FS	2004-04-05
1.0.2	Changed english text "Record Actions" to "Acting on a record" (30912) properly assigned some items to the "Actions" category	FS	2004-07-15

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	Look and Feel	2

4.2	Form Design User Interface	2

4.2.1	Creating a navigation bar control	2

String list	3

4.2.2	Control properties	3

Reused properties	3

Newly introduced properties	3

String list	3

4.2.3	Control events	4

4.3	Navigation Bar Items	4

String list	9

4.4	Future Tasks	10

5	References	10

Glossary

Term	Description
associated form	The form which a navigation bar control belongs to, and which it operates on. Technically, the parent object of navigation bar control model.

Motivation

Users often require to design forms which offer navigation functionality (such as "move to next record") by means other than the usual form navigation bar. The current solution for this need is to bind a command button to a Basic macro which either plays a pre-recorded macro, or explicitly scripts the RowSet component of the form document. Both approaches have one or more of the following disadvantages:

The command button is not automatically enabled or disabled according to the form state. E.g., when the form is positioned on the first record, it's impossible to execute the "move to previous record" functionality. Reflecting this impossibility in the state of the button requires additional scripting work and is error-prone.

The command button is unable to care for the complete form state. E.g. when the form which is to be navigated contains a uncommitted control, this cannot be detected from within a Basic macro, and simply moving the RowSet pointer loses the uncommitted content.

Macros which simply play a pre-recorded macro only work on the active form. It's not possible with this approach to create a macro which properly works on a fixed form (in a document containing more than one form), independent on whether this form is active or not.

The functionality specified herein does overcome all these disadvantages.

Additionally, the implementation which is necessary for the functionality described herein requires significant changes to OpenOffice.org's default implementation for form controller functionality. In particular, a lot of this functionality is to be moved out of the drawing layer implementations, into the UNO service where they semantically belong to. This is a requirement for possible future implementations, such as database forms which are not part of a host application (such as OpenOffice.org Writer), but live on their own (e.g. as UNO dialog).

Goals

Provide as much as possible form controller functionality (such as form navigation, filtering, and sorting) as a form control which can be added to any database form.

Prepare complete isolation of the FormController service and functionality from the drawing layer.

Requirements and Dependencies

Requirements

n/a

Technical Dependencies

n/a

Detailed Specification

A navigation bar control acts as quick access for functionality which is related to the logical form it belongs to. For instance, using a navigation bar control, you can move the associated form to the next record, or filter it.

Look and Feel

The control will look like the toolbars known from OpenOffice.org's user interface. Illustration 1 shows a navigation bar control with all functionality visible and enabled.

Illustration 1 Navigation Bar control

The texts in the bar will be localized. See chapter Navigation Bar Items for more explanation on the items of the tool bar.

Items

Like every toolbar in OpenOffice.org, the form navigation bar consists of a number of items, where each item fulfills a special functionality. There exist 5 types of items:

passive text: only used to display information

input field: an field which can be focussed by the user, and where numeric values can be entered

repeating button: A button which, when clicked, executes a particular action. When the the user keeps the mouse pressed over the button, the action is repeatedly executed.

button: A button which, when clicked, executes a particular action. The mouse key must be released and pressed again to trigger the same action again.

toggle button: A button which is associated with a boolean state, which is indicated by the button being pressed or not pressed. Clicking the button once toggles between both states.

Alignment

A navigation bar control may be higher or wider than the space actually occupied by its items. In this case, the set of items is aligned at the left hand side, and all items are vertically centered in the control.

Navigation Bar Items

Below, we will list all these items, together with their characteristics, in the order in which they appear in the control (left-to-right).

Note that every item has a category associated with it. All items of a category can be shown or hidden using the respective properties of the control (see chapter Control properties).

Items where the description states "Reload = Yes" need, will, when executed, explicitly or implicitly reload the form. As a consequence, the form will be positioned on the first record after execution of the item.

For items whose description states "Commit = Yes", the following is done before executing the action associated with this item: The current control is committed into the form's row, and the changes in the form are updated to the underlying database. The latter means that the current row is either updated or inserted into the database. If there's an error in either committing the control or the form's row, the action associated with the item is not executed.

For items whose description states "Commit = on demand", committing the current control and updating the form's current record is done after asking the user with a dialog shown in Illustration 2.

Illustration 2

When the user choses "Yes", the changes to the current control/record are saved before executing the action which is associated with the toolbar item, when s/he choses "No", the action is executed after discarding the changes, when s/he choses "Cancel", the action is not executed at all, and the form is not touched. Note that this dialog is not newly introduced for the navigation toolbar, but already present in OpenOffice.org.

Record label

Type	passive text
Semantics	display a label for the subsequent item
Text	Record
Category	Position

Record position

Type	numeric input field
Semantics	displays the number of the current record of the associated form, and allows quick navigation to a record given by it's number.
Tool tip text	Absolute record
Category	Position
Commit	Yes

This item can be focused, and the user can enter a record number here. Upon pressing the return key, and upon losing the focus, the associated form will be moved to the record given in the input field. if there is no record with the given number (e.g. if the user entered "100" in a form which has only 90 records), nothing happens.

Record count label

Type	passive text
Semantics	display a label for the subsequent item
Text	of
Category	Position

Record count

Type	passive text
Semantics	displays the number of records in the form
Tool tip text	Total Number of Records
Category	Position

This item constantly displays the number of records in the form.

For every form it holds that until all records have been visited, the record count as known so far is not reliable. The item will indicate this by placing an asterisk after the record count. E.g., it will display "11 *" if only 11 records are known, but there could be more.

First Record

Type	repeating button
Semantics	moves the associated form to the first record
Tool tip text	First Record
Icon	
Category	Navigation
Commit	Yes

Previous Record

Type	repeating button
Semantics	moves the associated form to the record record before the current one
Tool tip text	Previous Record
Icon	
Category	Navigation
Commit	Yes

Next Record

Type	repeating button
Semantics	moves the associated form to the record record after the current one
Tool tip text	Next Record
Icon	
Category	Navigation
Commit	Yes

Last Record

Type	repeating button
Semantics	moves the associated form to last record
Tool tip text	Last Record
Icon	
Category	Navigation
Commit	Yes

Save Record

Type	button
Semantics	saves the modifications done to the current record of the associated form.
Tool tip text	Save Record
Icon	
Category	Actions
Commit	Yes

Undo

Type	button
Semantics	reverts the modifications done to the current record of the associated form
Tool tip text	Undo: Data Entry
Icon	
Category	Actions

New Record

Type	button
Semantics	moves to the insertion row of the associated form
Tool tip text	New Record
Icon	
Category	Actions
Commit	Yes

Delete Record

Type	button
Semantics	deletes the current record of the associated form
Tool tip text	Delete Record
Icon	
Category	Actions

Refresh

Type	button
Semantics	reloads the associated form
Tool tip text	Refresh
Icon	
Category	Actions
Reload	Yes
Commit	on demand

Sort Ascending

Type	button
Semantics	sorts the associated form ascending, by the column which the currently focused control is bound to. Any previous sorting of the form is overridden.
Tool tip text	Sort Ascending
Icon	Korean:
Category	Filter & Sort
Reload	Yes
Commit	Yes

Sort Descending

Type	button
Semantics	sorts the associated form descending, by the column which the currently focused control is bound to. Any previous sorting of the form is overridden.
Tool tip text	Sort Descending
Icon	Korean:
Category	Filter & Sort
Reload	Yes
Commit	Yes

Sort

Type	button
Semantics	opens a dialog which allows to enter multiple sort criterions for the associated form
Tool tip text	Sort...
Icon	Korean:
Category	Filter & Sort
Reload	Yes
Commit	Yes

The dialog which is opened is the same as known from the table data view, and which is also opened when pressing the "Sort..." button in the global form navigation bar of a form document. It can seen in Illustration 3.

Illustration 3

This dialog is not covered by this specification, since it's reused in various places in OpenOffice.org. Technically, the toolbar item simply instantiates and executes the UNO service com.sun.star.sdb.OrderDialog.

Automatic Filter

Type	button
Semantics	automatically filters the associated form. Form this, the criterion "<column> = <value>" is appended (as conjunction) to the current filter of the form. <column> and <value> are determined by the currently focused control of the form: <column> is the name of the form column which it is bound to, and <value> is the current value of the control.
Tool tip text	AutoFilter
Icon	
Category	Filter & Sort
Reload	Yes
Commit	Yes

Default Filter

Type	button
Semantics	opens a dialog which allows to enter multiple filter criterions for the associated form
Tool tip text	Default Filter...
Icon	
Category	Filter & Sort
Reload	Yes
Commit	Yes

The dialog which is opened is the same as known from the table data view. It can seen in Illustration 4.

Illustration 4

This dialog is not covered by this specification, since it's reused in various places in OpenOffice.org. Technically, the toolbar item simply instantiates and executes the UNO service com.sun.star.sdb.FilterDialog.

Apply Filter

Type	toggle button
Semantics	quickly allows to disable or enable the current filter of the associated form
Tool tip text	Apply Filter
Icon	
Category	Filter & Sort
Reload	Yes
Commit	Yes

When this button is pressed, the filter of the associated form is enabled. When it's not pressed, the filter is disabled, but still present. This allows to quickly see the unfiltered results of the form, without the need to completely remove (and later re-create) the filter.

Remove Filter and Order

Type	button
Semantics	completely removes the filter and the sorting order from the associated form.
Tool tip text	Remove Filter/Sort
Icon	
Category	Filter & Sort
Reload	Yes
Commit	Yes

When this button is pressed, the filter of the associated form is enabled. When it's not pressed, the filter is disabled, but still present. This allows to quickly see the unfiltered results of the form, without the need to completely remove (and later re-create) the filter.

String list

Item	English	German	Comments
Toolbar text	Record	Datensatz	see 1. below
Toolbar item tool tip	Absolute record	Datensatznummer	see 1. below
Toolbar text	of	von	see 1. below
Toolbar item tool tip	Total No. of Records	Zahl der Datensätze	see 1. below
Toolbar item tool tip	First Record	Erster Datensatz	see 1. below
Toolbar item tool tip	Previous Record	Vorheriger Datensatz	see 1. below
Toolbar item tool tip	Next Record	Nächster Datensatz	see 1. below
Toolbar item tool tip	Last Record	Letzter Datensatz	see 1. below
Toolbar item tool tip	Save Record	Datensatz speichern	see 1. below
Toolbar item tool tip	Undo: Data Entry	Rückgängig: Dateneingabe	see 1. below
Toolbar item tool tip	New Record	Neuer Datensatz	see 1. below
Toolbar item tool tip	Delete Record	Datensatz löschen	see 1. below
Toolbar item tool tip	Refresh	Aktualisieren	see 1. below
Toolbar item tool tip	Sort Ascending	Aufsteigend sortieren	see 1. below
Toolbar item tool tip	Sort Descending	Absteigend sortieren	see 1. below
Toolbar item tool tip	Sort	Sortieren	see 1. below
Toolbar item tool tip	AutoFilter	AutoFilter	see 1. below
Toolbar item tool tip	Apply Filter	Filter anwenden	see 1. below
Toolbar item tool tip	Remove Filter/Sort	Filter/Sortierung entfernen	see 1. below
Alert box text	The content of the current form has been modified.\nDo you want to save your changes?	Der Inhalt des aktuellen Formulars wurde geändert.\nSollen die Änderungen gespeichert werden?	see 2. below

This item is currently also used in the form navigation bar, changes made here will also affect the texts there.

The text is currently already used, e.g. when a form document with modified controls is being closed.

Form Design User Interface

Creating a navigation bar control

A new icon will be added to the form functions toolbar, which can be used to create navigation bar form controls in an OpenOffice.org application supporting a form layer. The icon will be added to the very right of the upper row of the toolbar. The following icons will be used for this:

color scheme	toolbar size	icon
normal	small	
high contrast	small	
normal	large	
high contrast	large	

The tool tip for this icon will be "Navigation Bar".

In the form navigator, where every control type is represented by an own icon, the small toolbar icons will be reused.

The default name of a newly created scrollbar, as visible in the form navigator, will be "NavigationBar". If necessary, an 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.

The navigation bar icon (and thus the associated functionality of creating a navigation bar control) can be configured into toolbars and menus. In the respective configuration dialogs, the text for the functionality will be the same as the tool tip.

Furthermore, in the control conversion menu (which is a sub menu of the context menu of any control, and also appears in the context menu of the form navigator), an additional entry will be added which allows to convert any control into a navigation bar control. The text of this entry is the same as the text of the aforementioned tool tip.

String list

Item	English	German	Comments
Toolbar Tool tip	Navigation Bar	Navigationsleiste	
Logical Control Name	NavigationBar	Navigationsleiste	Translation! No spaces allowed in this string!

Control properties

Reused properties

A number of properties which exist for other form controls will be re-used with their well-known semantics. In particular, these are: Name, Border, Enabled, Tabstop, Order, Background color, Additional Information, Help text, Help URL.

Additionally, the Font property will be reused – it affects the font of the passive text labels in the control (see chapter Navigation Bar Items). Yet more additionally, the Delay property will be reused, too. It specifies the repeat delay for the repeating buttons in the control (see chapter Navigation Bar Items).

Newly introduced properties

The following properties are special to the navigation bar control:

Name	Type	possible values	semantics	Default value
Icon size	enumeration	Small / Large	specifies whether the icons in the toolbar should be small or large	Small
Positioning	boolean	Show / Hide	specifies whether items from the "Position" category should be shown (see chapter Navigation Bar Items)	Show
Navigation	boolean	Show / Hide	specifies whether items from the "Navigation" category should be shown (see chapter Navigation Bar Items)	Show
Acting on a record	boolean	Show / Hide	specifies whether items from the "Actions" category should be shown (see chapter Navigation Bar Items)	Show
Filtering / Sorting	boolean	Show / Hide	specifies whether items from the "Filter & Sort" category should be shown (see chapter Navigation Bar Items)	Show

String list

Item	English	German	Comments
Label (Property Name)	Icon size	Symbolgröße	
List Box Entry (Property Value)	Small	Klein	
List Box Entry (Property Value)	Large	Groß	
Label (Property Name)	Positioning	Positionierung	
Label (Property Name)	Navigation	Navigation	
Label (Property Name)	Acting on a record	Datensatzaktionen	
Label (Property Name)	Filtering / Sorting	Filter / Sortierung	

Illustration 5 navigation bar property browser

Control events

The following events, which are know from other form control types, are also available for the navigation bar form control, with their well-known semantics: 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.

Future Tasks

The navigation bar currently cannot provide the "Form based filter" and "Form as table" functionality's, which are known from the Form Navigation Toolbar. This is because those features are not to be executed relative to one FormController instance, as all other features provided by the navigation bar, but have to be implemented in the wider context of the whole document, which can contain multiple forms and controllers.

References

The functionality described herein is closely related to the Navigation Functionality for Command Buttons.

This property was known as Character set in OpenOffice.org 1.x, but has been renamed in the course to OpenOffice.org 2.0

Navigation Bar Form Control

Page 4

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

Frank Schönheit

2003-10-16T20:34:54