Sancho: Основной текст

2011-09-06T17:01:34Z

Основной текст

New page

<section begin=title /><noinclude>{{DISPLAYTITLE:</noinclude>Working with Forms<noinclude>}}</noinclude><section end=title />{{BreadCrumbL10n}}

{{Documentation/BASICGuideTOC
|ShowPrevNext=block
|ShowPrevPage=block
|PrevPage=EN/documentation/basic_guide/forms
|NextPage=EN/documentation/basic_guide/control_element_forms
|form=block
}}

__NOTOC__

{{OOo}} 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 {{OOo}} 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 ==

{{OOo}} 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:

<source lang="oobas">
Dim Doc As Object
Dim DrawPage As Object
Dim Form As Object

Doc = ThisComponent
DrawPage = Doc.DrawPage
Form = DrawPage.Forms.GetByIndex(0)
</source>

The <tt>GetByIndex</tt> 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:

<source lang="oobas">
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)
</source>

As is already suggested by the <tt>GetByIndex</tt> 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 {{OOo}} 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 <tt>GetByName</tt> method of the Object form:

<source lang="oobas">
Dim Doc As Object
Dim Form As Object
Dim Ctl As Object

Doc = ThisComponent
Form = Doc.DrawPage.Forms.GetByIndex(0)
Ctl = Form.getByName("MyListBox")
</source>

The example determines the model of the <tt>MyListBox</tt> 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 all forms for the control element required.

<source lang="oobas">
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
</source>

The example uses the <tt>HasByName</tt> method to check all forms of a text document to determine whether they contain a control element model called <tt>MyListBox</tt>. If a corresponding model is found, then a reference to this is saved in the <tt>Ctl</tt> variable and the search is terminated. The example is shown as in-line code, for clarity; in practice, the search would be inside a function, called with the name as a string parameter, and include error processing.

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

<source lang="oobas">
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
</source>

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 <tt>Doc</tt> document object but also the <tt>DocCrl</tt> 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 <tt>GetControl</tt> method to determine the view (<tt>CtlView</tt> 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.

<source lang="oobas">
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
</source>

The example checks all drawing elements to determine whether they support the <idl>com.sun.star.drawing.XControlShape</idl> interface needed for control element forms. If this is the case, the <tt>Control.Name</tt> property then checks whether the name of the control element is <tt>MyListBox</tt>. 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 <tt>shape</tt> object. The control element shape, like all other <tt>shape</tt> objects, provides the <tt>Size</tt> and <tt>Position</tt> properties for this purpose:

;<tt>Size (struct)</tt>:size of control element (<idl>com.sun.star.awt.Size</idl> data structure)
;<tt>Position (struct)</tt>:position of control element (<idl>com.sun.star.awt.Point</idl> data structure)

The following example shows how the position and size of a control element can be set using the associated shape object:

<source lang="oobas">
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
</source>

The <tt>shape</tt> 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.

{{PDL1}}

EN/documentation/basic guide/working with forms - Revision history

Sancho: Основной текст