Property Browser Enhancements

Database Access

Document - ID	Specification Owner	Last Change	Status
	Frank Schönheit	2004-03-03	Final (1.0.3)
Conforms to	
Applies to	OpenOffice.org Base, Basic Dialog editor
Task ID(s)	22877, 22878, 23190, 23418, 22879, 22880, 22881, 24606
Category	Feature

Abstract

The property browser for modifying various aspects of form and dialog controls, as well as logical forms, has always been experienced as somewhat quirky, and hard to understand for the inexperienced user. The changes proposed in this document will introduce several enhancements to this situation, of varying severity.

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	Marc Neumann (MSC)	msc@openoffice.org
Documentation	Uwe Fischer (UFI)	ufi@openoffice.org

Approved for Implementation

	Approved by	Date
User Experience	Christian Jansen	2004-01-20
Development		
Quality Assurance	Marc Neumann	2004-01-16
Documentation	Uwe Fischer	2004-01-16
String Review	Elizabeth Matthis	2004-02-20

Document Change History

Rev. Level	Change	Initials	Date
1.0	Final	FS	2004-01-20
1.01	incorporated changes string review changes	FS	2004-03-01
1.02	minor changes during last prep-QA review	FS	2004-03-03
1.03	adjusted abstract (more appropriate for auto-generated What's-New-Guide)	FS	2004-03-03

Contents

1	Goals	1

2	Detailed Specification	2

2.1	Reordering and Renaming of properties	2

2.2	Cross property dependencies	3

2.2.1	Disabling Properties	4

2.2.1.1	Complex property dependencies	5

2.3	Easing value input	5

2.3.1	Defining the tabbing order	5

2.3.2	Date input	6

2.3.3	File URLs	7

2.3.4	List Boxes: choosing a (Default) Selection	7

2.3.5	Measurement units	8

2.3.6	Filtering and Sorting a Form	8

2.3.7	Binding a form to an SQL command	9

2.3.8	Sub Form Relations	12

2.3.8.1	Direct column name linking	12

2.3.8.2	Linking multiple column pairs	14

2.3.8.3	The "Link Fields" Dialog	14

2.4	Miscellaneous	16

2.4.1	Tab Order Dialog	16

3	Future Tasks	16

4	Notes	17

5	References	17

Glossary

Term	Description
property browser	A component for inspecting and modifying (form related) objects such as controls and logical forms.
(form) component	a form or dialog control (more technically, and more precise: a control model), or a logical form. Controls can appear in any of OpenOffice.org's document types, and in Basic dialogs. logical forms can appear in the former only.
inspection	the process of displaying and changing the properties of a → component in the → property browser
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
limit property	properties which define a limit for the value reflected in a control, e.g. Time min. and Time max. See also → value properties
value property	value properties describe the very actual content of a control. This could be Status, Text, Date, Time, Value, and Selection. Usually, for every value property there's also a default value property . Additional, numeric value properties (Date, Time, Value) usually have → limit properties associated with them.
format property	properties which affect how the actual value of a form or dialog control is displayed, e.g. Date format.
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
data source browser	The window which can be opened in both OpenOffice.org Writer and OpenOffice.org Calc by choosing the menu item "View|Data Sources", which displays a list of available data sources, and the data from one user-selected table or query.
sub form	a logical form which is the child of another logical form (note that the parent-child relationship can be seen in the form navigator), the so called → master form
master form	a logical form which has a → sub form
detail form	occasionally used synonym for → sub form

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 component type.

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

Goals

The major goal is to improve the usability of the existing property browser in various aspects.

Detailed Specification

Everything described herein is to be seen relative to the property browser appearance as to be found in OpenOffice.org 1.1, so it's assumed that the reader is familiar with this component.

The deficits of the current property browser can be grouped into three categories:

unintuitive order and/or naming of properties

ignorance of cross-property dependencies

deficits in easy input of complex data

Reordering and Renaming of properties

The following changes are to be made to existing properties:

Multiline input will be renamed to Word break. Applies to: Label Field.

Note that this does explicitly not apply to Text Boxes, where the property will still be named Multiline input.

Horizontal scroll bar and Vertical scroll bar will be merged into a Scrollbars property, which is a list box containing all 4 combinations, namely None, Horizontal, Vertical, Both. Applies to: Text Box.

Type of submission will be moved behind Submission encoding. This will result in a more logical ordering of the properties, since Type of submission is evaluated only when Submission encoding is URL. Applies to: Form.

Default value will be renamed to Default text. Applies (only!) to: Text Box and Combo Box.

Default value will be renamed to Default time resp. Default date. Applies (only!) to: Date Field resp. Time Field.

For Tabstop, the Default entry will be removed from the list of possible values. This is because Default is internally mapped to the same behavior as Yes or No, depending on only the control type. For instance, for a Text Box Default effectively evaluates to Yes, for an Image Button it evaluates to No.

When a component is encountered whose Tabstop value already is Default, then this will be mapped to Yes or No in the property browser display, without actually really changing the property value.

Applies to: all focusable controls.

Alignment will be renamed to Graphics Alignment to better reflect it's semantics. Applies to: Push Button.

Bound field will be moved behind List content. Reason for this is that Bound field does depend on both Data field and Type of list content, so it should be placed after both. To not separate Type of list content and List content, which are also strongly coupled, Bound field will be moved to the last position. Applies to: List Box.

Order will be renamed to Tab order. This is for consistency reasons with e.g. the Tab Order Dialog. Applies to: all.

AutoFill will be moved behind Line count. This will result in the properties Dropdown and Line count being adjacent. Applies to: Combo Box.

Link master fields and Link slave fields will be moved behind Analyze SQL command.

String list

Item	English	German	Comments
Property Label	Word break	Wortumbruch	
Property Label	Scrollbars	Bildlaufleisten	
Property Value	None	Keine	list value for "Scrollbars" property
Property Value	Horizontal	Horizontal	list value for "Scrollbars" property
Property Value	Vertical	Vertikal	list value for "Scrollbars" property
Property Value	Both	Beide	list value for "Scrollbars" property
Property Label	Default text	Standardtext	Translators: This refers to text in the sense of “words”, NOT “font”
Property Label	Default date	Standarddatum	
Property Label	Default time	Standardzeit	
Property Label	Graphics alignment	Grafik-Ausrichtung	"Graphics" resp. "Grafik" is already used as label for a strongly coupled property
Property Label	Tab order	Aktivierungsreihenfolge	already used as title of the dialog which is associated with this property

String contexts

Illustration 1 property browser, here invoked for a Text Box
reached via "Main Toolbar", "Show Form Functions", "Control Properties"

Cross property dependencies

There is a variety of properties which are interdependent in different ways. Two classes of interdependencies exist:

Some properties are ignored until another property has a particular value. Example: The URL of a Push Button is ignored until its Button Type is URL.

In such cases, the controls for entering the dependent property (URL in the example above) will be disabled if and only if the actuating property (Button Type in the example above) does not have the proper value (URL in the example above).

Some properties describe the appearance and/or behavior of control content, while other properties describe a special content value of the control. Example: Date format describes the formatting in a Date Field, while Default value describes the default date of the control.

In such cases, the controls for entering the special values will be changed so that they also respect the settings made in the actuating property. In the example above, this means that the default date of a Date Field will always be displayed in the format as defined with the Date format property.

Disabling Properties

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	applies to
Button Type	≠ URL	URL, Frame	Push Button, Image Button
Graphics	empty	Graphics Alignment	Push Button
Graphics	empty	Scale	Image Button, Image Control
Data field	empty	Scale	Image Control
Data field	empty	Empty string is NULL, Filter proposal	Text Box, Combo Box, Formatted Field, Pattern Field
Data field	empty	Bound Field	List Box
Type of list content	≠ Value list	List Entries	List Box, Combo Box
List content	not empty	List Entries	List Box, Combo Box
Type of list content	= Table fields or = Value list	Bound Field	List Box
Drop down	≠ Yes	Line Count	List Box, Combo Box
Multiline input	= No	Scrollbars	Text Box
Repeat	= No	Delay	Date Field, Time Field, Numeric Field, Formatted Field, Currency Field, Push Button, Spin Button
URL	empty	Frame	Form
Submit encoding	≠ URL	Type of submission	Form
Tabstop	= No	Tab Order	all focusable controls
Multiline input	= Yes	Password characters	Text Box
Analyze SQL command	= No	Filter, Order	Form

For completeness, the following table lists the dependencies which are already implemented in today's property browser.

actuating property	trigger condition	depending properties	applies to
Linked Cell	empty	Data field, Empty string is NULL, Filter proposal	all
Linked Cell	not empty	Contents of the linked cell	List Box
Source cell range	not empty	Bound field, Type of list content, List content, List entries	List Box

Complex property dependencies

With this, especially some properties for List Boxes and Combo Boxes yield some non-trivial dependencies. The following list contains the complete rules for all of them.

Linked cell is enabled if and only if Data field is empty.

Content of the linked cell is enabled if and only if Linked cell is not empty.

Data field is enabled if and only if Linked cell is empty.

Bound field is enabled if and only if Data field is not empty, Linked cell is empty, Type of list content does equal neither Table fields nor Value list, and Source cell range is empty.

Type of list content is enabled if and only if Source cell range is empty.

List content is enabled if and only if Source cell range is empty.

List entries is enabled if and only if Source cell range is empty, and either Type of list content is Value list, or List content is empty.

Empty string is NULL is enabled if and only if Linked cell is empty and Data field is not empty.

Filter proposal is enabled if and only if Linked cell is empty and Data field is not empty.

This, finally, gives us the dependency graph as shown in Illustration 2:

Illustration 2

Additionally, the Scale property has a non-trivial dependency:

Scale and is enabled if and only if Graphics is not empty or Data field is not empty.

Easing value input

For a number of properties, there will be new possibilities to input the property value.

Defining the tabbing order

The Order property defines the order of a (form or dialog) control, relative to all other controls. The disadvantage of the current property browser behavior is that it's not possible to change the order of all controls at once: You can only subsequently select all controls, and give them a (most probably successive) order. This is inconvenient and error prone.

Thus, we will introduce the usual browse button (labeled "...") behind the control for inputting the value for the Order property, as shown in Illustration 3. It will open the tab order dialog which is already known from the form design (where the dialog is accessible from the Form Functions toolbar).

Illustration 3 Browse button for the Order property

The dialog can be seen in Illustration 4. It is not specified here, as it is already existent in previous versions of OpenOffice.org, with exactly the same functionality.

Illustration 4 Tab Order dialog

Date input

There are a number of properties which specify a date value, namely Date min., Date max., Default date, and Date. For all of these, the input control will be enhanced with a drop down button. When clicked, it opens a floating window for a graphical selection of a date, which is to be entered in the input control.

This date selection window can be seen in Illustration 5. It is not specified in detail here, since it's the usual window which is also available to the user when the Dropdown property of a Date field is set to Yes.

Illustration 5 Date selection drop down window

File URLs

For the properties URL and Graphics, the user can enter arbitrary URLs. Today, they're always displayed as such, even if they denote a file URL.

We will change this so that file URLs are displayed in system instead of URL notation (e.g. "C:\foo and bar" instead of "file:///c:/foo%20and%20bar").

Additionally, entering system notation property values will also be allowed: The text will then automatically (and only internally) be converted to a proper URL.

Yet more additionally, the auto completion feature which is known from the internal file dialog will be used, too. This means that the controls for inputting URLs will behave very much like the file name input field in the OpenOffice.org's File Open Dialog.

List Boxes: choosing a (Default) Selection

For List Box controls, the Default selection and Selection properties allow to specify which of the entries in the List entries property should be selected in a particular situation. Currently, this has to be done by specifying a number (or a list of numbers, depending on the Multiselection property value), which is pretty counter-intuitive.

Thus, we will offer the usual browse button associated with both of the properties, which opens a dialog as shown in Illustration 6. It allows to visually select the desired list entries.

The browse button for both properties will be enabled if and only if there is a non-empty value for the List entries property, and (in case of form controls) if the Type of list content equals Value list. The reason for the latter restriction is that for all content types except Value list, the list content is, upon loading the form, dynamically generated from some database data. Thus it's not reasonable to specify a (default) selection in such cases.

The title of the dialog equals the name of the property for which it is invoked.

When the dialog is initially opened, the list box on the left hand side contains all list entries of the control, as specified in the List entries property. If the property for which the dialog is invoked has a non-empty value at this time, the respective items in the list box are initially selected.

The list box in the dialog will allow selecting multiple entries if and only If the List Box control itself does so (Multiselection property set to Yes).

On the right hand side of the dialog there are the usual buttons (OK, Cancel, and Help) with the usual semantics.

Illustration 6 Choosing a (default) selection When the dialog is closed with OK, the index/es of the selected entry/entries will be set as value of the Default selection respectively Selection property.

Tab Order

The dialog will offer the canonical tabbing order (left to right and top to bottom).

String list

Item	English	German	Comments
Dialog title	Default Selection	Standardauswahl	the very same string as used for the property label
Dialog title	Selection	Auswahl	the very same string as used for the property label

Measurement units

The properties Row Height (for a Table Control) and Width (for a Table Control Column) specify a value whose unit is 1/10th millimeter. Currently, this unit is not displayed in the property browser, which will be changed. The input controls for both properties will be metric input fields as known from various other places in OpenOffice.org, thus displaying a metric unit together with the value, and allowing for entering other metric units as long as they denote a length.

For form controls, the default unit when displaying these properties is taken from the respective settings of the host application (e.g. for OpenOffice.org Writer the setting made in Tools|Options|Text Document|General|Measurement Unit).

The input control for the Delay property will be extended to display it's measurement unit (which is milliseconds, shortcut "ms"). It will allow entering time duration values in milliseconds ("ms") and seconds ("s"). As usual with metric fields, all other units except "ms" and "s" will be rejected, and treated as if the base unit (which is "ms") had been entered.

Filtering and Sorting a Form

For the Filter and Sort properties, an additional browse button (as usual right behind the control for inputting the respective property values) will be offered. When this button is clicked, the "Filter" respectively "Sort Order" dialog, as known from the data source browser, will be opened, and allow to change the filter respectively sorting criterion of the form. The dialogs, as they are already present in today's OpenOffice.org, can be seen in Illustration 7.

Illustration 7 Today's Filter and Sort Order dialogs

For the dialogs as opened from within the property browser, the only difference to the dialogs as used in the data source browser is the title: When called from within the property browser, it will equal the name of the property for which it has been called.
In particular, this means that in case these dialogs get redesigned some day, the property browser will benefit from this change, too.

For the interaction between a dialog (either for Filter or for Sort) and the property value, the following holds:

The browse button for the property will be disabled if and only if the Analyze SQL command is set to No, or the Content property is empty, or the Data source property is empty.

When the dialog is opened using the browse button, it initially displays the structured representation of the current property value. If the original filter resp. sort criterion contained more components than the dialog can display, these additional components are silently stripped. This is consistent with the behavior of this dialog when opening from within an ordinary data view.

When the dialog is closed with OK, the structured filter resp. sort order which has just been entered by the user is transformed into it's string representation, and set as value of the property.

Upon opening the dialog, a connection to the data source will be established. In particular, the user may be asked to log in to this data source. If the connection cannot be established for whatever reasons, the usual error dialog is shown, and the dialog is not opened.

Binding a form to an SQL command

For a form, when Content type is SQL command, the Content property is to denote an SQL statement which should be used to retrieve the data which the form should display. To ease this, we will provide the usual browse button for the Content property, which is enabled if and only if Content type is SQL command, Data source contains a valid (aka existent) data source name, and Analyze SQL command is No. When pressed, a query design window (as known from designing queries for a data source) will be opened.

This window will be a normal task window. In particular, it is not modal to the form document which the currently inspected object belongs to. In case the property browser, or the document where the inspected form resides, is to be closed, the open query design window is also closed. In case it, at this moment, still contains modified and unsaved content, the user is asked whether to save the changes (see below). If the user denies closing the query design window, then closing the property browser window, respectively the document window, is also denied.

When the window is initially opened, the current SQL command (means the current value of the Content property) will be shown (in the usual graphical and structured representation).

While the window is open, the input field for the properties Data source, Content type, Content and Analyze SQL command will be disabled, so that the user cannot create inconsistencies with editing the property value in both places.

Compared to the task of editing normal data source queries, the query design window will, in some aspects, behave different when opened to edit the Content property value. In particular:

The title of the window will be "SQL command" – which is exactly the text of the respective value of the Content type property.

The "Save as" functionality will not be available. In both the toolbox and the menu, the respective item will be disabled.

When the user choses "Save" (no matter if via the toolbox, the menu, or a keyboard shortcut), the statement as created by the user will be set as value of the Content property.

When the query design window is closed and the current SQL statement has been modified since the last "Save" action (or since the window was initially opened, if no "Save" action happened since then), an alert box with the following text appears: "The SQL command has been modified. Do you want to save these changes?". There will be buttons "Yes", "No" and "Cancel" with the canonic semantics.

Illustration 8 Query design window, opened from within the property browser

Illustration 8 shows the query design window, as opened from within the property browser.

If the property browser is closed (by whatever means) while the query design window is open, the window will be closed automatically. The same holds if another object is to be inspected (e.g. by selecting it in the form navigator). In both cases, if the query design window contains unsaved modifications, then the same alert box as above is raised, asking whether the changes should be submitted to the Content property. If the user cancels this alert box, then the property browser will not be closed, respectively not switch to the new object.

String list

Item	English	German	Comments
Alert box text	The SQL statement has been changed.\nDo you want to save these changes?	Der SQL-Befehl wurde geändert.\nSollen diese Änderungen gespeichert werden?	This text is analogous to the one which appears in the same situation when the window is used to edit a query. The only difference is that "The query" is replaced with "The SQL command". LIZ: Due to prevalent naming conventions in English and German, the term “statement” is to be translated with “Befehl” even though it is not the direct translation.

Sub Form Relations

Specifying a linking between a sub form and a master form is pretty unintuitive in today's property browser, which we will address by offering a dedicated dialog for specifying it.

Additionally, the user will in most cases not be required to deal with SQL statements and SQL parameters anymore, at least if s/he merely wants to link a master and a sub form using one or more column pairs.

In case the inspected form is not a sub form (i.e. has no parent form), the Master fields and Detail fields properties will be hidden.

Direct column name linking

Imagine three tables "Actors", "Movies", and "Directors", which contain data about, well, actors, movies, and directors. Furthermore assume a 1-n-relationship between "Directors" and "Movies", and a m-n-relationship between "Actors" and "Movies". This could be modeled as shown in Illustration 11.

Illustration 9

If in today's property browser, the user wants to display all directors in a master form, and all movies made by a director in a detail form, then this requires her to do something like

bind the master form (via Content Type and Content) to the Table directors.

bind the detail form to the SQL command "SELECT * from Movies where director = :dir_id"

set the Link master fields property of the detail form to DirectorID.

set the Link slave fields property of the detail form to dir_id.

This procedure is error-prone, and not intuitive at all. Thus, the property browser will be changed so that it also accepts column names in the Link slave fields property (and not only parameter names). As an immediate consequence, there's no need to hassle with SQL statements anymore: The Content Type / Content of the detail form could be simply set to Table and Movies, which is much more what the user might expect.

Of course, the old way of linking columns will still be supported. This leads to a potential ambiguity, since in the Link slave fields property, the list of names could either be a list of parameter names, or a list of column names. Thus, the following rule applies when evaluating the list of pairs of master and slave fields:

For every identifier in the Link slave fields list:

If the identifier is the name of a parameter (which could either be explicit parameters in an SQL command entered in Content, or implicit parameters which result when you use a parameterized query as Content), then the respective master-slave-field-pair will be used to fill the respective parameter.

If the identifier is a column name in the sub form (i.e. a column in the result set produced by the Table or Query or SQL command), then the master-slave-field-pair will be used to filter the sub form with respect to this column.

If nothing of the above holds, then the master-slave-field-pair will be ignored.

Example 1

With the data structure from Illustration 9, you could display all directors, plus all movies which these directors created, with the following two logical forms:

master form: Content Type = Table, Content = directors.

sub form: Content Type = Table, Content = Movies, Link master fields = DirectorID, Link slave fields = director.

Alternatively, you could still use an explicit SQL command for the sub form, which is how it works today:

master form: Content Type = Table, Content = directors.

sub form: Content Type = SQL command, Content = SELECT * from Movies WHERE director = :dir_id, Link master fields = DirectorID, Link slave fields = dir_id.

Example 2

Again with the data structure from Illustration 9, you could display all Movies, and for every movie all actors which played in this movie, with the following two forms:

master form: Content Type = Table, Content = Movies.

sub form: Content Type = SQL command, Content = SELECT actors.* FROM actsin, actors WHERE ( actsin.actor = actors.ActorID ), Link master fields = MovieID, Link slave fields = movie.

If you save the statement as separate query named "actors_for_movies", then your detail form would look like:

master form: Content Type = Table, Content = Movies.

sub form: Content Type = Query, Content = actors_for_movies, Link master fields = MovieID, Link slave fields = movie.

The alternative way (again, this is the way as it works before the change specified in this document) would be:

master form: Content Type = Table, Content = Movies.

sub form: Content Type = SQL command, Content = SELECT actors.* FROM actsin, actors WHERE ( actsin.actor = actors.ActorID ) AND ( actsin.movie = :movie_id ), Link master fields = MovieID, Link slave fields = movie_id.

Note that neither the names in the Link master fields, nor in the Link slave fields list, allow table names. That is, in Example 2, you cannot specify actsin.movie as slave field, though it may be desirable since the Content for the detail form comprises of more than one table. As a consequence, you are required to make column names in a master or detail form unique (by using alias names), if you want to refer them in one of the two Link properties. However, making names unique in an SQL statement is always a good idea, anyway ...

Linking multiple column pairs

To conveniently enter multiple pairs of linked columns, and additional dialog will be introduced.

For this, both the Link master fields and Link slave fields properties will get a browse button. Semantically, both buttons are the same: They open a dialog which allows to simultaneously specify both property values. Thus, below the buttons are referred as "the (browse) button" only.

The browse button is enabled if and only if all of the following statements hold:

The inspected form is a sub form.

For the master form, both the Data source and the Content property are not empty, and Data Source denotes the name of an existing data source.

For the sub form itself, both the Data source and the Content property are not empty, and Data Source denotes the name of an existing data source.

Upon pressing the button, the "Link Fields" dialog (see below) will be opened, and initially filled with the current values from the Link master fields and Link slave fields properties.

The "Link Fields" Dialog

The "Link Fields" dialog (see Illustration 10) is used to specify the fields which link between the master and the detail form. It displays 4 rows of pairs of combo boxes, plus an explanatory text, plus the usual OK/Cancel/Help buttons, plus an additional button for suggesting links.

Illustration 10 Declaring links between a master and a sub form

String list

Item	English	German	Comments
Dialog title	Link Fields	Felder verknüpfen	
Fixed Text	Master form	Hauptformular	
Text fragment	Subform	Unterformular	
list box entry	<none>	<keine>	
Button	Suggest	Vorschlagen	
Explanatory text	Subforms can be used to display detailed data about the current record of the master form. To do this, you can specify which columns in the subform match which columns in the master form.	Unterformulare können benutzt werden, um Detaildaten zu dem aktuellen Datensatz des Hauptformulars anzuzeigen. Dazu können Sie festlegen, welche Spalten sich jeweils entsprechen sollen.	

Tab Order

Tab traveling happens row-wise, and in every row from left to right. After the right-most list box in the last row passed, the buttons are traveled up-to-bottom.

Value transfer

When the dialog is initially opened, the current values of the Link master fields and Link detail fields properties (which are sequences of strings) are reflected in the dialog's columns. In the (probably rare) case where one of the string lists contains more than 4 entries, all entries except the first 4 are ignored.

When the dialog is closed with OK, the changes made therein are transferred back to the Link master fields and Link slave fields properties. In particular, if one of the both string sequences originally contained more than 4 entries, then the additional entries are lost.

Combo Boxes and Field lists

Each row of combo boxes is used to enter a pair of columns from the master and the detail form. All rows look and behave exactly the same way. In the left combo box, the list comprises of all fields of the sub form. E.g., if the sub form is bound to a table, all columns of this sub form are present in the list. Similarly, the list in the right combo box comprises of all fields of the master form.

The entry lists of the combo boxes are filled when the dialog is being opened. For this, the column lists of the master and detail form have to be retrieved, which is potentially expensive. While this is done, the mouse cursor will be an hour glass when over the dialog.

The combo box columns have labels above them, which show the name of the table/query which the sub respectively master form is bound to. If the form is not bound to a particular query or table, but to an SQL command, then the label is "sub form" respectively "master form".

Miscellaneous

The OK button in the dialog is disabled if and only if there is a list box row where only one of the list boxes contains an invalid selection. Invalid here means that no column from the list is selected in the list box.

Error handling

If an error occurs while the column lists are retrieved, this error is reported. For this, the usual SQL error dialog, as used across OpenOffice.org Base, is opened, with a primary text of "The columns of $object could not be retrieved", where $object is replaced with either "the master form" or "the sub form".
An example for the error dialog is show in Illustration 11. Note that the secondary text in this dialog depends on the actual error which happened, and is not under the control of the Link Fields dialog, but provided by the database driver instead.

Illustration 11 Error message for column lists which could not be retrieved

After the error has been reported to the user this way, the Link Fields dialog is closed immediately.

String list

Item	English	German	Comments
Error message	The columns of the master form could not be retrieved.	Die Spalten des Hauptformulars konnten nicht ermittelt werden.	
Error message	The columns of the sub form could not be retrieved.	Die Spalten des Unterformulars konnten nicht ermittelt werden.	

Suggesting field links

The "Suggest" button in the "Link Fields" dialog allows to pre-fill the list boxes with columns which are automatically obtained from a relation in the underlying database.

The button is available if and only if all of the following is met

Both the master and the detail form are based on the same Data source.

The Data source which the forms are based on supports relations.

For both the master and the detail form one of the following holds

the form is bound to a table

the form is bound to a query, which does not have the "Run SQL command directly" flag set, and the FROM clause of the underlying SQL statement contains one table only

the form is bound to a SQL command, its Analyze SQL command property is set to Yes, and the FROM clause of the SQL command in the Content property contains one table only.

Between the both tables which can be canonically associated with the two forms (once the previous condition is met), there exists a relation.

The relation which exists between both tables does involve at most 4 column pairs.

If one of the conditions above is not met, then the button will be visible, but disabled.

When the button is pressed, the list box rows in the "Link Fields" dialog are automatically filled with the proper columns from the relation between the both tables.

Miscellaneous

Miscellaneous things (which, in parts, do not even strictly belong to the overall topic ...):

Tab Order Dialog

Currently, the toolbox symbol for opening the tab order dialog (the same which, with this specification, is now also opened from within the property browser), has the tool top “Activation order”. However, the title of the dialog is “Tab Order”. For consistency reasons, we will change the tool tip to match the dialog title.

String list

Item	English	German	Comments
Tool tip	Tab Order	Aktivierungsreihenfolge	string review: This string matches the respective property names, so if this is to be changed, please keep consistency.

Future Tasks

Redesign the sort and filter dialogs, to e.g. support an unlimited number of items, and match the design of the filter/sort pages in the query and form wizards.

Notes

References

Note that default value properties are only displayed when inspecting a form control, while value properties are only displayed when inspecting a dialog control.

see chapter Reordering and Renaming of properties where this property is introduced

Property Browser Enhancements

Page 5

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

Frank Schönheit

2003-11-03T16:43:06