getting started with base - softenpochethis opens the automobile – openoffice.org base window....

Getting Started with BaseApache OpenOfficetm Database Component

CopyrightThis document is Copyright © 2013 by its contributors as listed below. You may distribute it and/or modify it under the terms of either the Apache Software License 2.0 or later ( http://www.apache.org/licenses/), or the Creative Commons Attribution License, version 3.0 or later (http://creativecommons.org/licenses/by/3.0/).

Apache OpenOffice and OpenOffice.org are trademarks of The Apache Software Foundation. All other trademarks mentioned in this guide belong to their respective owners.

ContributorsDrew Jensen ([email protected])

FeedbackPlease direct any comments or suggestions about this document to:

AcknowledgmentsThis work includes material from

OpenOffice.org 3.3 Getting Started Guide, Chapter 8 - Getting Started with Base, Copyright 2010 Dan Lewis, Iain Roberts, Magnus Adielsson, Jean Hollis Weber, JiHui Choi

OpenOffice.org 3.2 BASIC Guide · March 2010, Copyright Oracle Corp.

Publication date and software versionPublished 30 October 2013. Based on Apache OpenOffice 4.0.1

2 Getting Started with Base

Note for Mac usersSome keystrokes and menu items are different on a Mac from those used in Windows and Linux. The table below gives some common substitutions for the instructions in this chapter. For a more detailed list, see the application Help.

Windows/Linux Mac equivalent Effect

Tools > Options menu selection

OpenOffice.org > Preferences

Access setup options

Right-click Control+click Open context menu

Ctrl (Control) z (Command) Used with other keys

F5 Shift+z+F5 Open the Navigator

F11 z+T Open Styles & Formatting window

Getting Started with Base 3

ContentsCopyright.......................................................................................................................................... 2

Note for Mac users...........................................................................................................................3

Introduction...................................................................................................................................... 6

Planning a database.........................................................................................................................8

Creating a new database..................................................................................................................9

Creating database tables................................................................................................................10

Using the Wizard to create a table.............................................................................................10

Creating a table by copying an existing table.............................................................................13

Creating tables in Design View..................................................................................................13Creating tables for the list box...............................................................................................16

Defining relationships.....................................................................................................................18

Creating a database form...............................................................................................................20

Using the Wizard to create a form..............................................................................................20

Modifying a form........................................................................................................................23

Creating forms and subforms in Design View............................................................................34

Accessing other data sources........................................................................................................35

Accessing a spreadsheet as a data source................................................................................35

Registering *.odb databases......................................................................................................35

Using data sources in Apache OpenOffice.................................................................................36Viewing data sources............................................................................................................36Editing data sources..............................................................................................................36Launching Base to work on data sources..............................................................................37

Using data sources in Writer and Calc.......................................................................................37Writer documents..................................................................................................................37Calc spreadsheets................................................................................................................39

Entering data in a form...................................................................................................................41

Creating queries.............................................................................................................................44

Using the Wizard to create a query............................................................................................44

Using the Design View to create a query...................................................................................46

Creating reports..............................................................................................................................52

Creating a static report...............................................................................................................52

Creating a dynamic report..........................................................................................................55

Apendix 1 HSQL-SDBC internal query procedures........................................................................60

Overview....................................................................................................................................60

Numerical Functions..................................................................................................................60

String Functions.........................................................................................................................63

Date and Time Functions...........................................................................................................66

System Functions......................................................................................................................69

Aggregate Functions..................................................................................................................69

Statistical Functions...................................................................................................................70

Modifiers....................................................................................................................................70Limit...................................................................................................................................... 71


Top........................................................................................................................................ 71Distinct..................................................................................................................................72

Appendix 2 – OpenOffice Basic .....................................................................................................73

Database ..................................................................................................................................73SQL: a Query Language ......................................................................................................73Types of Database Access ...................................................................................................73

Data Sources ............................................................................................................................74Queries ................................................................................................................................75Database Access .................................................................................................................76Iteration of Tables .................................................................................................................77Type-Specific Methods for Retrieving Values .......................................................................78The ResultSet Variants .........................................................................................................79Methods for Navigation in ResultSets ..................................................................................79Modifying Data Records .......................................................................................................80

Dialogs ......................................................................................................................................80Working With Dialogs ...........................................................................................................81Creating Dialogs ...................................................................................................................81Closing Dialogs ....................................................................................................................81Working With Dialogs ...........................................................................................................82Access to Individual Control Elements .................................................................................82Working With the Model of Dialogs and Control Elements ...................................................82Focus and Tabulator Sequence ............................................................................................83Multi-Page Dialogs ...............................................................................................................84Dialogs supporting several languages ..................................................................................85Events ..................................................................................................................................85The Apache OpenOffice Basic development environment ....................................................85Mouse Events ......................................................................................................................86Keyboard Events ..................................................................................................................88Focus Events .......................................................................................................................89Control Element-Specific Events ..........................................................................................89Dialog Control Elements .......................................................................................................90Buttons .................................................................................................................................90Text Fields ............................................................................................................................93

Forms ....................................................................................................................................... 96Working With Forms .............................................................................................................97Control Element Forms ......................................................................................................100Database Forms .................................................................................................................106


IntroductionA data source, or database, is a collection of pieces of information that can be accessed or managed by OpenOffice.org (OOo). For example, a list of names and addresses is a data source that could be used for producing a mail merge letter. A shop stock list could be a data source managed through OOo.

NoteOpenOffice.org uses the terms “Data Source” and “Database” to refer to the same thing, which could be a database such as MySQL or dBase or a spreadsheet or textdocument holding data.

This chapter covers creating a database, showing what is contained in a database and how the different parts are used by OOo. It also covers using the Base component of OOo to register other data sources. A data source can be a database, spreadsheet, or text document.

Note OOo Base uses the HSQL database engine. All of the files created by this engine are kept in one zipped file. The database forms are included in this zipped file.

A database consists of a number of fields that contain the individual pieces of data. Each table of the database is a group of fields. When creating a table, you also determine the characteristics of each field in the table. Forms are for data entry into the fields of one or more tables associated withthe form. They can also be used for viewing fields from one or more tables associated with the form. A query creates a new table from the existing tables based upon how you create the query. A report organizes the information of the fields of a query in a document according to your requirements.

Caution

The database in OOo requires Java Runtime Environment (JRE). If you do not have it on your computer, you can download it from www.java.com and install it following the instructions on the site. It should be Java 5.0 or higher. In OOo, use Tools > Options > OpenOffice.org > Java to register Java.

Windows' version of JRE can not be used, while there are other versions that can.

Base creates relational databases. This makes it fairly easy to create a database in which the fields of the database have relationships with each other.

For example: Consider a database for a library. It will contain a field for the names of the authors and another field for the names of the books. There is an obvious relationship between the authorsand the books they have written. The library may contain more than one book by the same author. This is what is known as a one-to-many relationship: one author and more than one book. Most if not all the relationships in such a database are one-to-many relationships.

Consider an employment database for the same library. One of the fields contains the names of the employees while others contain the social security numbers, and other personal data. The relationship between the names and social security numbers is one-to-one: only one social securitynumber for each name.

If you are acquainted with mathematical sets, a relational database can easily be explained in terms of sets: elements, subsets, unions, and intersections. The fields of a database are the elements. The tables are subsets. Relationships are defined in terms of unions and intersections ofthe subsets (tables).

To explain how to use a database, we will create one for automobile expenses. In the process, we will be explaining how a database works.


Planning a databaseThe first step in creating a database is to ask yourself many questions. Write them down, and leave some space between the questions to later write the answers. At least some of the answers should seem obvious after you take some time to think.

You may have to go through this process a few times before everything becomes clear in your mind and on paper. Using a text document for these questions and answers makes it easier to move the questions around, add additional questions, or change the answers.

Here are some of the questions and answers I developed before I created a database for automobile expenses. I had an idea of what I wanted before I started, but as I began asking questions and listing the answers, I discovered that I needed additional tables and fields.

What are the fields going to be? My expenses divided into three broad areas: fuel purchases, maintenance, and vacations. The annual cost for the car’s license plate and driver’s license every four years did not fit into any of these. It will be a table of its own: license fees.

What fields fit the fuel purchases area? Date purchased, odometer reading, fuel cost, fuel quantity, and payment method fit. (Fuel economy can be calculated with a query.)

What fields fit the maintenance area? Date of service, odometer reading, type of service, cost of service, and next scheduled service of this type (for example, for oil changes list when the next oil change should be). But it would be nice if there was a way to write notes. So, a field for notes was added to the list.

What fields fit the vacations area? Date, odometer reading, fuel (including all the fields of the fuel table), food (including meals and snacks), motel, total tolls, and miscellaneous. Since these purchases are made by one of two bank cards or with cash, I want a field to state which payment type was used for each item.

What fields fit into the food category? Breakfast, lunch, supper, and snacks seem to fit. Do I list all the snacks individually or list the total cost for snacks for the day? I chose to divide snacks into twofields: number of snacks and total cost of snacks. I also need a payment type for each of these: breakfast, lunch, supper, and total cost of snacks.

What are the fields that are common to more than one area? Date appears in all of the areas as does odometer reading and payment type.

How will I use this information about these three fields? While on vacation, I want the expenses for each day to be listed together. The date fields suggest a relationship between the vacation table and the dates in each of these tables: fuel and food, This means that the date fields in these tableswill be linked as we create the database.

The type of payment includes two bank cards and cash. So, we will create a table with a field for the type of payment and use it in list boxes in the forms.

TipWhile we have listed fields we will create in the tables of the database, there is one more field that may be needed in a table: the field for the primary key. In some tables,the field for the primary key has already been listed. In other tables such as the payment type, an additional field for the primary key must be created.

Planning a database 7

Creating a new databaseTo create a new database, choose File > New > Database from the menu bar, or click the arrow next to the New icon on the Standard toolbar and select Database from the dropdown menu. Both methods open the Database Wizard.

On the first page of the Database Wizard, select Create a new database and then click Next.

The second page has two questions. Make sure the choice for the first question is Yes, register thedatabase for me and the choice for the second question is Open the database for editing. Click Finish.

NoteIf the database is not registered, it will not be accessible to the other OOo components such as Writer and Calc. If the database is registered, other components can access it.

Save the new database with the name Automobile. This opens the Automobile – OpenOffice.org Base window. Figure 1 shows part of this window.

Figure 1: Creating database tables

TipEvery time the Automobile database is opened, the Automobile – OpenOffice.org Base window opens. Changes can then be made to the database. The title for this window is always <database name> – OpenOffice.org Base.


Creating database tablesIn a database, a table stores information for a group of things we call fields. For example, a table might hold an address book, a stock list, a phone book or a price list. A database can have from one to several tables.

To work with tables, click the Tables icon in the Database list, or press Alt+a. The three tasks that you can perform on a table are in the Tasks list (see Figure 1).

Using the Wizard to create a tableWizards are designed to do the basic work. Sometimes this is not sufficient for what we want; in those cases we can use a wizard as a starting point and then build upon what it produces.

The Table Wizard in Base contains two categories of suggested tables: business and personal. Each category contains sample tables from which to choose. Each table has a list of available fields. We can delete some of these fields and add other fields.

A field in a table is one bit of information. For example, a price list table might have one field for item name, one for the description, and a third for the price.

Since none of the fields we need for our Automobile database are contained in any of the sample wizard tables, we will create a simple table using the wizard that has nothing to do with our database. This section is an exercise in explaining how the Wizard works.

The Wizard permits the fields of the table to come from more than one suggested table. We will create a table with fields from three different suggested tables in the Wizard.

Caution

Every table requires a Primary key field. (What this field does will be explained later.) We will use this field to number our entries and want that number to automatically increase as we add each entry.

Click Use Wizard to Create Table. This opens the Table Wizard (Figure 2).

Step 1: Select fields.We will use the CD-Collection Sample table in the Personal category to select the fields we need.

Category: Select Personal. The Sample Tables dropdown list changes to a list of personal sample tables.Sample tables: Select CD-Collection. The Available fields box changes to a list of availablefields for this table.

Selected fields: Using the > button, move the following fields from the Available fields window to the Selected fields window in this order: CollectionID, AlbumTitle, Artist, DatePurchased, Format, Notes, and NumberofTracks.

Selected Fields from another sample table. Click Business as the Category. Select Employees from the dropdown list of sample tables. Use the > button to move the Photo field from the Available fields window to the Selected fields window. It will be at the bottom of the list directly below the NumberofTracks field.If you make a mistake in selecting fields, click on the field name in the Selected fields list and use the < button to move it from the Selected fields list back to the Available fields list.

Creating database tables 9

If you make a mistake in the order of the selected fields, click on the field name that is in the wrong order and use the Up or Down arrow on the right side of the Selected fields list tomove the field name to the correct position.Click Next.

Figure 2: Selecting fields for the table

Step 2: Set field types and formats.In this step you give the fields their properties. When you click a field, the information on the right changes. (See Figure 3.) You can then make changes to meet your needs. Click each field, one at a time, and make the changes listed below.

Figure 3: Changing field types

NoteIf any of these fields requires an entry, set Entry required to Yes. An entry with that field blank will then not be allowed. In general, only set Entry required to Yes if something must always be put in that field. By default, Entry required is set to No.

CollectionID: Change AutoValue from No to Yes.

AlbumTitle: Entry required: Leave Entry required as No, unless all of your music is in albums.

Length: Unless you have an album title that exceeds 100 characters counting the spaces, do not change the length.


Note

In Base the maximum length of each field must be specified on creation. It is not easyto change this later, so if in doubt specify a greater length. Base uses VCHAR as the field format for text fields. This format only uses the actual number of characters in a field up to the limit set. So, a field containing 20 characters will only use space for 20 characters even if the limit is set at 100. Two album titles containing 25 and 32 characters respectively will use space for 25 and 32 characters and not 100 characters.

Artist: Use the Default setting. And since music has artists, set Entry Required to Yes.

Date Purchased: Field type: default date setting. Entry required should be No. (You may not know the date.)

Format: Only change the Entry Required setting: from No to Yes.

Notes: No changes are required.

NumberofTracks: Change the Field Type to Tiny Integer [TINYINT]. Your allowable number oftracks will be 999. Small Integer [SMALLINT] would allow 99999 tracks if you needed more than 999 tracks.Photo: Use the default settings.

When you have finished, click Next.

Note

Each field has a Field Type, which must be specified. Types include text, integer, date, and decimal. If the field is going to have general information in it (for example, aname or a description), use text. If the field will always contain a number (for example, a price), the type should be decimal or another numerical field. The wizard picks the right field type, so to get an idea of how this works, see what the wizard has chosen for different fields.

Step 3: Set primary key.Create a primary key should be checked.

Select option Use an existing field as a primary key.

In the Fieldname dropdown list, select CollectionID.

Check Auto value if it is not already checked.

Click Next.

Note

A primary key uniquely identifies an item (or record) in the table. For example, you might know two people called “Randy Herring” or three people living at the same address and the database needs to distinguish between them.

The simplest method is to assign a unique number to each one: number the first person 1, the second 2, and so on. Each entry has one number and every number is different, so it is easy to say “record ID 172”. This is the option chosen here: CollectionID is just a number assigned automatically by Base to each record of this table.

Step 4: Create the table.If desired, rename the table at this point. If you rename it, make the name meaningful to you. For this example, make no changes.Leave the option Insert data immediately checked.

Click Finish to complete the table wizard.


Close the window created by the table wizard. You are now back to the main window of the database with the listing of the tables, queries, forms, and reports. Notice that a table named “CD-Collection” is now listed in the Tables portion of the window.

Creating a table by copying an existing tableIf you have a large collection of music, you might want to create a table for each type of music you have. Rather than creating each table from the wizard, you can make copies of the original table, naming each according to the type of music contained in it.

Click on the Tables icon in the Database pane to see the existing tables.

Right-click on the CD-Collection table icon. Choose Copy from the pop-up menu.

Move the mouse pointer below this table, right-click, and select Paste. The Copy table dialog opens.

Change the table name to Pop and click Next.

Click the >> button to move all the fields from the left box to the right box and click Next.

Since all the fields already have the proper Field type, no changes should be needed. However, this is the time and place to make any changes if they are needed. (See Caution below for the reason why.) Click Create. The new table is created.

Caution

Once tables have been created using the wizard and data has been entered, editingthem should be very limited. Fields can be added or deleted, but adding a field requires taking the time to enter the data for that one field for every record having an entry for that field.Deleting a field deletes all the data once contained in that field. Changing the field type of a field can lead to data being lost either partially or completely. When creating a new table, it pays to create the fields with the correct names, length, and format before you add any data.Deleting a table removes all of the data contained in every field of the table. Unless you are sure, do not delete a table.

Creating tables in Design ViewDesign View is a more advanced method for creating a new table, in which you directly enter information about each field in the table. We will use this method for the tables of our database.

Note While the Field type and formatting are different in Design View, the concepts are the same as in the Wizard.

The first table to be created is Fuel. Its fields are FuelID, Date, FuelCost, FuelQuantity, Odometer, and PaymentType.

Click Create Table in Design View.

FuelID field:

Type FuelID as the first Field Name. Press the Tab key to move to the Field Type column.Select Integer [INTEGER] as the Field Type from the dropdown list. (The default setting is Text [VARCHAR].)


T i pA shortcut for selecting from the Field Type dropdown list: press the key for the first letter of the choice. You can cycle through the choices for a given letter by repeatedly pressing that key.

Change the Field Properties in the bottom section.Change AutoValue from No to Yes.Set FuelID as the Primary key.Right-click on the green triangle to the left of FuelID (Figure 4) and choose Primary Key from the menu. This places a key icon in front of FuelID.

Figure 4: Defining the primary key field

NoteThe primary key serves only one purpose: to uniquely identify the record. Any name can be used for this field. We have used FuelID for convenience, so we know to which table it belongs.

1) All other fields (Date, FuelCost, FuelQuantity, Odometer, and PaymentType):

Type the next field name in the Field Name column.

Select the Field Type for each field.

For Date use Date[DATE]. (Press the D key to select it.)

PaymentType uses Text [VARCHAR], the default setting.

All other fields use Number [NUMERIC]. (Press the N key once to select it.)

FuelCost, FuelQuantity, and Odometer need changes in the Field Properties section (Figure 5).

FuelQuantity: Change Length to 6 and Decimal places to 3. (Many fuel pumps measure fuel to thousands of a gallon in the USA where I live.)

Odometer: Change the Length to 10 and the Decimal places to 1.

FuelCost: Change the Length to 5 and Decimal places to 2. Click the Format example button (Figure 5). This opens the Field Format window (Figure 6). Use Currency as the Category and yourcurrency as the Format. My currency has two decimal places. Use what is appropriate for yours.


Figure 5: Changing field properties

Figure 6: Field Format options

To access additional formatting options, click the button to the right of the Format example field.

Description can be anything, or can be left blank.

To save and close the table, choose File > Save. Name the table Fuel. Close the Fuel table.

Follow the same steps to create the Vacations table. The fields and their field types are listed inFigure 7. Make sure you make the Date field the primary key before closing. (Right-click the gray box to the left of Date and select Primary key from the menu.) Save the table and name it Vacations. Close the Vacations table.


Figure 7: Fields in Vacations table

Creating tables for the list boxWhen the same information can be used in several fields, design a table for each type of information. Each table will contain two fields: the information field and ID, in that order.

Caution You must create these tables with the information field listed first and the ID field listed last. Failure to do so will produce the wrong results. For my Payment table, I use Name and ID as my fields, with Dan, Kevin, and Cash being the Name entries. The corresponding ID entries are 0, 1, 2. When the Name field is listed first in the table, one of the three names will appear in the payment field of the Fuel table. If theID field is listed first, 0, 1, or 2 appear in the payment field instead.

Follow the directions in “Creating tables in Design View” on page 12. In the table, the two fields canbe Type and PaymentID. In the Field Properties, set AutoValue to Yes for the PaymentID field. Set the PaymentID field as the primary key. (See Figure 8.)

Save the table using the name Payment Type.

Figure 8: Table in Design View

Note If you have several tables to create with the same fields, design one table and producethe other tables by cutting and pasting. (See “Creating a table by copying an existing table” on page 12.)

Adding data to the list table

List tables do not require a form. Instead, add their data directly to the table. In this example, use the names of the two people with a bank card and Cash for cash purchases.


In the main database window, click on the Tables icon (Figure 1). In the list of tables, right-click on Payment Type and select Open from the pop-up menu.

Enter Dan in the Type column in the first row. Press the Tab key to move to the second row. Notice that the PaymentID value for this row changes from <AutoField> to 0.

Enter Kevin in the second row. The PaymentID changes to 1.

a) Enter Cash in the third row. The PaymentID changes to 2.

Save and close the table window.

Tip You can also use the Enter key to move from entry field to entry field, or use the down arrow key to move from row to row.


Defining relationshipsNow that the tables have been created, what are the relationships between our tables? This is the time to define them based upon the questions we asked and answered in the beginning.

When on vacation, we want to enter all of our expenses all at one time each day. Most of these expenses are in the Vacations table, but the fuel we buy is not. So, we will relate these two tables using the Date fields. Since the Fuel table may have more than one entry per date, this relationshipbetween the Vacations and Fuel tables is one to many. (It is designated 1:n.)

The Vacations table also contains several fields for the type of payment used. For each field listing the payment type, there is only one entry from the Payment Type table. This is a one to one relationship: one field in one table to one entry from the other table. (It is designated 1:1.) Other tables also contain fields for the type of payment. The relationship between the fields of those tables and the Payment Type table are also 1:1.

Since the Payment Type table only provides a static list, we will not be defining a relationship between the Payment Type table and the fields of the other tables which use the entries of the Payment Type table. That will be done when the forms are created.

The Fuel and Maintenance tables do not really have a relationship even though they share similar fields: Date and Odometer.

Tip As you create your own databases, you need to also determine where tables are related and how.

To begin defining relationships, choose Tools > Relationships. The Automobile – OpenOffice.org Base: Relation Design window opens and the Add Tables dialog pops up. (You can also open it by clicking the Add Tables icon on the Relation Design window.)

On the Add Tables dialog, use either of these ways to add a table to the Relation Design window:

Double-click the name of the table. In our case, do this for both Vacations and Fuel.

Or, click the name of the table and then click Add for each table.

Click Close to close the Add Tables dialog when you have added the tables you want.

You can define the relationship between the Vacations and Fuel tables in two ways:

Click and drag the Date field in the Fuel table to the Date field in the Vacations table. When you release the mouse button, a connecting line forms between the two date fields.

Figure 9: Designation for a 1:n relationship

Or, click the New Relation icon. This opens the Relations window (Figure Figure 10). Our two tables are listed in the Tables involved section.

In the Fields involved section, click the dropdown list under the Fuel label.

Select Date from the Fuel table list.

Click in the cell to the right of this dropdown list. This opens a dropdown list for the Vacations table.

Defining relationships 17

Select Date from the Vacations table list. It should now look like Figure 10.

Click OK.

Figure 10: Selected fields in a relationship

2) Modifying the Update options and Delete options section of the Relation window.

Right-click the line connecting the Date fields in the two table lists to open a menu.

Select Edit to open the Relations dialog (Figure 11).

Select Update cascade.

a) Select Delete cascade.

Click OK to close the Relations dialog and choose File > Save to save the Relation Design window.

While these options are not strictly necessary, they do help. Having them selected permits you to update a table that has a relationship defined with another table. It also permits you to delete a field from the table.

Figure 11: Update options and Delete options section


Creating a database formDatabases are used to store data. But, how is the data put into the database? Forms are used to do this. In the language of databases, a form is a front end for data entry and editing.

Figure 12: Fields of a simple form Figure 13: Simple form with additions

A simple form consists of the fields from a table (Figure 12). More complex forms can contain muchmore, including additional text, graphics, selection boxes, and many other elements. Figure 13 is made from the same table with a text label (Fuel Purchases), a list box placed in PaymentType, and a graphic background.

Using the Wizard to create a formWe will use the Form Wizard to create a Vacations form, which will contain a form and a subform.

In the main database window (Figure 1), click the Forms icon in the left column. In the Tasks list, double-click Use Wizard to Create Form to open the Form Wizard (Figure 14). Simple forms require only some of these steps, while more complex forms may use all of them.

Step 1: Select fields.

Under Tables or queries, select Table: Vacations. Available fields lists the fields for the Vacations table.

Click the right double arrow to move all of these fields to the Fields in the form list. Click Next.

Figure 14: Form Wizard steps

Step 2: Set up a subform.


Since we have already created a relationship between the Fuel and Vacations tables, we will use that relationship. If no relationship had been defined, this would be done in step 4.

Click the box labeled Add Subform.

Click Subform based upon existing relation.

Fuel is listed as a relation we want to add. So, click Fuel to highlight it, as in Figure 15. Click Next.

Figure 15: Adding a subform

Step 3: Add subform fields.

This step is exactly the same as step 1. The only difference is that not all of the fields will be used in the subform.

Fuel is preselected under Tables or queries.

Use the >> button to move all the fields to the right.

Click the FuelID field to highlight it.

Use the < button to move the FuelID to the left (Figure 16).

Click Next.

Figure 16: Selecting fields of a subform

Step 4: Get joined fields.


This step is for tables or queries for which no relationship has been defined. Because we have already defined the relationship, the wizard skips this step.

Note It is possible to create a relationship between two tables that is based upon more than one pair of fields. How to do that and why is discussed in the Base Guide.

Caution

When selecting a pair of fields from two tables to use as a relationship, they have tohave the same field type. That is why we used the Date field from both tables: both their field types are Date[DATE].Whether a single pair of fields from two tables are chosen as the relationship or twoor more pairs are chosen, certain requirements must be met for the form to work.

• No field from the subform can be the Primary key for its table. (FuelID cannotbe used.)

• Each pair of joined fields must have the same file type.

• One of the fields from the main form must be the Primary key for its table. (Date would have to be used.)

Step 5: Arrange controls.

Each control in a form consists of two parts: label and field. This step in creating the form determines where a control’s label and field are placed in relationship with each other. The four choices from left to right are Columnar left, Columnar - Labels on top, As Data Sheet, and In Blocks - Labels Above.

Arrangement of the main form: Click the second icon (Columnar - Labels on top). The labels will beplaced above their field.

Arrangement of the subform: Click the third icon (As Data Sheet). (The labels are column headingsand the field entries are in spreadsheet format.) Click Next.

Step 6: Set data entry.

Unless you have a need for any of these entries to be checked, accept the default settings. Click Next.

Step 7: Apply styles.


Select the color you want in the Apply Styles list. (I chose the beige which is Orange 4 in the Color table.)

Select the Field border you want. (I prefer the 3-D look. You might want to experiment with the different possible settings.)

Click Next.

Step 8: Set name.

Enter the name for the form. In this case, it is Fuel.

Click Modify the form.

Click Finish. The form opens in Edit mode.

Modifying a formWe will be moving the controls to different places in the form and changing the background to a picture. We will also modify the label for the PaymentType field as well as change the field to a list box.

First, we must decide what we want to change. The discussion will follow this ten step outline of our planned changes.

Provide a dropdown capability for the Date field in the main form, and lengthen the field to show the day of the week, month, day, and year.

Shorten the length of the payment fields (all fields containing the word Payment).

Move the controls into groups: food, fuel subform, and miscellaneous.

Change the wording of some of the labels. Some single words should be two words. Some abbreviations should be used if possible (Misc. for miscellaneous).

Change the lengths of several fields and labels. Only Lunch, Supper, Motel, and Tolls have acceptable lengths. But for a better appearance, changes will be made to these as well.

Replace all the fields whose label ends in Payment with a list box containing the entries from the Payment Type table.

Lengthen the Note field vertically, add a scroll bar, and move it.

Make changes in the Date and PaymentType columns of the subform that are similar to the changes in the main form.

Add headings for each group in the main form.

Change the background to a picture, then modify some of the labels so that they can be read clearly. Change the font color of the headings.

Here are some methods that we will be using in these steps. The controls in the main form consistsof a label and its field. Sometimes we want to work with the entire control, other times we want to work with only the label or the field, and there are times when we want to work with a group of controls.

• Clicking a label or field selects the entire control. A border appears around the control with eight green handles. You can then drag and drop it where you want.

Figure 17: A selected control


• Control+click a label or field selects only the label or the field. You can press the Tab key to change the selection from the field to the label or the label to the field.

Figure 18: Selecting a field of a control

• Moving a group of controls is almost as easy as moving one of them.

Click the field of the top left control to be moved, to select it.

Move the cursor to just above and to the left of the selected control.

Drag the cursor to the bottom right of the group of controls and release the mouse button.

As you drag the cursor, a dashed box appears showing what is contained in your selection. Make sure it is big enough to include the entire length of all the controls.

When you release the mouse button, a border with its green handles appears around the controls you selected.

Figure 19: Selecting multiple controls

Move the cursor over one of the fields. It changes to a drag icon. Drag the group of controls to where you want them.

TipWhen either changing size or moving a control, two properties of the Form Design toolbar should be selected: Snap to Grid, and Guides when Moving. Your controls willline up better, and an outline of what you are moving moves as the cursor moves.You should also have both rulers active (View > Ruler).

Step 1: Change the Date field.

Control+click the Date field to select it.

Move the cursor over the middle green handle on the right side. It should change to a double-headed arrow.

Hold the left mouse button down as you drag the cursor to the right until the length is 6 cm. The vertical dashed line is lined up with the 6. Release the mouse button.

Click the Control icon in the Form Controls toolbar. The Properties: Date Field window opens. Eachline contains a property of the field.

Figure 20: Form Controls toolbar

Scroll down to the Date format property. This is a dropdown list with Standard (short) as the defaultsetting. Click it to open the list. Select the Standard (long) entry.

Scroll down to the Dropdown property. Its default setting is No. It is also a dropdown list. Click to open the list. Select Yes.


TipTo see what the Date field will look like, click the Form Mode On/Off icon (the second icon from the left in Figure 20). You can do this any time you want to see the form with the changes you have made.

Step 2: Shorten the width of some fields.

All of the fields with a label containing the word payment are too wide. They need shortening before the controls are moved.

Control+click the BPayment field.

Figure 21: Selecting a field

Move the cursor over the middle green handle on the right. The cursor becomes a double-headed arrow.

Drag the cursor to the left until the field is 2.5 cm wide (1 inch).

Tip If you have the Snap to Grid and Guides when moving icons selected in the Design Format toolbar, you will see how wide the field is as you shorten it.

Repeat these steps to shorten these fields: Lpayment, SPayment, SnPayment, Mpayment, and MiscPayment.

Step 3: Move the controls to group them by category.

We want to move the controls so that they look like Figure 22.

Figure 22: Positioning of controls

Click the first control you want to move. A border appears around the control with eight green handles.

Move the cursor over the label or field of the control. It change shape to a drag icon.

Drag and drop the control to where you want it.

Caution

Do not use Control+click when moving a field. It moves either the field or the label but not both. To move both, use a mouse click and drag to the desired spot.


Use the same steps to move the rest of the controls to where they belong.

Step 4: Change the label wording.

Field names have been single words for some time. However, the labels for the fields in a form can be more than one word. So, we will change them by editing the text in the label.

NoteThe table wizard in Base contains suggested fields which are single words, often consisting of two separate words. Table names in the wizard have been that way also. However, you can use multiple words as the name of a field, label, or table. We will do so when we create a list box for each of the payment type controls.

Control+click the SnackNo label. Do one of the following:

Right-click the SnackNo label and select Control from the pop-up menu.

• Or, click the Control icon in the Form Control toolbar (Figure 20).

The dialog that opens is labeled Properties: Label Field. It contains all of the properties of the selected label.

In the Label selection, edit the label to Snack No.

Close the Properties dialog.

Use the same procedure to change these labels as well: BPayment to Payment, LPayment to Payment, SPayment to Payment, Miscellaneous to Misc., SnackCost to Snack Cost, MPayment to Payment, MiscPayment to Misc. Payment, and MiscNotes to Misc. Notes.

TipYou can modify all of the listings in the Properties window. For example, if you change the Alignment from Left to Center, the word or words in the label are centeredwithin the label. When you have some time, you might want to experiment with different settings just to see the results you get.

Step 5: Change the widths of the labels and fields.

We want the following controls to be 2 cm wide (0.8 inches): Breakfast, Lunch, Supper, Odometer, Snack No., Tolls, Snack Cost, Motel, and Misc. All of the payment fields were changed in step 2, but Misc. Payment needs to be changed to 3 cm (1.2 inches).

Right-click Breakfast and choose Position and Size. On the Position and Size dialog, change Widthto 2 cm.

Repeat for the other listed controls, using 3 cm for Misc.Payment.

Caution

When changing the position or size of an entire control, use the Position and Size dialog or the drag and drop method.When working with either the label or the field (but not both at the same time), you can use the Properties dialog to make these changes when you want to be exact. However, you need to be careful not to accidentally select the entire control for use with the Properties dialog or you will apply the exact same values to both the label and field. For example, if you enter the values for a new position, both the field and the label moves to the same position and the field is positioned on top of the label. Then you have to move each of them to where you want them.

NoteTo open the Properties window, right-click a control and select Control from the pop-up menu. Or, you can click the Control icon in the Form Controls toolbar. Just be careful, and use Control+Z to undo any mistakes you may make. Detailed instructions on how to use the Properties window will be in the Base Guide.


Step 6: Replace fields with other fields.

We want to replace the PaymentType field with a List Box. Then we can choose the type of payment from the Payment Type table rather than having to manually enter the type. In my case, each of my payment types begins with a different letter. If I enter the first letter of the payment type,the rest of the word automatically appears. I can then go to the next field.

Control+click the Payment field for Breakfast. The green handles appear around the field but not around the Label.

Figure 23: Selecting a field of a control

Right-click within the green handles and select Replace with > List Box.

Click the Control icon in the Form Controls toolbar to open the Properties: List Box dialog.

On the General tab, scroll down to the Dropdown selection. Change the No to Yes.

Figure 24: Dropdown list open to reveal choices

Click the Data tab.

Type of list contents is a dropdown list. Change it to Sql.

Figure 25: Type of list contents dropdown list

Type the following exactly as it is in the List contents box:


SELECT "Type", "Type" FROM "Payment Type"

Figure 26: List content for payment type fields

Note

What you wrote is called an SQL command. The words SELECT and FROM are written in capital letters because they are commands. When the command SELECT is used, it requires a field name within quotation marks and then the field’s alias, also within quotation marks. In this case, the field and its alias are the same. The FROM command requires the name of the table which contains the field. Single-word table names do not require quotation marks, but multiple-word table names do.

Repeat these steps for the payment fields for Lunch, Supper, Motel, Snacks, and Misc. The main form should look like Figure 27 as far as where the controls are located. It also shows what the Note control should look like. Those changes are explained in the next step.

Close the Properties window.

Figure 27: Position of controls in main form

Step 7: Change the Misc. Notes field.

We want the Misc. Notes control, which has a field type of Memo, to have a vertical scrollbar for additional text space if desired.

Control+click the Misc. Notes field. The green handles should surround the field but not its label.

Click the Control icon to open the Properties window (Figure 28).

Scroll down to the Scrollbars setting. Change the selection from None to Vertical in this dropdown list.


Figure 28: Scrollbar selections in the Properties window

Close the Properties window.

Lengthen the Misc. Notes field by moving the cursor over the middle green handle at the bottom of the field and dragging down until the length is 6 cm (2.4 inches).

Step 8: Change labels and fields in the subform.

The subform is located at the bottom of the form. We want to widen the Date column, change the field in the PaymentType column to a list box, and change the label for the PaymentType column totwo words.

To widen the Date column, move the mouse pointer over the dividing line between the Date and FuelCost columns. When the pointer changes shape, click and drag to move the divider to the right.

To change the PaymentType column:

Right-click the label PaymentType and choose Replace with > List box from the menu.

Again right-click the label PaymentType to open the menu. Select Column to open the Properties dialog (Figure 29).

In the Label box, change PaymentType to Payment Type.

Click the Data tab.

From the Type of list contents dropdown list, select Sql.

Type the following exactly as it is written:

SELECT "Type", "Type" FROM "Payment Type"

Close the Properties dialog.


Figure 29: Properties window for control in a subform

Step 9: Add headings to groups.

This step is easier to do if you have end-of-paragraph markers visible. Choose View > Nonprinting Characters to turn them on.

Make sure the cursor in in the upper left corner. If it is not, click in that corner to move it there.

Press the Enter key to move the cursor down to the space between the Date field and the Breakfast field.

Change the Apply Styles dropdown list from Default to Heading 2.

Figure 30: Apply Styles list

Use the spacebar to move the cursor to where you want the heading to start.

Type the heading Meals.

Use the spacebar to move the cursor to the center of snack area.

Type the heading Snacks.

Use the Enter key to move the cursor between the Supper control and the subform.

Use the spacebar to move the cursor to the center of the subform.

Type the heading Fuel Data.

NoteIf you know how to use styles, you can open the Styles and Formatting window using F11. Right-clicking the Heading 2 paragraph style allows you to modify the appearance of all three headings. See Chapter 6 of the Writer Guide for details.

Step 10: Change the background of a form.


The background for a form can be a color, or a graphic (picture). You can use any of the colors in the Color Table at Tools > Options > OpenOffice.org > Colors. If you know how to create custom colors, you can use them. You can also use a picture (graphic file) as the background.

If you choose a dark background, you many need to change many of the labels and headings so they can be seen.

Select the labels of the top row of controls.

Control+click the Date label.

Control+shift+click the rest of the labels of the top row. The border will gradually grow to the right as you do this until all the labels are enclosed in it.

Figure 31: Selecting multiple labels at one time

Click the Control icon in the Design Form toolbar to open the Properties dialog.

Change the Background color selection from Default to Light cyan. (This is a dropdown list.) Close the Properties dialog.

Select the other labels in the same way and then change their background color.

To change the font color for the headings:

Open Styles and Formatting using the F11 key. Make sure the Paragraph icon is selected at the left end of the icons in Figure 32.

Right-click the Heading 2 style to open a pop-up window and select Modify from this menu.

a) In the Paragraph Style Heading 2 dialog, click the Font Effects tab. Change Font colorfrom Automatic to Light Cyan.

Figure 32: Styles and Formating window

Click OK to close the dialog.

TipLearning how to use styles can be very helpful at times. By using styles, we changed the font color for all three headings at one time. There are other methods of changingthe font color, but they require repeating the same steps for each heading.

To add a graphic to the background:

Right-click on the background and select Page from the pop-up menu.

On the Page Style dialog, click the Background tab, change the As dropdown list from Color to Graphic.


Click Browse to find and select the graphic file you want to use, and click Open. In the Type sectionof the Background tab, select Area.

Click OK to close the dialog. The form should look like Figure 33.

Figure 33: Finished form

Step 11: Change the tab order.

The Tab key moves the cursor from field to field. This is much easier to do than to click each field to enter data into it. It also permits us to group our expenses into areas before we begin entering data. For example, all of our meal receipts can be grouped together as can our snacks and also our fuel purchases.

Control+click the Date field.

1) Click the Form Design icon in the Form Controls toolbar to open the Form Design toolbar (Figure 34), or choose View > Toolbars > Form Design to open this toolbar.

2) Click the Activation Order icon (circled).

Figure 34: Form Design toolbar with Activation Order icon circled

Rearrange the order of the fields in the Tab Order window.

Find the txtMPayment listing near the bottom of the list and click it.

Click the Move Up button until txtPayment is just below fmtMotel.

Use the same two steps to put the fields in the same order as in Figure 35. Click OK.


Figure 35: Tab order for the main form

Save and close the form.

Save the database.

Creating forms and subforms in Design ViewThis method requires using the Form Controls and Form Design toolbars extensively. These techniques are beyond the scope of this document. Instructions for creating forms using Design view will be described in the Database Guide.


Accessing other data sourcesApache OpenOffice allows data sources to be accessed and then linked into OOo documents. For example, a mail merge links an external document containing a list of names and addresses into a letter, with one copy of the letter being generated for each entry.

To access a data source that is not a *.odb file:

File > New > Database opens the Database Wizard window.

1) Select Connect to an existing database. Click the arrow next to the Database type field andselect the database type from the dropdown list. Click Next.

Click Browse and select the database. Click Next.

Accept the default settings: Register the database for me, and Open the database for editing. ClickFinish. Name and save the database in the location of your choice.

Accessing a spreadsheet as a data sourceAccessing a spreadsheet is similar to accessing other databases:

Choose File > New > Database.

Select Connect to an existing database. Select Spreadsheet as the Database type.

Click Browse to locate the spreadsheet you want to access. If the spreadsheet is password protected, check the Password required box. Click Next.

If the spreadsheet requires a user’s name, enter it. If a password is also required, check its box. Click Next.

Note

Using this method of accessing a spreadsheet, you cannot change anything in the spreadsheet. You can only view the contents of the spreadsheet, run queries, and create reports based upon the data already entered into the spreadsheet.All changes in a spreadsheet must be made in the spreadsheet itself, using Calc. After modifying the spreadsheet and saving it, you will see the changes in the database. If you create and save an additional sheet in your spreadsheet, the database will have a new table the next time you access it.

Registering *.odb databasesDatabases created by OOo2.x or later are in the *.odb (OpenDocument Base) format. Other programs can also produce databases in this format. Registered a *.odb database is simple:

Choose Tools > Options > OpenOffice Base > Databases.

Under Registered databases, click New.

Browse to where the database is located.

Make sure the registered name is correct.

Click OK.

NoteSometimes when updating Apache OpenOffie to a newer version, your list of registered database files disappears. When that happens, you need to use these steps to register your database files with your latest version of Apache OpenOffice.

Accessing other data sources 33

Using data sources in Apache OpenOfficeHaving registered the data source, whether a spreadsheet, text document, external database or other accepted data source, you can use it in other OpenOffice.org components including Writer and Calc.

Viewing data sourcesOpen a document in Writer or Calc. To view the data sources available, press F4 or select View > Data Sources from the pull-down menu. This brings up a list of registered databases, which will include Bibliography and any other database registered, such as the Automobile database created earlier in this chapter.

To view each database, click on the + to the left of the database’s name (see Figure 36). This brings up Tables and Queries. Click on the + next to Tables to view the individual tables created. Now click on a table to see all the records held in it.

Figure 36: Databases

Editing data sourcesSome data sources can be edited in the View Data Sources dialog. A spreadsheet can not. A record can be edited, added, or deleted.

The data is displayed on the right side of the screen. Click in a field to edit the value.

Beneath the records are five tiny buttons. The first four move backwards or forwards through the records, or to the beginning or end. The fifth button, with a small star, inserts a new record.

Figure 37: View Data Sources navigation buttons

To delete a record, right-click on the gray box to the left of a row to highlight the entire row, and select Delete Rows to remove the selected row.

Figure 38: Deleting a row in the Data View window

Launching Base to work on data sourcesYou can launch OOo Base at any time from the View Data Source pane. Just right-click on a database or the Tables or Queries icons and select Edit Database File. Once in Base, you can edit,add, and delete tables, queries, forms, and reports.


Insert new record

Using data sources in Writer and CalcData can be placed into Writer and Calc documents from the tables in the data source window. In Writer, values from individual fields can be inserted. Or, a complete table can be created in the Writer document. One common way to use a data source is to perform a mail merge.

TipChoosing Tools > Mail Merge Wizard or clicking on the Mail Merge icon on the View Data Source pane launches the Mail Merge wizard which steps you through creating a mail merge document. See Chapter 11 in the Writer Guide.

Writer documentsTo insert a field from a table opened in the data source window into a Writer document, click on thefield name (the gray square at the top of the field list) and, with the left mouse button held down, drag the field onto the document. In a Writer document, it will appear as <FIELD> (where FIELD is the name of the field you dragged).

For example, to enter the cost of meals and who paid for them on a certain date of a vacation:

Open the list of data sources (F4) and select the Vacations table in the Automobile database.

3) Use this sentence: “On (date), our breakfast cost (amount) paid by (name), our lunch cost (amount) paid by (name), and our supper cost (amount) paid by (name).” But only type “On, our breakfast cost paid by , our lunch cost paid by , and our supper cost paid by .”

To replace (date), click the field name Date in the data source window and drag it to the right of theword On. The result: On <Date>. If you have Field shadings turned on (View > Field shading), <Date> has a gray background. Otherwise it does not.

To replace first (amount), click the Breakfast field name and drag it to the right of our breakfast cost. Make sure you have the proper spacing between the field names and the words before and after them. Result: breakfast cost <Breakfast>.

To replace the first (name), click the Bpayment field name and drag it to the right of paid by. Result:paid by <Bpayment>.

In the same way, fill in the rest of the fields in the sentence.

Use <Lunch> and <LPayment> for the second set of (amount) and (name) in the sentence.

Use <Supper> and <SPayment> for the third set of (amount) and (name) in the sentence.

Final result: On <Date>, our breakfast cost <Breakfast> paid by <BPayment>, our lunch cost <Lunch> paid by <LPayment>, and our supper cost <Supper> paid by <SPayment>.

Add data to the fields of the sentence:

Click the gray box to the left of the row of data you want to add. That row should be highlighted likethe second row of Figure 39.

Click the Data to Fields icon (circled). This should fill the fields with the data from the row you chose.

Click another row and then click this icon again. The data in the sentence changes to this selected row of data.

Save the document if you want to use it as an example later.


Figure 39: Selected row in data source window

Adding data in table format is a little easier and takes perhaps fewer steps. Some of the steps will be quite similar.

Navigate to the place you want to place the table and click the location.

Control+Click the gray box to the left of each row of the data source that you want to be a row in your table when the rows are not consecutive. To select consecutive rows, click the gray box to theleft of the top desired row and Shift+click the bottom desired row.

Click the Data to text icon to open the Insert Database Columns dialog (Figure 40). (The Data to text icon is to the left of the Data to Fields icon in Figure 39.)

4) Move the fields you want in your table from the Database Columns list to the Table column(s) list.

To place the fields in the order you select, click the field and use the single arrow to move the fieldsin the order you desire. You can also limit the fields you use to less than all of the fields available.

If you want to use all of the fields, use the double arrow pointing to the right to move all of them at one time. The order of the fields in the table you create will be the same as in the data source table.

To remove a single field from the Table Column(s) list, click the field and use the single arrow pointing to the left.

5) To start over, click the double arrow pointing to the left.

Figure 40: Insert Database Columns dialog

Select the settings for your table. Use the default settings as in Figure 40.

Click OK. Save the document.


Calc spreadsheetsThere are two ways to enter data in a Calc spreadsheet. One enters the data into the spreadsheet cells. The other creates records in the spreadsheet just like they are done in creating a form in a database. While you can directly access the data in the spreadsheet cells, you can only see the data in the records created in the spreadsheet.

Entering data directly to the spreadsheet cells uses the Data to Text icon as we did to make a tablein a Writer document. But differences exist in these two situations.

The steps are straightforward.

Click the cell of the spreadsheet which you want to be the top left of your data including the columnnames.

Use F4 to open the database source window and select the table whose data you want to use.

Select the rows of data you want to add to the spreadsheet:

Click the gray box to the left of the row you want to select if only selecting one row. That row is highlighted.

To select multiple rows, hold down the Control key while clicking the gray box of the rows you need. Those rows are highlighted.

To select all the rows, click the gray box in the upper left corner. All rows are highlighted.

Click the Data to text icon to insert the data into the spreadsheet cells.

Save the spreadsheet.

Adding records to a spreadsheet is fairly easy. You need to have the Data Source window open, your spreadsheet open, and the table you want to use selected.

Click the gray box above the field name for the table's ID field.

Drop and drag the gray box for the table's ID field to where you want the record to appear in the spreadsheet.

Repeat until you have moved all of the fields you need to where you want them.

Name and save the spreadsheet.

Click a row of the table in the Data Source window.

Drag the data in the ID field in the selected row onto the ID field in the spreadsheet. The Save icon should activate.

Click the Edit File button to make the spreadsheet read only. Click Save when asked if you want tosave the file.

The Data Source window goes blank, the fields in the spreadsheet are populated with data from the row you selected, and the Form Navigation toolbar appears at the bottom of the spreadsheet.

Figure 41: Navigation arrows of a form

Click the arrows on the Form Navigation toolbar to view the different records of the table. (The arrows are circled in red.) The number in the box changes when you change the record number by clicking an arrow. The data in the fields changes correspondingly to the data for that particular record number.


Entering data in a formRecords are used to organize the data we enter into a form. They also organize the data we enter into a subform.

Each type of field allows a different method to enter the data. In many if not all cases, more than one method can be used.

The first step to entering data in a form is to open it from the main database window (Figure 1).

Click the Forms icon in the Database list.

Find the form’s name in the Forms list (Vacations).

Double-click the form’s name.

The quickest way to enter a date in the Date field is to click the arrow that opens the dropdown calendar. Then click the day the you want. Then press the Tab key to go to the Odometer field.

Figure 42: Calendar dropdown

The Odometer, Tolls, and Motel fields are numerical fields. Enter values directly into them, or use the up and down arrows. When the value is entered, use the Tab key to go to the next field.

Clicking the up arrow increases the value, and the down arrow decreases the value one unit.

These two arrows only change the numerals to the left of the decimal place.

Numerals to the right of the decimal place must be changed by deleting them and typing the desired ones.

The Motel’s Payment field is a dropdown list. If as in my case, all of the elements of the list start with different letters, typing the first letter selects the desired entry.

If two or more elements of the list have the same first letter, repeated typing of the first letter will cycle through the elements with this same first letter.

When the selection is correct, use the Tab key to go to the Misc. field.

The rest of the fields of the main form are either numerical fields or dropdown lists until we reach the Misc. Notes field. It is a text field. Type anything you desire in this field just as you would any simple text editor.

Note

Since the Tab key is used to move between fields, it can not be used in a text field. All spacing must be done by the spacebar. Finally, the Enter key only acts as a line break to move the cursor to the next line. While the Enter key will move from non-text fields to non-text fields, it will not do so from a text field. Use the Tab key instead.If we did not have a subform for fuel data, pressing the Tab key in the last field wouldsave all of the fields, clear them, and make the form ready to accept data on the second record.


Since we have a subform form, using the Tab key places the cursor in the first Date field of the subform with the date automatically entered to match the Date field of the main form.

The FuelCost, FuelQuantity, and Odometer fields are numerical fields. The Payment field is a dropdown list. Enter the data just as you did in the main form, and use the Tab key to go to the nextfield.

When you use the Tab key to leave the Payment field, it goes to the Date field of the next line and automatically enters the date. Now you can enter your second set of fuel data for this day.

To move to another record when the form has a subform, click any of the fields of the main form. Inthis case, click the Date field of the main form. Then use the directional arrows at the bottom. There are four of them from left to right: First Record, Previous Record, Next Record, and Last Record (Figure 41). To the right of these arrows is the New Record icon.

To create a new record while in another record in the main form, click either the Next Record icon or the New Record icon.

TipThe number in the Record box is the number of the record whose data is shown in the form.If you know the number of the record you want, you can enter it into the record box and then press Enter to take you to that record.

Figure 43 is a record with data inserted in its fields.

Figure 43: Sample record of the Vacation form and subform

Entering data in a form 39

Creating queriesQueries are used to get specific information from a database. Query results are special tables within the database.

To demonstrate the use of queries, we will use two different methods:

Using our CD-Collection table, we will create a list of albums by a particular artist. We will do this using the Wizard.

• The information we might want from the Fuel table includes what our fuel economy is. We will do this using the Design View. (Queries that require calculations are best created with the Design view.)

Using the Wizard to create a queryQueries created by the wizard provide a list or lists of information based upon what one wants to know. It is possible to obtain a single answer or multiple answers, depending upon the circumstances.

In the main database window (Figure 1), click the Queries icon in the Databases section, then in the Tasks section, click Use Wizard to Create Query. The Query Wizard window opens (Figure 44).The information we want is what albums are by a certain musical group or individual (the album’s author). We can include when each album was bought.

Note

When working with a query, more than one table can be used. Since different tables may contain the same field names, the format for naming fields in a query is Table name.field name, with a period (.) between the table name and the field name. For example, The Lunch field of the Vacation table used in a query has the name Vacation.Lunch.

Step 1: Select the fields.

Select the CD-Collection table from the dropdown list of tables.

Select fields from the CD-Collection table in the Available fields list.

Click Artist, and use the > button to move it to the Fields in the Query list.

Move the AlbumTitle and DatePurchased fields in the same manner.

Click Next.

Tip To change the order of the fields, select the field you want to move and click the up ordown arrow.


Figure 44: First page of the Query Wizard

Step 2: Select the sorting order.

Up to four fields can be used to sort the information of our query. A little simple logic helps at this point. Which field is most important?

In our query, the artist is most important. The album title is less important, and the date purchased is of least importance. Of course, if we were interested in what music we bought on a given day, the date purchased would be the most important.

Figure 45: Sorting order page

Click the first Sort by dropdown list.

Click CD-Collection.Artist to select it.

To list the artists in alphabetical order (a-z), select Ascending on the right.

Click the second Sort by dropdown list.

Click CD-Collection.ArtistTitle. and select Ascending.

Repeat this process for CD-Collection.DatePurchased.

Click Next.

Step 3: Select the search conditions.

The search conditions allow us to compare the name we entered with the names of the artist in ourdatabase and decide whether to include a particular artist in our query or not.

is equal to: the same as

is not equal to: not the same as

is smaller than: comes before


is greater than: comes after

is equal or less than: the same as or comes before

is equal or greater than: the same as or comes after

like: similar to in some way

Note These conditions apply to numbers, letters (using the alphabetical order), and dates.

Since we are only searching for one thing, we will use the default setting of Match all of the following.

We are looking for a particular artist, so select CD-Collection. Artist in the Fields list and is equal to as the Condition.

Type the name of the artist in the Value box. Click Next.

Step 4: Select type of query.

We want simple information, so the default setting: Detailed query is what we want. Click Next at the bottom of the window.

Note Since we have a simple query, the Grouping and Grouping conditions are not needed. Steps 5 and 6 of the wizard are skipped in our query.

Step 7: Assign aliases if desired.

We want the default settings. Click Next.

Step 8: Overview.

Name the query (suggestion: Query_Artists). To the right of this are two choices. Select Display Query. Click Finish.

Using the Design View to create a queryCreating a query using Design View is not as difficult as it may first seem. It may take multiple steps, but each step is fairly simple.

What fuel economy is our vehicle getting (miles per gallon in the USA)? This question requires creating two queries, with the first query used as part of the second query.

Step 1: Open the first query in Design View.

Click Create Query in Design View.

Step 2: Add tables.

Figure 46: Add Tables or Query window

Click Fuel to highlight it.


Click Add. Click Close.

Tip Move the cursor over the bottom edge of the fuel table (Figure 47) and drag the to make it longer and easier to see all of the fields in the table.

Figure 47: Fuel table in query

Step 3: Add fields to the table at the bottom.

Double-click the FuelID field in the Fuel table.

Double-click the Odometer field.

Double-click the FuelQuantity field.

The table at the bottom of the query window should now have three columns.

Figure 48: Query table

Step 4: Set the criterion for the query.

We want the query’s FuelID to begin with the numeral 1.

Type >0 in the Criterion cell under FuelID in the query table.

Click the Run Query icon in the Query Design toolbar.

Figure 49: Query Design toolbar

Figure 50 contains the Fuel table with my entries and the query results based upon the Fuel table: the query results are in the right table.


Figure 50: Fuel table and query of the fuel table

Step 5: Save and close the query.

Since this query contains the ending odometer reading for our calculations, name it End-Reading when saving it. Then close the query.

Step 6: Create the query to calculate the fuel economy.

Click Create Query in Design View to open a new query.

Add the Fuel table to the query just as you did in step 2: Add tables But, do not close the Add Tables window.

Add the End-Reading query to this query.

Click Queries to get the list of queries in the database.

Figure 51: Selecting queries to add to another query

Click End-Reading.

Click Add, and then click Close.

Step 7: Add fields to the table at the bottom of the query.

We are going to calculate the fuel economy. To do this we need the FuelQuantity and distance traveled. Since the FuelQuantity we want to use is at the ending odometer reading, we will use the End-Reading query to get it. We will also use the Odometer field from the Fuel table and End-Reading query.

Figure 52: Tables in this query

Double-click FuelQuantity in the End-Reading query.

Double-click Odometer in the End-Reading query.

Double-click Odometer in the Fuel table.


Figure 53: Added fields to the query

Step 8: Enter the FuelID difference field.

We want the difference between the FuelID value of the Fuel table and FuelID value of the End-Reading query to equal one (1).

Type "End-Reading".FuelID - Fuel.FuelID in the field to the right of the Odometer field of the Fuel Table.

Type the numeral 1 (one) in the Criterion cell of this column.

Figure 54: Typing in calculation of fields

Calculate the distance traveled:

Type "End-Reading".Odometer – Fuel.Odometer in the Field cell.

Type >0 in the Criterion cell.

Figure 55: Field for distance traveled calculations

Calculate fuel economy:

Type ("End-Reading".Odometer – Fuel.Odometer)/"End-Reading".FuelQuantity in the next column to the right of the word Field.


Figure 56: Fuel economy calculation field

Note

When entering fields for these calculations, you must follow this format: table or query name followed by a period follow by the field name. For hyphenated or multiple-word names (table or query), use double quotes around the table or query name. The query will then add the rest of the double quotes as in Figure 56.Use the arithmetical symbol between the two. More than one calculation can be done by using parentheses to group the arithmetical operations.

Step 9: Run the query and make some modification.

After we run the query to make sure it works correctly, we will hide all of the fields that we do not need.

Click the Run Query icon in the Design Query toolbar (Figure 49). The results are in Figure 57.

Figure 57: Result of running the fuel economy query

Notice that not all of the last column label is visible because some of the labels are long. We can fix this problem by using an alias for many of the fields. The labels are replaced by their aliases.

Add Aliases:

Type in the aliases as they are listed in Figure 58.

Figure 58: Query table with aliases added

Run the query again. The results are in Figure 59.

Figure 59: Query run with aliases

We really do not need the column showing the difference between the FuelID fields from the table and query, so we will hide it. While it will not be visible, it will still be used in the calculations.

Hide a field that does not need to be seen.

Remove the check in the box of the Visible cell as in Figure 60.


Figure 60: Making a field invisible in a query run

Rerun the query (Figure 61).

Figure 61: Query run with aliases

Step 10: Close, save, and name the query.

My suggestion for a name is Fuel Economy.

There are obviously other calculations that can be made in this query such as cost per distance traveled and how much of the cost belongs to each of the payments types.

NoteTo fully use queries requires a knowledge of set operations (unions, intersections, and, or, complements, and any combinations of these). Having a copy of the Hsqldb User Guide, available from http://hsqldb.org/, is also extremely useful.


Creating reportsReports provide information found in the database in a useful way. In this they are similar to queries. Reports are generated from the database’s tables or queries. They can contain all of the fields of the table or query or just a selected group of fields. Reports can be static or dynamic. Static reports contain the data in the selected fields at the time the report was created. Dynamic reports can be updated to show the latest data.

For example, a report on expenses for a vacation in the past should probably be a static report because it is based upon specific data that does not change. However, a report on the fuel data should probably be a dynamic report, because this report depends upon data that does change.

Caution Dynamic reports update only the data that is changed or added to a table or query. They do not show any modifications made to the table or query itself. For example, after creating the report below, open the fuel economy query created in the previoussection. For the "End-Reading".”Odometer – Fuel.”Odometer” column, change the number 1 to the number 3. The report will be identical before and after you make thechange.

All reports are based upon a single table or query. So you need first to decide what fields you want to use in the report. If you want to use fields from different tables, you must first combine these fields in a single query. Then you can create a report on this query.

For example, a report on vacation expenses includes both fuel costs and meal costs. These valuesare contained in fields of two different tables: Vacations and Fuel. So this report requires creating aquery.

Creating a static reportWe will create a report on vacation expenses. Certain questions need to be asked before creating the report.

What information do we want in the report?

How do we want the information arranged?

What fields are required to provide this information?

Will a query have to be created because these fields are in different tables?

Are there any calculations required in the data before being added to the report?

The expenses for our vacation are motel, tolls, miscellaneous, breakfast, lunch, supper, snacks, and fuel. One possible report would simply list the totals of each of these expense groups. Another possible report would list the expense totals for each day of the vacation. A third possible report would list the totals for each expense group for each type of payment. (This would let us know where the money came from to pay the expenses.) The best way to create reports like these is to create the queries needed to gather the needed data, insert the query data into a spreadsheet, anduse the necessary Calc functions on this data.

We will create two reports, one listing the expenses each day other than fuel and the second listingthe fuel costs each day.

The fields we need for the first report from the Vacations table are: Date, Motel, Toll, Breakfast, Lunch, Supper, SnackCost, and Miscellaneous. This report will not require an additional query.

The second report involves the Fuel table. Since this table includes fuel purchases at times other than during the vacation, we need to create a query that contains only the fuel purchased during the vacation.


Vacations table report

To create a new report.

Click the Reports icon in the Database list in the Automobile – OpenOffice.org Base window (Figure 1).

In the Tasks list, click Use Wizard to Create Report. The Report Wizard opens.

Step 1: Field selection

Select Table: Vacations in the Tables or Queries dropdown list.

Use the > to move these fields from the Available fields list to the Fields in report list: Date, Motel, Tolls, Miscellaneous, Breakfast, Lunch, Supper, and SnackCost. Click Next.

Figure 62: Adding fields to a report

Step 2: Labeling fields

Change any field labels you wish. We will shorten Miscellaneous to Misc. Click Next.

Step 3: Grouping

Since we are grouping by the date, use the > button to move the Date field to the Grouping list. Click Next.

Figure 63: Selecting fields for grouping data

Step 4: Sort options

We do not want to do any additional sorting. Click Next.

Step 5: Choose layout

Use default settings for the layout. Click Next.

Step 6: Create report

Label the report: Vacation Expenses.

Select Static report.


Click Finish.

NoteIf you feel adventurous, try selecting some of the other layout choices. After selecting a choice, drag the Report Wizard window out of the way so that you can see what you have selected. (Move the cursor over the Title Bar of the window, and then drag and drop.)

Vacation fuel report

Create a query containing only fuel bought on the days of the vacation.

Open a query in Design View.

a) Follow the steps for adding tables in “Add tables” on page 42 to add the Fuel table.

b) In the Fuel table, double-click Date and FuelCost to enter them in the table at the bottom of the query.

In the Criterion cell of the Date field, type the following: BETWEEN #5/25/2007# AND #5/26/2007#

Figure 64: Setting the criterion for a query

Save, name, and close the query. (Suggestion: Vacation Fuel Purchases.)

Tip

When using dates in a query, enter them in numerical form MM/DD/YYYY or DD/MM/YYYY depending upon your language's default setting for dates (my default setting is MM/DD/YYYY).Each date must have a # before and after it. Hence, May 25, 2007 is written #05/25/2007# or #25/5/2007# depending upon your language’s default setting for dates.

Open a new report.

Right-click the Vacation Fuel Purchases query.

Select Report Wizard from the pop-up menu.

Note When a new report is opened in this way, the query used to open it is automatically selected in the Tables or queries dropdown list in the Report Wizard.

Create the report.

Use >> to move both fields from the Available fields list to the Fields in report list. Click Next.

Label fields.

Add a space to FuelCost to make it Fuel Cost (two words). Click Next.

Group fields.

Click Date to highlight it. Use > to move the Date field to the Groupings list. Click Next.

Choose layout.


We will be making no changes in the layout. Click Next.

Create report (final settings).

Use the suggested name, which is the same as the query.

Select Static report. Click Finish.

Creating a dynamic reportNow we will create a report with some statistics on our fuel consumption. To do this, we have to modify two queries: End-Reading and Fuel Economy. We will be adding the FuelCost field to the End-Reading query. Then we will add the FuelCost field from the End-Reading query to the Fuel Economy query.

TipWhen opening a query to edit it, it might appear as in Figure 65. If you move your cursor over the black line (circled), it becomes a double headed arrow. Drag it to a lower position.

Figure 65: Appearance of query when opened for editing

Add the FuelCost field to the End-Reading query:

Right-click the End-Reading query and select Edit from the pop-up menu.

In the Fuel table list, double-click to add FuelCost to the bottom table (Figure 66).

Save and close the query.

Figure 66: Adding an additional field to the query

Add the FuelCost field from the End-Reading query to the Fuel Economy query:


Right-click the Fuel Economy query and select Edit from the pop-up menu.

Double-click the FuelCost field in the End-Reading query list to add it to the query table at the bottom.

Add a calculation field to the right of the FuelCost field.

Type the following in a Field cell in the table at the bottom:

"End-Reading".FuelCost/("End-Reading".Odometer – Fuel.Odometer)

Type the following in its Alias cell: cost per mile.

Note If you use the metric system, cost per km is the appropriate alias.

Save and close the query.

Open a new report.

Right-click the Fuel Economy query and select Report Wizard.

Select fields.

Move all the fields from the Available fields to the Fields in report list. Use the >> to do so. Click Next.

Label fields.

Change FuelCost to Fuel Cost by placing a space between the words. Click Next.

Group fields.

Use > to move the Date field to the Groupings list. Click Next.

Sort options: the wizard skipped this one.

Choose layout: accept the default. Click Next.

Create the report.

Change the report name to Fuel Statistics.

The default setting is Dynamic report, so no change is necessary.

Select Modify report layout.

Click Finish.

Modifying a report

At the end of the last section, we left the Fuel Statistics report open in the edit mode (Figure 67). We will be working on that report. These same steps can be used with any report that you open forediting.


Figure 67: A report in edit mode

The Author is the name you listed in Tools > Options > OpenOffice.org > User Data. The date is notcorrect. The columns need to be moved to the left to give a better appearance. None of the numbers are correct, but their only purpose is to show the number of decimal places.

Step 1: Change the date.

Click to the right of the date (4/26/20) so that the cursor is next to the field. Use the Backspace key to erase the date.

Insert > Fields > Date. This places today’s date where the original date was.

Change the date formatting:

Double-click the date field you just inserted. The Edit Fields: Document window opens.

Figure 68: Modifying a date field

Since this is a dynamic report, change the Select field from Date (fixed) to Date.

Change the Format to what you desire. (I use the Friday, December 31, 1999 choice.) Click OK.

Step 2: Change the column widths.

The column widths can be changed by moving the cursor over the right border of each column so that it becomes a double-headed arrow. Then drag and drop it to where you want it. This has to be done for each column in each table in the report. This can also be done with the last column on theright even though there is no black border. It should now look something like Figure 69.


Figure 69: Realigned columns in a report

Step 3: Change the number formatting in the cells.

The fuel quantity should have three decimal places. The Begin, End, and Distance should have one decimal place. Fuel Cost should be currency and have two decimal places, and Cost per mile should have three decimal places.

1) Right-click the cell below Quantity and select Number format. (The cell is circled in Figure 69.)

In the Options section (Figure 70),

Change the number of Decimal places to 3.

Click the green checkmark. Click OK.

Figure 70: Option section of the Number Formating window

Change the Cost per mile field.

Right-click in the cell below Fuel Cost.

Select Number Format.

In the Category list, select Currency. Click OK.

Change the Fuel Cost field.

Right-click in the cell below Cost per mile.

Select Number Format.

In the Category list, select Currency.

In the Option section:

Set the number of decimal places to 3.

Click the green checkmark.

Click OK.

Step 4: Save and close the report.

Double-click the report. It should now look like Figure 71.


Figure 71: Final report


Apendix 1 HSQL-SDBC internal query procedures

OverviewThe HSQLdb database engine included with Base supports the following functions and stored procedures for use within queries.

The Query component in Base allows for SQL commands that return a result set. i.e. SELECT and CALL

The component supports two views:

GUI Query Designer (Designer View) Text editor (SQL View)

Queries created and executed in Designer and SQL View support the use of named replaceable parameters in these statements, in most cases. Use of this feature is controlled by the option 'Escape Processing'.

Escape Processing is always ENABLED when using Designer View. Escape Processing is ENABLED by default in SQL View, but may be DISABLED by selecting the 'Run SQL directly' tool button.

The SQL window in Base (opened with the menu commands TOOLS > SQL) allows any valid SQL statement to be executed, but it does not return any data results to the user. Statements executed in this window serve two main purposes.

Data Manipulation Language ( DML ) statements. i.e. UPDATE, DELETE, INSERT. Data Definition Language ( DDL ) statements. i.e. CREATE TABLE, ALTER TABLE, etc.

Multiple statements may be executed as a batch by ending each statement with a semi-colon.

All functions listed below are available for use in the SQL window.

Each table below is formatted as follows:

Function Name - this is the actual function, along with required or optional parameters

Designer - Yes in this column means it may be used in Designer View. No, the function must be used in SQL View.

Esc Proc - Yes in this column means it may be used in SQL View, with escape processing ENABLED. No, the function is only available in SQL View with escape processing DISABLED.

Comments - A brief description of what the function does, the parameters expected and thetype of output generated.

Numerical Functions

Function Name Comments

ABS(d) Returns the absolute value of a number. ABS( -1 ) = ABS( 1 )

ACOS(d) Returns the arc cosine of an angle, in the range of 0.0 through pi. ACOS( .5 ) = 1.05


ASIN(d) Returns the arc sine of an angle, in the range of -pi/2 through pi/2. ASIN( .5 ) = 0.52

ATAN(d) Returns the arc tangent of an angle, in the range of -pi/2 through pi/2. ATAN( .5 ) = 0.46

ATAN2(a,b) Returns the tangent of a/b. ATAN2( 1, 2 ) = 0.46

BITAND(a,b) Returns a & b. BITAND( 0, 1 ) = 0

BITOR(a,b) Returns a | b BITOR( 0,1 ) = 1

BITXOR(a,b) Returns the bit-wise logical xor of the given integer values.BITXOR( 0, 1 ) = 1

CEILING(d) Rreturns the smallest integer that is not less than d CEILING( 8.7 ) = 9

COS(d) Returns the trigonometric cosine of an angle. COS( .5 ) = 0.88

COT(d) Returns the cotangent of an angle. COT( .5 ) = 1.83

DEGREES(d) Converts radians to degrees. DEGREES( 1 ) = 57.29577951

EXP(d) Returns the exponential number e (i.e., 2.718...) raised to the power of a double value. EXP( 2 ) = 7.389056

FLOOR(d) Returns the largest double value that is not greater than the d. FLOOR( -8.7 ) = -9

LOG(d)

Returns the natural logarithm (base e) of d. d must be greater than 0.0. LOG( 1.5 ) = 0.41 LOG( -1 ) = -1.#NAN

LOG10(d)

Returns the logarithm (base 10) of d. d must be greater than 0.0. LOG10( 1.5 ) = 0.18 LOG10( -1 ) = -1.#NAN


MOD(a,b) Returns a modulo b MOD( 7, 2 ) = 1

PI() The double value that is closer than any other to pi, the ratio of the circumference of a circle to its diameter. PI() = 3.14159265

POWER(a,b) Returns of value of the first argument, a, raised to the power of the second argument, b. POWER( 2, 2 ) = 4

RADIANS(d) Converts degrees to radians RADIANS( 1 ) = 0.01745329

RAND() Returns a random number x >= 0.0 and < 1.0 RAND() MIGHT EQUAL 0.34

ROUND(a,b) Rounds a to b digits after the decimal point. ROUND( 1.0333, 2 ) = 1.0300

ROUNDMAGIC(d)

solves certain rounding problems, specifically when numbers approach 0.0 such as 3.11-3.1-0.001 ROUNDMAGIC( 3.11-3.1-0.001 ) = 0.01 * Currently when used with escape processing enabled thereturn value is changed to a string. The workaround for this is to cast the result back to a dboule.CAST( ROUNDMAGIC( D ) AS DOUBLE ) See Issue#81031

SIGN( d ) Returns -1 if d is smaller than 0, 0 if d==0 and 1 if d is bigger than 0 SIGN( -0.001 ) = -1

SIN(d) Returns the trigonometric sine of an angle. d is an angle in radians SIN( PI() / 12 ) = 0.25881905

SQRT( d ) Returns the square root of d. <br. SQRT( 9 ) = 3

TAN( A ) Returns the trigonometric tangent of an angle, A. A - and angle in in radians. TAN( 0.01745329 * 20 ) = 0.36397018

TRUNCATE(a,b) Truncates a to b digits after the decimal point. TRUNCATE( 1.0333, 3 ) = 1.0330


String Functions


ASCII(s)

Returns the Unicode code value of the leftmost character ofs as an int. This is the same as the ASCII value if the string contains only ASCII characters. ASCII( 'ONE' ) = 79

BIT_LENGTH(str) Returns the length of the string in bits BIT_LENGTH ( 'ONE' ) = 48Note Each character is assumed to be 16 bits long.

CHAR(c)

Returns the character string corresponding to the given ASCII (or Unicode) value C.Note: In some SQL CLI implementations, a null is returned if the range is outside 0..255.In HSQLDB, the corresponding Unicode character is returnedunchecked.CHAR( 79 ) = O

CHAR_LENGTH(str) Returns the length of the string in characters CHAR_LENGTH('ONE') = 3

CONCAT(str1,str2) Returns str1 + str2 CONCAT( 'ONE', 'HUNDRED' ) = ONEHUNDRED

DIFFERENCE(s1,s2)

Returns the difference between the sound of s1 and s2. If either String is NULL, zero is returned. DIFFERENCE( 'SMITH', 'SMYTH' ) = 0 ; DIFFERENCE( 'WILD', 'CHILD' ) = 1 ; DIFFERENCE( 'TUPLE', 'SUPPLE' ) = 1 ; DIFFERENCE( 'BRAKE', 'BIKE' ) = 2

HEXTORAW(s1)

Returns translated string ; The given String must consist of a sequence of 4 digit hexidecimal character substrings. If its length is not evenly divisible by 4, null is returned. If any of its4 character subsequences cannot be parsed as a 4 digit, base 16 value, then a NumberFormatException is thrown.'00FF', '00ff00ff' is acceptable ; '0x00FF', 'FF' is NOT and will return nullHEXTORAW( '0041' ) = A ; HEXTORAW( 'FF41' ) = a ; HEXTORAW( '00410061' ) = Aa

INSERT(s,start,len,s2) Returns a character sequence which is the result of writing the first length number of characters from the second given String over the first string. The start position in the first string where the characters are overwritten is given by start. Note: In order of precedence, boundry conditions are handled as follows: if either supplied String is null, then the other is returned; the check starts with the first given String. if start is less than one, s1 is returned if length is less than or equal to zero, s1 is returned if the length of s2 is zero, s1 is returned


if start is greater than the length of s1, s1 is returned if length is such that, taken together with start, the indicated interval extends beyond the end of s1, then the insertion is performed precisely as if upon a copy of s1 extended in length to just include the indicated interval.

INSERT( 'How brown cow.', 5, 1, 'now ' ) = How now brown cow.

LCASE(s) Converts s to lower case LCASE( 'ONE' ) = one

LEFT(s,count)

Returns the leftmost count of characters of sNote: boundry conditions are handled in the following order of precedence: if s is null, then null is returned if count is less than 1, then a zero-length String is returned if count is greater than the length of s, then a copy of s is returned - requires double quoting - use SUBSTRING() instead LEFT( 'ONE', 2 ) = ON

LENGTH(s) Returns the number of characters in s LENGTH( 'ONE' ) = 3

LOCATE(search,s,[start])

Returns the first index (1=left, 0=not found) where search is found in s, starting at start LOCATE( 'ME', 'FIND ME IF YOU CAN', 1 ) = 6 ; LOCATE( 'ME', 'FIND ME IF YOU CAN', 7 ) = 0

LTRIM(s) Removes all leading blanks in s LTRIM( ' ONE ' ) = "ONE "

LOWER(s) Converts s to lower case LOWER( 'ONE' ) = one

OCTET_LENGTH(str) Returns the length of the string in bytes (twice the number of characters) OCTET_LENGTH( 'ONE' ) = 6

RAWTOHEX(s1)

Returns translated string, where s1 is any character string and returns the string representation of the characters as hexvalues RAWTOHEX( 'A' ) = 0041 ; RAWTOHEX( 'Aa' ) = 00410061

POSITION (<string expression> IN <string expression 1>)

If the first string is a sub-string of the second one, returns the position of the sub-string, counting from one; otherwise 0 POSITION ( 'THIS' IN 'THIS AND THAT' ) = 1

REPEAT(s,count) Returns s repeated count times REPEAT( 'X', 4 ) = XXXX


REPLACE(s,replace,s2) Replaces all occurrences of replace in s with s2 REPLACE( 'WHAT XXXX BROWN COW.', 'XXXX', 'NOW' ) =WHAT NOW BROWN COW.

RIGHT(s,count)

Returns the rightmost count of characters of s

Note:Boundry conditions are handled in the following order ofprecedence:if s is null, null is returnedif count is less than one, a zero-length String is returnedif count is greater than the length of s, a copy of s is returnedRIGHT( 'THIS AND THAT', 4 ) = THAT

RTRIM(s) Removes all trailing spaces RTRIM( ' ONE ' ) = " ONE"

SOUNDEX(s)

Returns a four character code representing the sound of s.Non-ASCCI characters in the input String are ignored.SOUNDEX( 'SMITH' ) = S530 ; SOUNDEX( 'SMYTH' ) = S530

SPACE(count) Returns a string consisting of count spaces SPACE( 4 ) = " "

SUBSTR(s,start[,len])SUBSTRING(s,start[,len])

Returns the substring starting at start (1=left) with length lenNote: The rules for boundary conditions on s, start and lengthare,in order of precedence:1.) if s is null, return null2.) If length is less than 1, return null.3.) If start is 0, it is treated as 1.4.) If start is positive, count from the beginning of s to find thefirst character postion.5.) If start is negative, count backwards from the end of s to find the first character.6.) If, after applying 2.) or 3.), the start position lies outside s, then return null7.) if length is ommited or is greated than the number of characters from the start position to the end of s, return the remaineder of s, starting with the start position.SUBSTR( 'HERE I AM', 6, 1 ) = I ; SUBSTR( 'HERE I AM', 6 )= I AM

SUBSTRING( s FROM start [FOR len] ) Alternate syntax where s may be a string expression SUBSTRING ( 'HERE I AM' FROM 6 FOR 1 ) = I ; SUBSTRING ( 'HERE I AM' FROM 6 ) = I AM

TRIM( [[ LEADING | TRAILING | BOTH ] [TRIMSTR]]FROM s )

Returns the character sequence s, with the leading, trailing orboth the leading and trailing occurences of the first character of the character sequence trimstr removed.If trimstr is not supplied SPACE is used.TRIM( BOTH FROM ' ONE ' ) = "ONE" ; TRIM ( BOTH 'O' FROM 'OONEOO' ) = NE* Note with escape processing DISABLED the command maybe abbreviated to TRIM ( FROM ' ONE ' ) AS "OUTPUT" = "ONE" - An alias must be used in this case also


UCASE(s) Converts s to upper case UCASE( 'one' ) = ONE

UPPER(s) Converts s to upper case UPPER( 'one' ) = ONE

Date and Time Functions


CURDATE()

Returns the current date. This is the current system date on your PC. CURDATE() = 09/01/07NOTE - The parenthesize are required.

CURTIME()

Returns the current time. This is the current system time on your PC. CURTIME() = 10:16:04 PMNOTE - The parenthesize are required.

DATEDIFF(string, datetime1, datetime2)

Returns the count of units of time elapsed from datetime1 to datetime2. The string indicates the unit of time and can have the following values 'ms'='millisecond', 'ss'='second','mi'='minute','hh'='hour', 'dd'='day', 'mm'='month', 'yy' = 'year'. Both the long and short form of the strings can be used.DATEDIFF('dd', '2007-08-01', '2007-09-01' ) = 31

DAYNAME(date) Returns the name of the day of the week.DAYNAME( '2007-09-01' ) = Saturday

DAYOFMONTH(date) Returns the day of the month (1-31)DAYOFMONTH( '2007-09-01' ) = 1

DAYOFWEEK(date) Returns the day of the week (1 means Sunday)DAYOFWEEK( '2007-09-01' ) = 7

DAYOFYEAR(date) Returns the day of the year (1-366)DAYOFYEAR( '2007-09-01' ) = 244

HOUR(time) Return the hour (0-23)HOUR( '21:16:04' )

MINUTE(time) Returns the minute (0-59)MINUTE( '21:16:04' ) = 16

MONTH(date) Returns the month (1-12)MONTH( '2007-09-01' ) = 9


MONTHNAME(date) Returns the name of the month,MONTHNAME( '2007-09-01' ) = September

NOW() Returns the current date and time as a timestamp) use of CURRENT_TIMESTAMP instead is suggestedNOW() = 09/01/07 10:34 PM

QUARTER(date) Returns the quarter (1-4), with the new year starting in JanuaryQUARTER( '2007-09-01' ) = 3

SECOND(time) Returns the second (0-59)SECOND( CURRENT_TIME ) MAY EQUAL 6

WEEK(date) Returns the week of this year (1-53)WEEK( '2007-09-01' ) = 35

YEAR(date) Returns the yearYEAR( '2007-09-01' ) = 2007

CURRENT_DATE Returns the current dateCURRENT_DATE = 09/01/07

CURRENT_TIME Returns the current timeCURRENT_TIME = 10:44:28 PM

CURRENT_TIMESTAMP Returns the current timestampCURRENT_TIMESTAMP = 09/01/07 10:34 PM

TO_CHAR( datetime, format String )

Returns a string from a date or datetime, based on the format maskFollowing is a list of valid format mask character sequences,

Chr seq returned value example

YYYY 4 digit year TO_CHAR( CURRENT_TIMESTAMP, 'YYYY' ) = 2007

YYYYYY

Last 3, 2 or 1 digits of year

TO_CHAR( CURRENT_TIMESTAMP, 'YY' ) = 07

IYYYIYYIY

Last 4, 3, 2 digits of ISO year

TO_CHAR( CURRENT_TIMESTAMP, 'IY' ) = 07

MM Month (01-12; JAN = 01)

TO_CHAR( CURRENT_TIMESTAMP, 'MM' ) = 09

MON Abbreviated name of month

TO_CHAR( CURRENT_TIMESTAMP, 'MON' ) = Sep


MONTH

Name of month, padded with blanks to length of 9 characters.

TO_CHAR( CURRENT_TIMESTAMP, 'MONTH' ) = September

w Week of year TO_CHAR( CURRENT_DATE, 'w' ) = 35

W Week of month TO_CHAR( CURRENT_DATE, 'W' ) = 1

IW

Week of year (1-52 or 1-53) based on the ISO standard.

TO_CHAR( CURRENT_DATE, 'IW' ) = 35

d Day of week (1-7)

TO_CHAR( CURRENT_DATE, 'd' ) = 1

D Abbreviation for day of week

TO_CHAR( CURRENT_DATE, 'D' ) = Sat

DDdd

Day of month as2 digits

TO_CHAR( CURRENT_DATE, 'DD' ) = 01

DDD Day of year TO_CHAR( CURRENT_DATE, 'DDD' ) =244

H Hour of day 0 - 23

TO_CHAR( CURRENT_TIME, 'H' ) = 23

HH Hour of day 0-11TO_CHAR( CURRENT_TIME, 'HH' ) = 11

m Minute of current hour

TO_CHAR( CURRENT_TIME, 'm' ) = 48

s Seconds of current minute

TO_CHAR( CURRENT_TIME, 's' ) = 33

a AM or PM TO_CHAR( CURRENT_TIME, 'a' ) = PM

All other characters

LITERALS

TO_CHAR( CURRENT_DATE, 'D - MON, dd YYYY' ) = Sat - Sep, 01 2007

System Functions


DATABASE() Returns the fully qualified file name of the Base file DATABASE() = C:\Documents and Settings\HP_Owner\My


Documents\Forum\ChucrchLibrary\new_library.odb

USER() Returns the name of the user connected to the Base database NOTE - This command requires use of the parentheses. USER() = SA

CURRENT_USER

Returns the name of the user connected to the Base database. This is actually a macro that calls the function USER(). NOTE - Use of parentheses is not allowed with this macro. CURRENT_USER = SA

IDENTITY() Returns the last identity value that was inserted by this connection.

Aggregate FunctionsAggregate functions are used to perform some computation against group of values. Each field in atable can be thought of as one group of values. Use of the GROUP BY clause in a select statement allows the creation of multiple value groups.


COUNT( Any | * ) Returns the count of not null entries in a column or when used with * the count of records.

MIN(d) Returns the smallest value in a group.

MAX(d) Returns the largest value in a group.

SUM(d) Adds all values in a group together.

AVG(d) Returns the average for the group of values.

SOME(b) Returns TRUE if any value in a group = TRUE

EVERY(b) Returns TRUE only if all values in a group = TRUE.

Statistical Functions


VAR_POP Returns the biased variance of a group of numbers.


VAR_SAMP Returns the sample variance of a group of numbers.

STDDEV_POP

STDDEV_SAMP

ModifiersYou may want to modify the results returned by a query to either limit the number of records returned or you may want to only returns records with unique values. This is accomplished by using the SELECT statement modifiers LIMIT, TOP, or DISTINCT.

In the case of LIMIT and TOP, Base does not allow their use without turning 'Escape Processing' off first. This is done in the query design window by 1) Turn of the GUI designer 2) Select the 'Run SQL Direct' toolbar button.

Example Data

TaskID StartDate EndDate Description

2 01/01/07 01/01/07 Task1

3 01/01/07 01/02/07 Task2

4 01/02/07 01/02/07 Task3

5 01/02/07 01/03/07 Task4

6 01/03/07 01/03/07 Task5

7 01/04/07 01/04/07 Task6

8 02/01/07 02/10/07 Task7

9 02/11/07 02/11/07 Task8

10 03/01/08 03/02/07 Task9

11 03/02/08 03/03/07 Task10

LimitThe modifier LIMIT can be used in either of two ways

Just after the word SELECT - when used it you must supply two parameters 'Starting Record' and 'Number of rows' separated by a space At the end of a select statement, IF the statement contains a HAVING, GROUP BY or ORDER BY clause. - Here you may supply one or two parameters. The 'number of rows' and optionally the 'Starting Record' designated by the word OFFSET

Examples:

SELECT LIMIT 3 2 "TaskID", "StartDate", "EndDate", "Description" FROM"Tasks"

This can be read as - return 2 rows, skipping the first 3 records in the result set. The returned result set would be


5 01/02/07 01/03/07 Task4

6 01/03/07 01/03/07 Task5


SELECT "TaskID", "StartDate", "EndDate", "Description" FROM "Tasks" ORDER BY "StartDate" DESC LIMIT 2 OFFSET 3

This example can be also be read as - return 2 rows, skipping the first 3 records of the result set after sorting by StartDate in descending order. The returned result set would now be

TaskID StartDate EndDate Description 8 02/01/07 02/10/07 Task7 7 01/04/07 01/04/07 Task6

TopThe modifier TOP is used to limit the number of records returned without an offset value. It must beincluded directly after the word SELECT and maybe used with any select statement.

SELECT TOP 2 "TaskID", "StartDate", "EndDate", "Description" FROM "Tasks" ORDER BY "StartDate" DESC

The returned result set


11 03/02/08 03/03/07 Task10

10 03/01/08 03/02/07 Task9 SELECT TOP 2 "TaskID", "StartDate", "EndDate", "Description" FROM "Tasks"

The returned result set


2 01/01/07 01/01/07 Task1

3 01/01/07 01/02/07 Task2

DistinctThe modifier DISTINCT limits the returned to rows to only those for which every row contains unique entries.


Appendix 2 – OpenOffice Basic

Database Apache OpenOffice has an integrated database interface (independent of any systems) called StarDatabase Connectivity (SDBC). The objective of developing this interface was to provide access toas many different data sources as possible.

To make this possible, data sources are accessed by drivers. The sources from which the drivers take their data is irrelevant to a SDBC user. Some drivers access file-based databases and take the data directly from them. Others use standard interfaces such as JDBC or ODBC. There are, however, also special drivers which access the MAPI address book, LDAP directories or Apache OpenOffice spreadsheets as data sources.

Since the drivers are based on UNO components, other drivers can be developed and therefore open up new data sources. You will find details about this in the Apache OpenOffice Developer's Guide.

Note – VBA : In terms of its concept, SDBC is comparable with the ADO and DAO libraries available in VBA. It permits high level access to databases, regardless of the underlying database backends.

SQL: a Query Language The SQL language is provided as a query language for users of SDBC. To compare the differencesbetween different SQL dialects, the SDBC components from Apache OpenOffice have their own SQL parser. This uses the query window to check the SQL commands typed and corrects simple syntax errors, such as those associated with uppercase and lowercase characters.

If a driver permits access to a data source that does not support SQL, then it must independently convert the transferred SQL commands to the native access needed.

Types of Database Access The database interface from Apache OpenOffice is available in the Apache OpenOffice Writer and Apache OpenOffice Calc applications, as well as in the database forms.

In Apache OpenOffice Writer, standard letters can be created with the assistance of SDBC data sources and these can then be printed out. You can also move data from the database window intotext documents using the drag-and- drop function.

If you move a database table into a spreadsheet, Apache OpenOffice creates a table area which can be updated at the click of the mouse if the original data has been modified. Conversely, spreadsheet data can be moved to a database table and a database import performed.

Finally, Apache OpenOffice provides a mechanism for forms based on databases. To do this, you first create a standard Apache OpenOffice Writer or Apache OpenOffice Calc form and then link thefields to a database.

All the options specified here are based on the user interface from Apache OpenOffice. No programming knowledge is needed to use the corresponding functions.

This section, however, provides little information about the functions specified, but instead concentrates on the programming interface from SDBC, which allows for automated database querying and therefore permits a much greater range of applications to be used.

Basic knowledge of the way in which databases function and the SQL query language is however needed to fully understand the following sections.


Data Sources A database is incorporated into Apache OpenOffice by creating what is commonly referred to as a data source. The user interface provides a corresponding option for creating data sources in the Extras menu. You can also create data sources and work with them using Apache OpenOffice Basic.

A database context object that is created using the createUnoService function serves as the starting point for accessing a data source. This based on the com.sun.star.sdb.DatabaseContext service and is the root object for all database operations.

The following example shows how a database context can be created and then used to determine the names of all data sources available. It displays the names in a message box.

Dim DatabaseContext As Object Dim Names Dim I As Integer DatabaseContext = createUnoService("com.sun.star.sdb.DatabaseContext")Names = DatabaseContext.getElementNames() For I = 0 To UBound(Names()) MsgBox Names(I) Next I

The individual data sources are based on the com.sun.star.sdb.DataSource service and can be determined from the database context using the getByName method:

Dim DatabaseContext As Object Dim DataSource As Object DatabaseContext = createUnoService("com.sun.star.sdb.DatabaseContext")DataSource = DatabaseContext.getByName("Customers")

The example creates a DataSource object for a data source called Customers.

Data sources provide a range of properties, which in turn provide general information about the origin of the data and information about access methods. The properties are:

Name (String) name of data source

URL (String) URL of data source in the form of jdbc: subprotocol : subname or sdbc: subprotocol : subname

Settings (Array) array containing PropertyValue-pairs with connection parameters (usually at least user name and password)

User (String) user name

Password (String) user password (is not saved)

IsPasswordRequired (Boolean) the password is needed and is interactively requested from user.

IsReadOnly (Boolean) permits read-only access to the database

Appendix 2 – OpenOffice Basic 69

NumberFormatsSupplier (Object) object containing the number formats available for the database (supports the com.sun.star.util.XNumberFormatsSupplier interface)

TableFilter (Array) list of table names to be displayed

TableTypeFilter (Array) list of table types to be displayed. Values available are TABLE, VIEW and SYSTEM TABLE

SuppressVersionColumns (Boolean) suppresses the display of columns that are used for version administration

Note – The data sources from Apache OpenOffice are not 1:1 comparable with the data sources in ODBC.

Whereas an ODBC data source only covers information about the origin of the data, a data source in Apache OpenOffice also includes a range of information about how the data is displayed within the database windows of Apache OpenOffice.

Queries Predefined queries can be assigned to a data source. Apache OpenOffice notes the SQL commands of queries so that they are available at all times. Queries are used to simplify working with databases because they can be opened with a simple mouse click and also provide users without any knowledge of SQL with the option of issuing SQL commands.

An object which supports the com.sun.star.sdb.QueryDefinition service is concealed behind a query. The queries are accessed by means of the QueryDefinitions method of the data source.

The following example lists the names of data source queries can be established in a message box.

Dim DatabaseContext As Object Dim DataSource As Object Dim QueryDefinitions As Object Dim QueryDefinition As Object Dim I As Integer DatabaseContext = createUnoService("com.sun.star.sdb.DatabaseContext")DataSource = DatabaseContext.getByName("Customers") QueryDefinitions = DataSource.getQueryDefinitions() For I = 0 To QueryDefinitions.Count() - 1

QueryDefinition = QueryDefinitions(I) MsgBox QueryDefinition.Name

Next I In addition to the Name property used in the example, the com.sun.star.sdb.QueryDefinition provides a whole range of other properties. These are:

Name (String) query name Command (String) SQL command (typically a SELECT command)

The following example shows how a query object can be created in a program-controlled manner and can be assigned to a data source.

Dim DatabaseContext As Object Dim DataSource As Object


Dim QueryDefinitions As Object Dim QueryDefinition As Object Dim I As Integer DatabaseContext = createUnoService("com.sun.star.sdb.DatabaseContext")DataSource = DatabaseContext.getByName("Customers") QueryDefinitions = DataSource.getQueryDefinitions() QueryDefinition = createUnoService("com.sun.star.sdb.QueryDefinition")QueryDefinition.Command = "SELECT * FROM Customer" QueryDefinitions.insertByName("NewQuery", QueryDefinition)

The query object is first created using the createUnoService call, then initialized, and then inserted into the QueryDefinitions object by means of insertByName.

Database Access A database connection is needed for access to a database. This is a transfer channel which permits direct communication with the database. Unlike the data sources presented in the previoussection, the database connection must therefore be re-established every time the program is restarted.

Apache OpenOffice provides various ways of establishing database connections. This example shows how to connect to an existing data source.

Dim DatabaseContext As Object Dim DataSource As Object Dim Connection As Object Dim InteractionHandler as Object DatabaseContext = createUnoService("com.sun.star.sdb.DatabaseContext")DataSource = DatabaseContext.getByName("Customers") If Not DataSource.IsPasswordRequired Then

Connection = DataSource.GetConnection("","") Else

InteractionHandler = createUnoService("com.sun.star.sdb.InteractionHandler") Connection = DataSource.ConnectWithCompletion(InteractionHandler)

End If The code used in the example first checks whether the database is password protected. If not, it creates the database connection required using the GetConnection call. The two empty strings in the command line stand for the user name and password.

If the database is password protected, the example creates an InteractionHandler and opens the database connection using the ConnectWithCompletion method. The InteractionHandler ensures that Apache OpenOffice asks the user for the required login data.

Iteration of Tables A table is usually accessed in Apache OpenOffice through the ResultSet object. A ResultSet is a type of marker that indicates a current set of data within a volume of results obtained using the SELECT command.

This example shows how a ResultSet can be used to query values from a database table.

Dim DatabaseContext As Object Dim DataSource As Object Dim Connection As Object Dim InteractionHandler as Object Dim Database Access Dim Statement As Object


Dim ResultSet As Object DatabaseContext = createUnoService("com.sun.star.sdb.DatabaseContext")DataSource = DatabaseContext.getByName("Customers") If Not DataSource.IsPasswordRequired Then

Connection = DataSource.GetConnection("","") Else

InteractionHandler = createUnoService("com.sun.star.sdb.InteractionHandler") Connection = DataSource.ConnectWithCompletion(InteractionHandler)

End If Statement = Connection.createStatement() ResultSet = Statement.executeQuery("SELECT ""CustomerNumber"" FROM ""Customer""") If Not IsNull(ResultSet) Then

While ResultSet.next MsgBox ResultSet.getString(1)

Wend End If

Once the database connection has been established, the code used in the example first uses the Connection.createObject call to create a Statement object.

This Statement object then uses the executeQuery call to return the actual ResultSet.

The program now checks whether the ResultSet actually exists and traverses the data records using a loop.

The values required (in the example, those from the CustomerNumber field) returns the ResultSet using the getString method, whereby the parameter 1 determines that the call relates to the values of the first column.

Note – VBA : The ResultSet object from SDBC is comparable with the Recordset object from DAO and ADO, since this also provides iterative access to a database.

– StarOffice 5 : The database is actually accessed in Apache OpenOffice through a ResultSet object. This reflects the content of a table or the result of a SQL-SELECT command. In the past, the ResultSet object provided the resident methods in the Application object for navigation within the data, for example, DataNextRecord.

Type-Specific Methods for Retrieving Values As can be seen in the example from the previous section, Apache OpenOffice provides a getString method for accessing table contents. The method provides the result in the form of a string. The following get methods are available:

getByte() supports the SQL data types for numbers, characters and strings

getShort() supports the SQL data types for numbers, characters and strings

getInt() supports the SQL data types for numbers, characters and strings

getLong() supports the SQL data types for numbers, characters and strings


getFloat() supports the SQL data types for numbers, characters and strings

getDouble() supports the SQL data types for numbers, characters and strings

getBoolean() supports the SQL data types for numbers, characters and strings

getString() supports all SQL data types

getBytes() supports the SQL data types for binary values

getDate() supports the SQL data types for numbers, strings, date and time stamp

getTime() supports the SQL data types for numbers, strings, date and time stamp

getTimestamp() supports the SQL data types for numbers, strings, date and time stamp

getCharacterStream() supports the SQL data types for numbers, strings and binary values

getUnicodeStream() supports the SQL data types for numbers, strings and binary values

getBinaryStream() binary values

getObject() supports all SQL data types

In all instances, the number of columns should be listed as a parameter whose values should be queried.

The ResultSet Variants Accessing databases is often a matter of critical speed. Apache OpenOffice provides several ways of optimizing ResultSets and thereby controlling the speed of access. The more functions a ResultSet provides, the more complex its implementation usually is and therefore the slower the functions are.

A simple ResultSet, provides the minimum scope of functions available. It only allows iteration to be applied forward, and for values to be interrogated. More extensive navigation options, such as the possibility of modifying values, are therefore not included.

The Statement object used to create the ResultSet provides some properties which allow the functions of the ResultSet to be influenced:

ResultSetConcurrency (const) specifications as to whether the data can be modified (specifications in accordance with com.sun.star.sdbc.ResultSetConcurrency).


ResultSetType (const) specifications regarding type of ResultSets ( specifications in accordance with com.sun.star.sdbc.ResultSetType).

The values defined in com.sun.star.sdbc.ResultSetConcurrency are:

UPDATABLE ResultSet permits values to be modified

READ_ONLY ResultSet does not permit modifications

The com.sun.star.sdbc.ResultSetConcurrency group of constants provides the following specifications:

FORWARD_ONLY ResultSet only permits forward navigation

SCROLL_INSENSITIVE ResultSet permits any type of navigation, changes to the original data are, however, not noted

SCROLL_SENSITIVE ResultSet permits any type of navigation, changes to the original data impact on the ResultSet

Note – VBA : A ResultSet containing the READ_ONLY and SCROLL_INSENSITIVE properties corresponds to a record set of the Snapshot type in ADO and DAO.

When using the ResultSet's UPDATEABLE and SCROLL_SENSITIVE properties, the scope of function of a ResultSet is comparable with a Dynaset type Recordset from ADO and DAO.

Methods for Navigation in ResultSets If a ResultSet is a SCROLL_INSENSITIVE or SCROLL_SENSITIVE type, it supports a whole range of methods for navigation in the stock of data. The central methods are:

next() navigation to the next data record

previous() navigation to the previous data record

first() navigation to the first data record

last() navigation to the last data record

beforeFirst() navigation to before the first data record

afterLast() navigation to after the last data record

All methods return a Boolean parameter which specifies whether the navigation was successful.

To determine the current cursor position, the following test methods are provided and all return a Boolean value:


isBeforeFirst() ResultSet is before the first data record

isAfterLast() ResultSet is after the last data record

isFirst() ResultSet is the first data record

isLast() ResultSet is the last data record

Modifying Data Records If a ResultSet has been created with the ResultSetConcurrency = UPDATEABLE value, then its content can be edited. This only applies for as long as the SQL command allows the data to be re-written to the database (depends on principle). This is not, for example, possible with complex SQLcommands with linked columns or accumulated values.

The ResultSet object provides Update methods for modifying values, which are structured in the same way as the get methods for retrieving values. The updateString method, for example, allows a string to be written.

After modification, the values must be transferred into the database using the updateRow()method.The call must take place before the next navigation command, otherwise the values will be lost.

If an error is made during the modifications, this can be undone using the cancelRowUpdates()method. This call is only available provided that the data has not be re-written into the database using updateRow().

Dialogs You can add custom dialog windows and forms to Apache OpenOffice documents. These in turn can be linked to Apache OpenOffice Basic macros to considerably extend the usage range of Apache OpenOffice Basic. Dialogs can, for example, display database information or guide users through a step-by-step process of creating a new document in the form of a Wizard.

Tip - You will find another description of dialogs in the Developer's Guide:

chapter Apache OpenOffice_Basic_IDE describes more fully the IDE

chapter Programming Dialogs and Dialog Controls shows more examples in Basic.

Working With Dialogs Apache OpenOffice Basic dialogs consist of a dialog window that can contain text fields, list boxes,radio buttons, and other control elements.

Creating Dialogs You can create and structure dialogs using the Apache OpenOffice dialog editor:

Create and structure dialogs in the dialog editor You can drag the control elements from the design pallet (right) into the dialog area, and define their position and size.

The example shows a dialog that contains a label and a list box.

A dialog containing a label and a list box


You can open a dialog with the following code:

Dim Dlg As Object DialogLibraries.LoadLibrary("Standard") Dlg = CreateUnoDialog(DialogLibraries.Standard.DlgDef) Dlg.Execute() Dlg.dispose()

CreateUnoDialog creates an object called Dlg that references the associated dialog. Before you can create the dialog, you must ensure that the library it uses (in this example, the Standard library) is loaded. The LoadLibrary method performs this task.

Once the Dlg dialog object has been initialized, you can use the Execute method to display the dialog. Dialogs such as this one are described as modal because they do not permit any other program action until they are closed.

While this dialog is open, the program remains in the Execute call.

The dispose method at the end of the code releases the resources used by the dialog once the program ends.

Closing Dialogs

Closing With OK or Cancel If a dialog contains an OK or a Cancel button, the dialog is automatically closed when you click oneof these buttons. More information about working with these buttons is discussed in Dialog Control Elements in Detail.

If you close a dialog by clicking the OK button, the Execute method returns a return value of 1, otherwise a value of 0 is returned.

Dim Dlg As Object DialogLibraries.LoadLibrary("Standard") Dlg = CreateUnoDialog(DialogLibraries.Standard.MyDialog) Select Case Dlg.Execute() Case 1

MsgBox "Ok pressed" Case 0

MsgBox "Cancel pressed" End Select

Working With Dialogs

Closing With the Close Button in the Title Bar You can close a dialog by clicking the close button on the title bar of the dialog window. The Execute method of the dialog returns the value 0, which is the same as when you click Cancel.

Closing With an Explicit Program Call You can also close an open dialog window with the endExecute method:

Dlg.endExecute() The Execute method of the dialog returns the value 0, which is the same as when you click Cancel.

Access to Individual Control Elements A dialog can contain any number of control elements. You can access these elements through the getControl method that returns the control element by name.


Dim Ctl As Object Ctl = Dlg.getControl("MyButton") Ctl.Label = "New Label"

This code determines the object for the MyButton control element and then initializes the Ctl object variable with a reference to the element. Finally the code sets the Label property of the control element to the New Label value.

Note – Unlike Apache OpenOffice Basic identifiers, the names of control elements are case sensitive.

Working With the Model of Dialogs and Control Elements The division between visible program elements (View) and the data or documents behind them (Model) occurs at many places in Apache OpenOffice API. In addition to the methods and properties of control elements, both dialog and control element objects have a subordinate Model object. This object allows you to directly access the content of a dialog or control element.

In dialogs, the distinction between data and depiction is not always as clear as in other API areas of Apache OpenOffice. Elements of the API are available through both the View and the Model.

The Model property provides program-controlled access to the model of dialog and control elementobjects.

Dim cmdNext As Object cmdNext = Dlg.getControl("cmdNext") cmdNext.Model.Enabled = False

This example deactivates the cmdNext button in the Dlg dialog with the aid of the model object from cmdNext.

Every control element has its own name that can be queried using the following model property:

Model.Name (String) control element name

You can specify the title that appears in the title bar of a dialog with the following model property:

Model.Title (String) dialog title (only applies to dialogs)

You can query the size and position of a control element using the following properties of the model object:

Model.Height (long) height of control element (in ma units)

Model.Width (long) width of control element (in ma units)

Model.PositionX (long) X-position of control element, measured from the left inner edge of the dialog (in ma units)

Model.PositionY (long) Y-position of control element, measured from top inner edge of the dialog (in ma units)

To ensure platform independence for the appearance of dialogs, Apache OpenOffice uses the Map AppFont (ma) internal unit to specify the position and size within dialogs. An ma unit is defined as being one eighth of the average height of a character from the system font defined in the operating system and one quarter of its width.


By using ma units, Apache OpenOffice ensures that a dialog looks the same on different systems under different system settings.

If you want to change the size or position of control elements for runtime, determine the total size of the dialog and adjust the values for the control elements to the corresponding part ratios.

Note – The Map AppFont (ma) replaces the Twips unit to achieve better platform independence.

Focus and Tabulator Sequence You can navigate through the control elements in any dialog by pressing the Tab key. The followingproperties are available in this context in the control elements model:

Model.Enabled (Boolean) activates the control element

Model.Tabstop (Boolean) allows the control element to be reached through the Tab key

Model.TabIndex (Long) position of control element in the order of activation

Finally, the control element provides a getFocus method that ensures that the underlying control element receives the focus:

getFocus control element receives the focus (only for dialogs)

Multi-Page Dialogs A dialog in Apache OpenOffice can have more than one tab page. The Step property of a dialog defines the current tab page of the dialog whereas the Step property for a control element specifiesthe tab page where the control element is to be displayed.

The Step-value of 0 is a special case. If you set this value to zero in a dialog, all of the control elements are visible regardless of their Step value. Similarly, if you set this value to zero for a control element, the element is displayed on all of the tab pages in a dialog.

Designing Page 1 of the dialog In the preceding example, you can also assign the Step value of 0 to the dividing line as well as theCancel, Prev, Next, and Done buttons to display these elements on all pages. You can also assign the elements to an individual tab page (for example page 1).

The following program code shows how the Step value in event handlers of the Next and Prev buttons can be increased or reduced and changes the status of the buttons.

Sub cmdNext_Initiated Dim cmdNext As Object Dim cmdPrev As Object

cmdPrev = Dlg.getControl("cmdPrev") cmdNext = Dlg.getControl("cmdNext") cmdPrev.Model.Enabled = Not cmdPrev.Model.Enabled cmdNext.Model.Enabled = False Dlg.Model.Step = Dlg.Model.Step + 1

End Sub

Sub cmdPrev_Initiated


Dim cmdNext As Object Dim cmdPrev As Object

cmdPrev = Dlg.getControl("cmdPrev") cmdNext = Dlg.getControl("cmdNext") cmdPrev.Model.Enabled = False cmdNext.Model.Enabled = True Dlg.Model.Step = Dlg.Model.Step - 1

End Sub A global Dlg variable that references an open dialog must be included to make this example possible. The dialog then changes its appearance as follows:

Page 1

Page 2

Tip - You can find an other OOoBasic example here.

Dialogs supporting several languages The strings of a Dialog can be localized, see the Developer's Guide chapter Dialog Localization.

Events Apache OpenOffice dialogs and forms are based on an event-oriented programming model where you can assign event handlers to the control elements. An event handler runs a predefined procedure when a particular action occurs. You can also edit documents or open databases with event handling as well as access other control elements.

Apache OpenOffice control elements recognize different types of events that can be triggered in different situations.

These event types can be divided into four groups:

Mouse control: Events that correspond to mouse actions (for example, simple mouse movements or a click on a particular screen location). Keyboard control: Events that are triggered by keyboard strokes. Focus modification: Events that Apache OpenOffice performs when control elements are activated or deactivated. Control element-specific events: Events that only occur in relation to certain control elements.

When you work with events, make sure that you create the associated dialog in the Apache OpenOffice development environment and that it contains the required control elements or documents (if you apply the events to a form).

The Apache OpenOffice Basic development environment The figure above shows the Apache OpenOffice Basic development environment with a dialog window that contains two list boxes. You can move the data from one list to the other using the buttons between the two list boxes.

If you want to display the layout on screen, then you should create the associated Apache OpenOffice Basic procedures so that they can be called up by the event handlers. Even though you can use these procedures in any module, it is best to limit their use to two modules.

To make your code easier to read, you should assign meaningful names to these procedures. Jumping directly to a general program procedure from a macro can result in unclear code. Instead, to simplify code maintenance and troubleshooting, you should create another procedure to serve as an entry point for event handling - even if it only executes a single call to the target procedure.


The code in the following example moves an entry from the left to the right list box of a dialog.

Sub cmdSelect_Initiated Dim lstEntries As Object Dim lstSelection As Object lstEntries = Dlg.getControl("lstEntries") lstSelection = Dlg.getControl("lstSelection") If lstEntries.SelectedItem > 0 Then lstSelection.AddItem(lstEntries.SelectedItem, 0) lstEntries.removeItems(lstEntries.SelectItemPos, 1) Else Beep End If End Sub

If this procedure was created in Apache OpenOffice Basic, you can assign it to an event required using the property window of the dialog editor.

The Assign Action dialog The Assign Action dialog lists all of the available Events. To assign a macro to an event:

1) Select the event 2) Click Macro... 3) Browse to and select the macro you want to assign 4) Click OK

Parameters The occurrence of a particular event is not always enough for an appropriate response. Additional information may be required. For example, to process a mouse click, you may need the screen position where the mouse button was pressed.

In Apache OpenOffice Basic, you can use object parameters to provide more information about an event to a procedure, for example:

Sub ProcessEvent(Event As Object) End Sub

The structure and properties of the Event object depend on the type of event that triggers the procedure call. Regardless of the type of event, all objects provide access to the relevant control element and its model.

The control element can be reached using Event.Source and its model using Event.Source.Model. You can use these properties to trigger an event within an event handler.

Mouse Events Apache OpenOffice Basic recognizes the following mouse events:

Mouse moved user moves mouse

Mouse moved while key pressed user drags mouse while holding down a key

Mouse button pressed user presses a mouse button


Note – This event is also used for notifying requests for a popup context menu on the control. In this case, the member PopupTrigger of the event passed to your macro function will be TRUE. In particular, if such a request is made by pressing the right mouse button on the control, the event will be fired twice: once for the popup menu request, and once for the real mouse event. If you are interested in only the mouse click, your macro should ignore all calls where PopupTrigger is TRUE.

Mouse button released user releases a mouse button

Mouse outside user moves mouse outside of the current window

The structure of the associated event objects is defined in the com.sun.star.awt.MouseEventstructure which provides the following information:

Events

Buttons (short) button pressed (one or more constants in accordance with com.sun.star.awt.MouseButton)

X (long) X-coordinate of mouse, measured in pixels from the top left corner of the control element

Y (long) Y-coordinate of mouse, measured in pixels from the top left corner of the control element

ClickCount (long) number of clicks associated with the mouse event (if Apache OpenOffice can respond fast enough, ClickCount is also 1 for a double-click because only an individual event is initiated)

The constants defined in com.sun.star.awt.MouseButton for the mouse buttons are:

LEFT left mouse button

RIGHT right mouse button

MIDDLE middle mouse button

The following example outputs the mouse position as well as the mouse button that was pressed:

Sub MouseUp(Event As Object) Dim Msg As String Msg = "Keys: " If Event.Buttons AND com.sun.star.awt.MouseButton.LEFT Then Msg = Msg & "LEFT " End If If Event.Buttons AND com.sun.star.awt.MouseButton.RIGHT Then Msg = Msg & "RIGHT " End If If Event.Buttons AND com.sun.star.awt.MouseButton.MIDDLE Then Msg = Msg & "MIDDLE " End If


Msg = Msg & Chr(13) & "Position: " Msg = Msg & Event.X & "/" & Event.Y MsgBox Msg End Sub

Note – VBA : The VBA Click and Doubleclick events are not available in Apache OpenOffice Basic.Instead use the Apache OpenOffice Basic MouseUp event for the click event and imitate the Doubleclick event by changing the application logic.

Keyboard Events The following keyboard events are available in Apache OpenOffice Basic:

Key pressed user presses a key.

Key released user releases a key

Both events relate to logical key actions and not to physical actions. If the user presses several keys to output a single character (for example, to add an accent to a character), then Apache OpenOffice Basic only creates one event.

A single key action on a modification key, such as the Shift key or the Alt key does not create an independent event.

Information about a pressed key is provided by the event object that Apache OpenOffice Basic supplies to the procedure for event handling. It contains the following properties:

KeyCode (short) code of the pressed key (default values in accordance with com.sun.star.awt.Key)

KeyChar (String) character that is entered (taking the modification keys into consideration)

The following example uses the KeyCode property to establish if the Enter key, the Tab key, or one of the other control keys has been pressed. If one of these keys has been pressed, the name of the key is returned, otherwise the character that was typed is returned:

Sub KeyPressed(Event As Object) Dim Msg As String Select Case Event.KeyCode

Case com.sun.star.awt.Key.RETURN Msg = "Return pressed"

Case com.sun.star.awt.Key.TAB Msg = "Tab pressed"

Case com.sun.star.awt.Key.DELETE Msg = "Delete pressed"

Case com.sun.star.awt.Key.ESCAPE Msg = "Escape pressed"

Case com.sun.star.awt.Key.DOWN Msg = "Down pressed"

Case com.sun.star.awt.Key.UP Msg = "Up pressed"

Case com.sun.star.awt.Key.LEFT Msg = "Left pressed"

Case com.sun.star.awt.Key.RIGHT Msg = "Right pressed"


Case Else Msg = "Character " & Event.KeyChar & " entered"

End Select MsgBox Msg

End Sub Information about other keyboard constants can be found in the API Reference under the com.sun.star.awt.Key group of constants.

Focus Events Focus events indicate if a control element receives or loses focus. You can use these events to, forexample, determine if a user has finished processing a control element so that you can update other elements of a dialog.

The following focus events are available:

When receiving focus element receives focus

When losing focus element loses focus

The Event objects for the focus events are structured as follows:

FocusFlags (short) cause of focus change (default value in accordance with com.sun.star.awt.FocusChangeReason)

NextFocus (Object) object that receives focus (only for the When losing focus event)

Temporary (Boolean) the focus is temporarily lost

Control Element-Specific Events In addition to the preceding events, which are supported by all control elements, there are also some control element-specific events that are only defined for certain control elements. The most important of these events are:

When Item Changed the value of a control element changes

Item Status Changed the status of a control element changes

Text modified the text of a control element changes

When initiating an action that can be performed when the control element is triggered (for example, a button is pressed)

When you work with events, note that some events, such as the When initiating event, can be initiated each time you click the mouse on some control elements (for example, on radio buttons). No action is performed to check if the status of the control element has actually changed. To avoid


such “blind events”, save the old control element value in a global variable, and then check to see if the value has changed when an event is executing.

The When initiating event is also noteworthy for the following reasons:

This event is initiated by either a key-press or a mouse button. Thus, it provides a consistent interface for users who navigate by mouse or by keyboard. When the Repeat property of a command button is set to True, this event is the one which is repeatedly sent, as long as the triggering action (key down or mouse-button down) remains in effect.

The properties for the Item Status Changed event are:

Selected (long) currently selected entry

Highlighted (long) currently highlighted entry

ItemId (long) ID of entry

Dialog Control Elements Apache OpenOffice Basic recognizes a range of control elements which can be divided into the following groups:

Entry fields Text fields Date fields Time fields Numerical fields Currency fields Fields adopting any format

Buttons Standard buttons Checkboxes Radio Buttons Selection

lists List boxes Combo-boxes Tree Control Other Scrollbars (horizontal and vertical) Fields of groups Progress bars Dividing lines (horizontal and vertical) Graphics File selection fields


Buttons A button performs an action when you click it.

The simplest scenario is for the button to trigger a When Initiating event when it is clicked by a user. You can also link another action to the button to close a dialog using the PushButtonType property. When you click a button that has this property set to the value of 0, the dialog remains unaffected. If you click a button that has this property set to the value of 1, the dialog is closed, andthe Execute method of the dialog returns the value 1 (dialog sequence has been ended correctly). If the PushButtonType has the value of 2, the dialog is closed and the Execute method of the dialog returns the value 0 (dialog closed). In the Dialog Editor, the property values are shown symbolically, as Default (0), Okay (1), and Cancel (2).

The following are some of the properties that are available through the button model:

Model.BackgroundColor (long) color of background

Model.DefaultButton (Boolean) The button is used as the default value and responds to the Enter key if it has no focus

Model.FontDescriptor (struct) structure that specifies the details of the font to be used (in accordance with com.sun.star.awt.FontDescriptor structure)

Model.Label (String) label that is displayed on the button

Model.Printable (Boolean) the control element can be printed

Model.TextColor (Long) text color of the control element

Model.HelpText (String) help text that is displayed when you move the mouse cursor over the control element

Model.HelpURL (String) URL of the online help for the corresponding control element

PushButtonType (short) action that is linked to the button (0: no action, 1: OK, 2: Cancel)

Option Buttons These buttons are generally used in groups and allow you to select from one of several options. When you select an option, all of the other options in the group are deactivated. This ensures that at any one time, only one option button is set. An option button control element provides two properties:

State (Boolean) activates the button

Label (String) label that is displayed on the button

You can also use the following properties from the model of the option buttons:


Model.FontDescriptor (struct) structure with details of the font to be used (in accordance with com.sun.star.awt.FontDescriptor)

Model.Label (String) label that is displayed on the control element

Model.Printable (Boolean) control element can be printed

Model.State (Short) if this property is equal to 1, the option is activated, otherwise it is deactivated

Model.TextColor (Long) text color of control element

Model.HelpText (String) help text that is displayed when the mouse cursor rests over the control element

Model.HelpURL (String) URL of online help for the corresponding control element

To combine several option buttons in a group, you must position them one after another in the activation sequence without any gaps (Model.TabIndex property, described as Order in the dialog editor). If the activation sequence is interrupted by another control element, then Apache OpenOffice automatically starts with a new control element group that can be activated regardless of the first group of control elements.

Note – VBA : Unlike VBA, you cannot insert option buttons in a group of control elements in Apache OpenOffice Basic. The grouping of control elements in Apache OpenOffice Basic is only used to ensure a visual division by drawing a frame around the control elements.

Checkboxes Checkboxes are used to record a Yes or No value and depending on the mode, they can adopt twoor three states.

In addition to the Yes and No states, a check box can have an in-between state if the corresponding Yes or No status has more than one meaning or is unclear.

Checkboxes provide the following properties:

State (Short) state of the checkbox (0: no, 1: yes, 2: in-between state)

Label (String) label for the control element

enableTriState (Boolean) in addition to the activated and deactivated states, you can also use the in-between state

The model object of a checkbox provides the following properties:

Model.FontDescriptor (struct) structure with details of the font used (in accordance with com.sun.star.awt.FontDescriptor structure)


Model.Label (String) label for the control element


Model.State (Short) state of the checkbox (0: no, 1: yes, 2: in-between state)

Model.Tabstop (Boolean) the control element can be reached with the Tab key


Model.HelpText (String) help text that is displayed when you rest the mouse cursor over the control element


Text Fields Text fields allow users to type numbers and text. The com.sun.star.awt.UnoControlEdit. service forms the basis for text fields.

A text field can contain one or more lines and can be edited or blocked for user entries. Text fields can also be used as special currency and numerical fields as well as screen fields for special tasks. As these control elements are based on the UnoControlEdit Uno service, their program-controlled handling is similar.

Text fields provide the following properties:

Text (String) current text

SelectedText (String) currently highlighted text

Selection (Struct) read-only highlighting of details (structure in accordance with com.sun.star.awt.Selection, with the Min and Max properties to specify the start and end of the current highlighting)

MaxTextLen (short) maximum number of characters that you can type in the field

Editable (Boolean) True activates the option for entering text, False blocks the entry option (the property cannot becalled up directly but only through IsEditable)

IsEditable (Boolean) the content of the control element can be changed, read-only

The following properties are provided through the associated model object:


Model.Align (short) orientation of text (0: left-aligned, 1: centered, 2: right-aligned)

Model.BackgroundColor (long) color of the background of the control element

Model.Border (short) type of border (0: no border, 1: 3D border, 2: simple border)

Model.EchoChar (String) echo character for password fields

Model.FontDescriptor (struct) structure with details of font used (in accordance with com.sun.star.awt.FontDescriptor structure)

Model.HardLineBreaks (Boolean) automatic line breaks are permanently inserted in the control element text

Model.HScroll (Boolean) the text has a horizontal scrollbar

Model.MaxTextLen (Short) maximum length of text, where 0 corresponds to no length limit

Model.MultiLine (Boolean) permits entry to spans several lines


Model.ReadOnly (Boolean) the content of the control element is read-only


Model.Text (String) text associate with the control element


Model.VScroll (Boolean) the text has a vertical scrollbar

Model.HelpText (String) help text that is displayed when the mouse cursor rests over the control element


List Boxes List boxes (com.sun.star.awt.UnoControlListBox service) support the following properties:


ItemCount (Short) number of elements, read-only

SelectedItem (String) text of highlighted entry, read-only

SelectedItems (Array Of Strings) data field with highlighted entries, read-only

SelectedItemPos (Short) number of the entry highlighted at present, read-only

SelectedItemsPos (Array of Short) data field with the number of highlighted entries (for lists which support multiple selection), read-only

MultipleMode (Boolean) True activates the option for multiple selection of entries, False blocks multiple selections (the property cannot be called up directly but only through IsMultipleMode)

IsMultipleMode (Boolean) permits multiple selection within lists, read-only

List boxes provide the following methods:

addItem (Item, Pos) enters the string specified in the Item into the list at the Pos position

addItems (ItemArray, Pos) enters the entries listed in the string's ItemArray data field into the list at the Pos position

removeItems (Pos, Count) removes Count entries as of the Pos position

selectItem (Item, SelectMode) activates or deactivates highlighting for the element specified in the string Item depending on the SelectMode Boolean variable

makeVisible (Pos) scrolls through the list field so that the entry specified with Pos is visible

The model object of the list boxes provides the following properties:

Model.BackgroundColor (long) background color of control element

Model.Border (short) type of border (0: no border, 1: 3D border, 2: simple border)

Model.FontDescriptor (struct) structure with details of font used (in accordance with com.sun.star.awt.FontDescriptor structure)

Model.LineCount (Short) number of lines in control element


Model.MultiSelection (Boolean) permits multiple selection of entries

Model.SelectedItems (Array of Strings) list of highlighted entries

Model.StringItemList (Array of Strings) list of all entries


Model.ReadOnly (Boolean) the content of the control element is read-only



Model.HelpText (String) automatically displayed help text which is displayed if the mouse cursor is above the control element


Note – VBA : The VBA option for issuing list entries with a numerical additional value (ItemData) does not exist in Apache OpenOffice Basic. If you want to administer a numerical value (for example a database ID) in addition to the natural language text, you must create an auxiliary data field that administers in parallel to the list box.

Forms In many respects, the structure of Apache OpenOffice forms corresponds to the dialogs. There are,however, a few key differences:

Dialogs appear in the form of one single dialog window, which is displayed over the document and does not permit any actions other than dialog processing until the dialog is ended. Forms, on the other hand, are displayed directly in the document, just like drawing elements. A dialog editor is provided for creating dialogs, and this can be found in the Apache OpenOffice Basic development environment. Forms are created using the Form Controls and the Form Design Toolbar directly within the document. Whereas the dialog functions are available in all Apache OpenOffice documents, the full scope of the form functions are only available in text and spreadsheets. The control elements of a form can be linked with an external database table. This function is not available in dialogs. The control elements of dialogs and forms differ in several aspects.

Users who want to provide their forms with their own methods for event handling, should refer to the Dialogs chapter. The mechanisms explained there are identical to those for forms.


Working With Forms Apache OpenOffice forms may contain text fields, list boxes, radio buttons, and a range of other control elements, which are inserted directly in a text or spreadsheet. The Form Functions Toolbar is used for editing forms.

A Apache OpenOffice form may adopt one of two modes: the draft mode and the display mode. In draft mode, the position of control elements can be changed and their properties can be edited using a properties window.

The Form Functions Toolbar is also used to switch between modes.

Determining Object Forms Apache OpenOffice positions the control elements of a form at drawing object level. The actual object form can be accessed through the Forms list at the drawing level. The objects are accessed as follows in text documents:

Dim Doc As Object Dim DrawPage As Object Dim Form As Object Doc = ThisComponent DrawPage = Doc.DrawPage Form = DrawPage.Forms.GetByIndex(0)

The GetByIndex method returns the form with the index number 0.

When working with spreadsheets, an intermediate stage is needed for the Sheets list because the drawing levels are not located directly in the document but in the individual sheets:

Dim Doc As Object Dim Sheet As Object Dim DrawPage As Object Dim Form As Object Doc = ThisComponent Sheet = Doc.Sheets.GetByIndex(0) DrawPage = Sheet.DrawPage Form = DrawPage.Forms.GetByIndex(0)

As is already suggested by the GetByIndex method name, a document may contain several forms. This is useful, for example, if the contents of different databases are displayed within one document, or if a 1:n database relationship is displayed within a form. The option of creating sub-forms is also provided for this purpose.

The Three Aspects of a Control Element Form A control element of a form has three aspects:

The Model of the control element is the key object for the Apache OpenOffice Basic-programmer when working with control element forms. The counterpart to this is the View of the control element, which administers the display information. Since control element forms within the documents are administered like a special drawing element, there is also a Shape object which reflects the drawing element-specific propertiesof the control element (in particular its position and size).

Accessing the Model of Control Element Forms The models of the control elements of a form are available through the GetByName method of the Object form:

Dim Doc As Object


Dim Form As Object Dim Ctl As Object Doc = ThisComponent Form = Doc.DrawPage.Forms.GetByIndex(0) Ctl = Form.getByName("MyListBox")

The example determines the model of the MyListBox control element, which is located in the first form of the text document currently open.

If you are not sure of the form of a control element, you can use the option for searching through allforms for the control element required:

Dim Doc As Object Dim Forms As Object Dim Form As Object Dim Ctl As Object Dim I as Integer Doc = ThisComponent Forms = Doc.Drawpage.Forms For I = 0 To Forms.Count - 1 Form = Forms.GetbyIndex(I) If Form.HasByName("MyListBox") Then Ctl = Form.GetbyName("MyListBox") Exit Function End If Next I

The example uses the HasByName method to check all forms of a text document to determine whether they contain a control element model called MyListBox. If a corresponding model is found,then a reference to this is saved in the Ctl variable and the search is terminated.

Accessing the View of Control Element Forms To access the view of a control element form, you need the associated model. The view of the control element can then be determined with the assistance of the model and using the document controller.

Dim Doc As Object Dim DocCrl As Object Dim Forms As Object Dim Form As Object Dim Ctl As Object Dim CtlView As Object Dim I as Integer Doc = ThisComponent DocCrl = Doc.getCurrentController() Forms = Doc.Drawpage.Forms For I = 0 To Forms.Count - 1 Form = Forms.GetbyIndex(I) If Form.HasByName("MyListBox") Then Ctl = Form.GetbyName("MyListBox") CtlView = DocCrl.GetControl(Ctl) Exit Function End If Next I

The code listed in the example is very similar to the code listed in the previous example for determining a control element model. It uses not only the Doc document object but also the DocCrldocument controller object which makes reference to the current document window. With the help


of this controller object and the model of the control element, it then uses the GetControl method todetermine the view (CtlView variable) of the control element form.

Accessing the Shape Object of Control Element Forms The method for accessing the shape objects of a control element also uses the corresponding drawing level of the document. To determine a special control element, all drawing elements of the drawing level must be searched through.

Dim Doc As Object Dim Shape as Object Dim I as integer Doc = ThisComponent For i = 0 to Doc.DrawPage.Count - 1 Shape = Doc.DrawPage(i) If HasUnoInterfaces(Shape, "com.sun.star.drawing.XControlShape") Then If Shape.Control.Name = "MyListBox" Then Exit Function End If End If Next

The example checks all drawing elements to determine whether they support the com.sun.star.drawing.XControlShape interface needed for control element forms. If this is the case, the Control.Name property then checks whether the name of the control element is MyListBox. If this is true, the function ends the search.

Determining the Size and Position of Control Elements As already mentioned, the size and position of control elements can be determined using the associated shape object. The control element shape, like all other shape objects, provides the Sizeand Position properties for this purpose:

Size (struct) size of control element (com.sun.star.awt.Size data structure)

Position (struct) position of control element (com.sun.star.awt.Point data structure)

The following example shows how the position and size of a control element can be set using the associated shape object:

Dim Shape As Object Dim Point As New com.sun.star.awt.Point Dim Size As New com.sun.star.awt.Size ' ... Initialize Shape object, as previously shown ... Point.x = 1000 Point.y = 1000 Size.Width = 10000 Size.Height = 10000 Shape.Size = Size Shape.Position = Point

The shape object of the control element must already be known if the code is to function. If this is not the case, it must be determined using the preceding code.


Control Element Forms The control elements available in forms are similar to those of dialogs. The selection ranges from simple text fields through list and combo boxes to various buttons.

Below, you will find a list of the most important properties for control element forms. All properties form part of the associated model objects.

In addition to the standard control elements, a table control element is also available for forms, which enables the complete incorporation of database tables. This is described in the Database Forms chapter.

Buttons The model object of a form button provides the following properties:

BackgroundColor (long) background color

DefaultButton (Boolean) the button serves as a default value. In this case, it also responds to the entry button if it has nofocus

Enabled (Boolean) the control element can be activated

Tabstop (Boolean) the control element can be reached through the tabulator button

TabIndex (Long) position of control element in activation sequence

FontName (String) name of font type

FontHeight (Single) height of character in points (pt)

Tag (String) string containing additional information, which can be saved in the button for program-controlled access

TargetURL (String) target URL for buttons of the URL type

TargetFrame (String) name of window (or frame) in which TargetURL is to be opened when activating the button (for buttons of the URL type)

Label (String) button label

TextColor (Long) text color of control element

HelpText (String) automatically displayed help text which is displayed if the mouse cursor is above the control element


HelpURL (String) URL of online help for the corresponding control element

ButtonType (Enum) action that is linked with the button (default value from com.sun.star.form.FormButtonType)

State (Short) in toggle button, 1 = pushed, 0 = normal

Through the ButtonType property, you have the opportunity to define an action that is automaticallyperformd when the button is pressed. The associated com.sun.star.form.FormButtonType group of constants provides the following values:

PUSH standard button

SUBMIT end of form entry (particularly relevant for HTML forms)

RESET resets all values within the form to their original values

URL call of the URL defined in TargetURL (is opened within the window which was specified throughTargetFrame)

The OK and Cancel button types provided in dialogs are not supported in forms.

Option Buttons The following properties of an option button are available through its model object:


Tabstop (Boolean) the control element can be reached through the tab key

TabIndex (Long) position of control element in the activation sequence




Label (String) inscription of button

Printable (Boolean) the control element can be printed


State (Short) if 1, the option is activated, otherwise it is deactivated

RefValue (String) string for saving additional information (for example, for administering data record IDs)


HelpText (String) automatically displayed help text, which is displayed if the mouse cursor is above the control element


The mechanism for grouping option buttons distinguishes between the control elements for dialogsand forms.

Whereas control elements appearing one after another in dialogs are automatically combined to form a group, grouping in forms is performed on the basis of names. To do this, all option buttons of a group must contain the same name. Apache OpenOffice combines the grouped control elements into an array so that the individual buttons of a Apache OpenOffice Basic program can bereached in the same way.

The following example shows how the model of a control element group can be determined. Dim Doc As Object Dim Forms As Object Dim Form As Object Ctl As Object Dim I as Integer Doc = ThisComponent Forms = Doc.Drawpage.Forms For I = 0 To Forms.Count - 1 Form = Forms.GetbyIndex(I) If Form.HasByName("MyOptions") Then Ctl = Form. GetGroupbyName("MyOptions") Exit Function End If Next I

The code corresponds to the previous example for determining a simple control element model. It searches through all forms in the current text document in a loop and uses the HasByName method to check whether the corresponding form contains an element with the MyOptions name it is searching for. If this is the case, then the model array is accessed using the GetGroupByName method (rather than the GetByName method to determine simple models).

Checkboxes The model object of a checkbox form provides the following properties:








Label (String) button label


State (Short) if 1, the option is activated, otherwise it is deactivated

RefValue (String) string for saving additional information (for example, for administrating data record IDs)




Text Fields The model objects of text field forms offer the following properties:

Align (short) orientation of text (0: left-aligned, 1: centered, 2: right-aligned)

BackgroundColor (long) background color of control element

Border (short) type of border (0: no border, 1: 3D border, 2: simple border)

EchoChar (String) echo character for password field




HardLineBreaks (Boolean) the automatic line breaks are permanently inserted in the text of the control element

HScroll (Boolean) the text has a horizontal scrollbar

MaxTextLen (Short) maximum length of text; if 0 is specified, there are no limits

MultiLine (Boolean) permits multi-line entries


ReadOnly (Boolean) the content of the control element is read-only



TabIndex (Long) position of the control element in the activation sequence



Text (String) text of control element


VScroll (Boolean) the text has a vertical scrollbar



List Boxes The model object of the list box forms provides the following properties:

BackgroundColor (long) background color of control element


Border (short) type of border (0: no border, 1: 3D frame, 2: simple frame)

FontDescriptor (struct) structure with details of font to be used (in accordance with com.sun.star.awt.FontDescriptor structure)

LineCount (Short) number of lines of control element

MultiSelection (Boolean) permits multiple selection of entries

SelectedItems (Array of Strings) list of highlighted entries

StringItemList (Array of Strings) list of all entries

ValueItemList (Array of Variant) list containing additional information for each entry (for example, for administrating data record IDs)


ReadOnly (Boolean) the content of the control element is read-only






Tag (String) string containing additional information which can be saved in the button for program-controlledaccess





Note – VBA : Through their ValueItemList property, list box forms provide a counterpart to the VBA property, ItemData, through which you can administer additional information for individual list entries.

Furthermore, the following methods are provided though the view object of the list box:

addItem (Item, Pos) inserts the string specified in the Item at the Pos position in the list

addItems (ItemArray, Pos) inserts the entries listed in the string's ItemArray data field in the list at the Pos position

removeItems (Pos, Count) removes Count entries as of the Pos position

selectItem (Item, SelectMode) activates or deactivates the highlighting for the element specified in the string Item depending on the SelectMode variable

makeVisible (Pos) scrolls through the list field so that the entry specified by Pos is visible

Database Forms Apache OpenOffice forms can be directly linked to a database. The forms created in this way provide all the functions of a full database front end without requiring independent programming work.

You can page through and search in the selected tables and queries, as well as change data records and insert new data records. Apache OpenOffice automatically ensures that the relevant data is retrieved from the database, and that any changes made are written back to the database.

A database form corresponds to a standard Apache OpenOffice form. In addition to the standard properties, the following database-specific properties must also be set in the form:

DataSourceName (String) name of data source (refer to Database Access; the data source must be globally created in Apache OpenOffice)

Command (String) name of table, query, or the SQL select command to which a link is to be made

CommandType (Const) specifies whether the Command is a table, a query or a SQL command (value from com.sun.star.sdb.CommandType enumeration)

The com.sun.star.sdb.CommandType enumeration covers the following values:

TABLE Table

QUERY Query


COMMAND SQL command

The database fields are assigned to the individual control elements through this property:

DataField (String) name of linked database field

Tables Another control element is provided for work with databases, the table control element. This represents the content of a complete database table or query. In the simplest scenario, a table control element is linked to a database using the autopilot form, which links all columns with the relevant database fields in accordance with the user specifications.
