Basic Programmer's Guide > Forms

StarOffice(tm) 7 Office Suite

Basic Programmer's Guide |

## Forms

Previous · Start · Next

In many respects, the structure of StarOffice-forms corresponds to the dialogs discussed in the previous chapter. 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 StarOffice Basic development environment. Forms are created using the Form Functions Toolbar directly within the document.

- Whereas the dialog functions are available in all StarOffice 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 Chapter 11 (Dialogs). The mechanisms explained there are identical to those for forms.

## Working with Forms

StarOffice 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 StarOffice 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

StarOffice positions the control elements of a form at drawing object level. The actual object form can be accessed through the Forms list at drawing level. The objects are accessed as follows in text documents:

Dim Doc As Object

Dim DrawPage As Object

Dim Form As Object

Doc = StarDesktop.CurrentComponent

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 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 = StarDesktop.CurrentComponent

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:

- First, there is the Model of the control element. This is the key object for the StarOffice 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 properties of 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 = StarDesktop.CurrentComponent

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 is not sure of the form of a control element, you can use the option for searching through all forms 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 = StarDesktop.CurrentComponent

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, the associated model is first needed. 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 = StarDesktop.CurrentComponent

DocCrl = Doc.getCurrentControler()

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 DocCrl document 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 to determine 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 = StarDesktop.CurrentComponent

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 Size and 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

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 in Detail

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 section in chapter 11.

### 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 no focus.

- 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).

Through the ButtonType property, you have the opportunity to define an action that is automatically performed 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 through TargetFrame).

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:

- Enabled (Boolean) – the control element can be activated.

- Tabstop (Boolean) – the control element can be reached through the tab key.

- TabIndex (Long) – position of control element in the 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.

- 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).

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

The mechanism for grouping option buttons distinguishes between the control elements for dialogs and 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. StarOffice combines the grouped control elements into an array so that the individual buttons of a StarOffice Basic program can be reached in the same way as previously.

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

Dim Ctl As Object

Dim I as Integer

Doc = StarDesktop.CurrentComponent

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:

- Enabled (Boolean) – the control element can be activated.

- Tabstop (Boolean) – the control element can be reached through the tab key.

- TabIndex (Long) – position of control element in the 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.

- Label (String) – button label.

- 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 administrating data record IDs).

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

### 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.

- FontName (String) – name of font type.

- FontHeight (Single) – height of character in points (pt).

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

- Printable (Boolean) – the control element can be printed.

- ReadOnly (Boolean) – the content of the control element is read-only.

- Enabled (Boolean) – the control element can be activated.

- Tabstop (Boolean) – the control element can be reached through the tab key.

- TabIndex (Long) – position of the control element in the activation sequence.

- FontName (String) – name of font type.

- FontHeight (Single) – height of character in points (pt).

- Text (String) – text of control element.

- TextColor (Long) – text color of control element.

- VScroll (Boolean) – the text has a vertical scrollbar.

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

### 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).

- Printable (Boolean) – the control element can be printed.

- ReadOnly (Boolean) – the content of the control element is read-only.

- Enabled (Boolean) – the control element can be activated.

- Tabstop (Boolean) – the control element can be reached through the tab key.

- TabIndex (Long) – position of control element in the 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.

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

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

StarOffice 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.

The user has the option of paging through and searching the selected tables and queries, as well as changing data records and inserting new data records. StarOffice 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 basically corresponds to a standard StarOffice 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 Chapter 10, Database Access; Database access; the data source must be globally created in StarOffice).

- 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. Because the associated API is relatively complex, we shall not provide a complete description of the API at this point.

© 2003 Sun Microsystems, Inc.