Form Navigation Functionality for Push Buttons

Database Access

Document - ID	Specification Owner	Last Change	Status
	Frank Schönheit	2004-04-05	final
Conforms to	
Applies to	OpenOffice.org Base
Task ID(s)	24415, 24416, 24417, 24418, 24419
Category	Feature

Abstract

Users often wish to create forms which offer form navigation functionality (such as "move to next record") by other means than the usual form navigation bar. The functionality described herein will allow for an easy possibility to bind the known push button controls to the most common navigation functionality.

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	initial public revision	FS	2004-02-01
1.0	changed "Load document" to "Open Document/Web Page" as to CJ's request added approvals	FS	2004-03-09
1.0.1	incorporated changes from linguistic review	FS	2004-04-05

Contents

1	Motivation	1

2	Goals	2

3	Requirements and Dependencies	2

3.1	Technical Dependencies / Requirements	2

4	Detailed Specification	2

4.1	New Push Button Actions	3

4.2	Automatic Availability	4

4.3	Event Handling	4

5	References	5

Glossary

Term	Description
bound control	a form control which is bound to a RowSet column
uncommitted control	a bound control whose content has been modified, while this modification has not yet been reflected to the → row set column which the control is bound to
database object	in the scope of this document: a table, a query, or an SQL command. A database object, together with a data source, is the minimum to define a → row set.
row set	a collection of rows as retrieved from one or more database tables, usually specified by a data source plus a → database object relative to this data source.
logical form	an instance of the com.sun.star.form.component.Form service which is part of the form component hierarchy of a document. Multiple logical forms can be part of one document, each bound to a different data source and → database object. A logical form is always also a → row set.
associated form	the → logical form which a form control belongs to. Technically, it's the parent form of the component. This relation can be seen in the Form Navigator tool in OpenOffice.org.
active form	the → logical form within a document which the currently focused control belongs to
insert row	a virtual row in a → row set which is used to insert a new record
Form Navigation Bar	the toolbar which automatically appears in every document with a form which is properly bound to a → database object.

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

Users often require to design forms which offer navigation functionality (such as "move to next record") by other means than the usual form navigation bar. The current solution for this need is to bind a push 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 push 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 push 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, even when this form is not active.

The functionality specified herein does overcome all these disadvantages.

Goals

The user will get an easier possibility to bind form navigation functionality to push buttons in form documents.

Requirements and Dependencies

Technical Dependencies / Requirements

Some of the prerequisites for this implementation are already present. Grid Controls in form documents already allow to route their navigation functionality through a central instance which both controls the states (enabled/disabled) of these functionality and executes it when requested.

This implementation has to be generalized so that the new implementation described herein can benefit from it, too.

Detailed Specification

OpenOffice.org already features different kinds of push buttons in a document: buttons for resetting or submitting a form, and buttons for loading a document specified by URL. To differentiate between these functionality's, the Button type property of a push button has to be set to the value Reset, Submit, or URL (while the default value for this property is Push, which refers to no special functionality at all).

This list of actions to be executed when the button is pressed will be extended with the feature described herein.

For this, the property itself as value as the possible values will be renamed as follows:

The property itself will be renamed to Action. This is to indicate that the property refers to the action which is to be automatically executed when the buttons is pressed.

The property value formerly known as Push is renamed to None.

The property value formerly known as Submit is renamed to Submit form.

The property value formerly known as Reset is renamed to Reset form.

The property value formerly known as URL is renamed to Open document / web page.

String list

Item	English	German	Comments
Label	Action	Aktion	
List box entry	None	Keine	
List box entry	Submit form	Formular übertragen	
List box entry	Reset form	Formular zurücksetzen	
List box entry	Open document/web page	Dokument/Webseite öffnen	

See Illustration 1 for the context of these strings.

Illustration 1 possible push button actions

New Push Button Actions

The list of possible actions for a push button will be extended with functionality related (not only) to navigating a form. The table below lists all new possible values, and describes the actions which, when the particular value is chosen, is executed when the button is clicked. In the property browser, the new values will be appended to the list of previously available values, in the order in which they appear in the table below.

Property Value	Associated action
First record	The associated form is moved to the first record.
Previous record	The associated form is moved to the record preceding the current one.
Next record	The associated form is moved to the record succeeding the current one.
Last record	The associated form is moved to the last record.
Save record	The current record of the associated form is saved, if necessary.
Undo data entry	The changes in the current record of the associated form are undone, without saving them.
New record	The associated form is moved to the insert row.
Delete record	The current record of the associated form is deleted.
Refresh form	The associated form will be reloaded.

Additional semantics apply to all of the actions above (such as that a move operation on the associated form always implicitly commits the current record, if necessary, or that the user is asked for confirmation before a record is deleted), which are not described here. The reason is that those semantics are already well-known from the Form Navigation Bar.

In a consequence, pressing a button whose Action property is set to First record, yields the very same result as pressing the "First record" button in the Form Navigation Bar. Similar, all other actions described herein have a counterpart in the Form Navigation Bar.

We will call push buttons whose Action property is set to one of the values above navigation buttons.

String list

Item	English	German	Comments
List box entry	First record	Erster Datensatz	see 1. below
List box entry	Previous record	Vorheriger Datensatz	see 1. below
List box entry	Next record	Nächster Datensatz	see 1. below
List box entry	Last record	Letzter Datensatz	see 1. below
List box entry	Save record	Datensatz speichern	see 1. below
List box entry	Undo data entry	Rückgängig: Dateneingabe	see 1. below
List box entry	New record	Neuer Datensatz	see 1. below
List box entry	Delete record	Datensatz löschen	see 1. below
List box entry	Refresh form	Formular aktualisieren	see 1. below

These strings equal the tool tips for the corresponding functionality in the Form Navigation Bar.

See Illustration 1 for the context of these strings.

Automatic Availability

Since not all actions can be executed all the time (e.g. a form cannot be moved to the insert row when the permissions of the underlying table to not permit adding data), navigation buttons are automatically enabled and disabled depending on the availability of their associated action.

For instance, if a button is to execute First record,then this button will be disabled as long as the associated form is already positioned on the first record.

Again, navigation buttons here follow the semantics of buttons in the Form Navigation Bar: a navigation button is enabled if and only if the corresponding button in the Form Navigation Bar would be enabled.

As a consequence, the semantics of the Enabled property of push buttons slightly changes: In case the push button is also an action button, the following holds

If Enabled is set to No, then the button is always disabled, independent of the availability of the associated navigation functionality.

If Enabled is set to Yes, and the associated navigation functionality is currently available, then the push button is enabled.

If Enabled is set to Yes, and the associated navigation functionality is currently not available, then the push button is disabled.

Event Handling

If a push button is associated with a navigation functionality, then the approve-listeners registered for the button are called before executing the navigation feature. In particular, if the user bound a Basic script to the Before commencing event of the button, this script is called before the feature is being executed. Also, the script method can veto the execution with returning false, as usual.

Also, action buttons do not call the ordinary action listeners (event When initiating) when their associated action is executed.

References

The functionality described herein is related to similar functionality which can be found in the navigation bar form control, whose specification is available here:
http://dba.openoffice.org/specifications/forms/navigation_bar.sxw.

Form Navigation Functionality for Push Buttons

Page 5

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

Frank Schönheit

2003-10-16T21:22:05