Forms

When a control is inserted into a document, it is stored in a form. Forms are contained in draw pages, which implement the com.sun.star.form.XFormsSupplier interface. The visible portion of the control-what you see-is stored in a draw page and represented by a ControlShape. The data model for the control is stored in a form and referenced by the ControlShape. The method getForms() returns an object that contains the forms for the draw page (see Table 19 ).

Table 19: Some methods supported by the com. sun. star. form. Forms service.

Method	Description
createEnumeration()	Create an enumeration of the forms.
getByIndex(Long)	Get a form by index.
getByName(String)	Get a form by name .
getCount()	Get the number of forms.
hasByName(String)	Return True if the form with the specified name exists.
hasElements()	Return True if the page contains at least one form.
insertByIndex(Long, Form)	Insert a form by index.
insertByName(String, Form)	Insert a form by name.
removeByIndex(Long)	Remove a form by index.
removeByName(String)	Remove the named form.
replaceByIndex(Long, Form)	Replace a form by index.
replaceByName(String, Form)	Replace a form by name.

The purpose of Listing 28 is to demonstrate how to add a form to a draw page. Forms are not interesting unless they contain a control, so Listing 28 adds a drop-down list box with some values to select.

Listing 28: AddAForm is found in the Graphic module in this chapter's source code files as SC15.sxi.

 Sub AddAForm   Dim oPage            'Page on which to draw   Dim oShape           'Shape to insert   Dim oDoc             'ThisComponent   Dim oForm            'Individual form   Dim oControlModel    'Model for a control   Dim s (0 To 5) As String   REM Data for the combo box!   s(0) = "Zero"   : s(1) = "One"   : s(2) = "Two"   s(3) = "Three"  : s(4) = "Four"  : s(5) = "Five"   oDoc = ThisComponent   oPage = createDrawPage(oDoc, "Test Draw", True)   REM Create a shape for the control.   oShape = oDoc.createInstance("com.sun.star.drawing.ControlShape")   oShape.Position = createPoint(1000, 1500)   oShape.Size = createSize(2500, 800)   REM Create a combo box model.   oControlModel = oDoc.createInstance("com.sun.star.form.component.ComboBox")   oControlModel.Name = "NumberSelection"   oControlModel.Text = "Zero"   oControlModel.Dropdown = True   oControlModel.StringItemList = s()   REM Set the shape's control model!   oShape.Control = oControlModel   oForm = oDoc.createInstance("com.sun.star.form.component.Form")   oForm.Name = "NumberForm"   oPage.Forms.insertByIndex( 0, oForm )   REM Add the control model to the first form in the collection.   oForm.insertByIndex( 0, oControlModel )   oPage.add( oShape ) End Sub 

 

Regular forms, as created by Listing 28, group form components (described in Table 20 ) together. A DataForm, however, can connect to a database and display the results of SQL queries. An HTMLForm, on the other hand, contains controls specific to HTML pages.

Table 20: Control components that can be added to forms.

Component	Description
CheckBox	Check box control.
ComboBox	Provides text input or selection from a list of text values.
CommandButton	A clickable button.
CurrencyField	An edit field with a currency value.
DatabaseCheckBox	A data-aware check box that can be bound to a database field.
DatabaseComboBox	A data-aware combo box that can be bound to a database field.
DatabaseCurrencyField	A data-aware edit field with a currency value that can be bound to a database field.
DatabaseDateField	A data-aware date field that can be bound to a database field.
DatabaseFormattedField	A data-aware formatted field that can be bound to a database field.
DatabaseImageControl	A field for displaying images stored in a database.
DatabaseListBox	A data-aware list box that can be bound to a database field.
DatabaseNumericField	A data-aware numeric field that can be bound to a database field.
DatabasePatternField	A data-aware pattern field that can be bound to a database field.
DatabaseRadioButton	A data-aware radio button that can be bound to a database field.
DatabaseTextField	A data-aware text field that can be bound to a database field.
DatabaseTimeField	A data-aware time field that can be bound to a database field.
DateField	An edit field with a date value.
FileControl	An edit field for a file name.
FixedText	Display text that cannot be edited by the user .
FormattedField	An edit field that contains formatted text.
GridControl	Display data in a table-like way.
GroupBox	A control that can visually group controls.
HiddenControl	A control that is hidden.
ImageButton	A clickable button which is represented by an image.
ListBox	A control with multiple values from which to choose.
NumericField	An edit field with a numeric value.
PatternField	An edit field with text that matches a pattern.
RadioButton	A radio button.
TextField	A text-edit field that supports single-line and multi-line data.
TimeField	An edit field with a time value.