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

2011-09-06T17:04:54Z

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

New page

<section begin=title /><noinclude>{{DISPLAYTITLE:</noinclude>Control Element Forms in Detail<noinclude>}}</noinclude><section end=title />{{BreadCrumbL10n}}

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

__NOTOC__

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 [[EN/documentation/basic_guide/database_forms|Database Forms]] chapter.

== Buttons ==

The model object of a form button provides the following properties:

;<tt>BackgroundColor (long)</tt>:background color
;<tt>DefaultButton (Boolean)</tt>:the button serves as a default value. In this case, it also responds to the entry button if it has no focus
;<tt>Enabled (Boolean)</tt>:the control element can be activated
;<tt>Tabstop (Boolean)</tt>:the control element can be reached through the tabulator button
;<tt>TabIndex (Long)</tt>:position of control element in activation sequence
;<tt>FontName (String)</tt>:name of font type
;<tt>FontHeight (Single)</tt>:height of character in points (pt)
;<tt>Tag (String)</tt>:string containing additional information, which can be saved in the button for program-controlled access
;<tt>TargetURL (String)</tt>:target URL for buttons of the URL type
;<tt>TargetFrame (String)</tt>:name of window (or frame) in which <tt>TargetURL</tt> is to be opened when activating the button (for buttons of the <tt>URL</tt> type)
;<tt>Label (String)</tt>:button label
;<tt>TextColor (Long)</tt>:text color of control element
;<tt>HelpText (String)</tt>:automatically displayed help text which is displayed if the mouse cursor is above the control element
;<tt>HelpURL (String)</tt>:URL of online help for the corresponding control element
;<tt>ButtonType (Enum)</tt>:action that is linked with the button (default value from <idl>com.sun.star.form.FormButtonType</idl>)
;<tt>State (Short)</tt>:in toggle button, 1 = pushed, 0 = normal

Through the <tt>ButtonType</tt> property, you have the opportunity to define an action that is automatically performed when the button is pressed. The associated <idl>com.sun.star.form.FormButtonType</idl> group of constants provides the following values:

;<tt>PUSH</tt>:standard button
;<tt>SUBMIT</tt>:end of form entry (particularly relevant for HTML forms)
;<tt>RESET</tt>:resets all values within the form to their original values
;<tt>URL</tt>:call of the URL defined in <tt>TargetURL</tt> (is opened within the window which was specified through <tt>TargetFrame</tt>)

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:

;<tt>Enabled (Boolean)</tt>:the control element can be activated
;<tt>Tabstop (Boolean)</tt>:the control element can be reached through the tab key
;<tt>TabIndex (Long)</tt>:position of control element in the activation sequence
;<tt>FontName (String)</tt>:name of font type
;<tt>FontHeight (Single)</tt>:height of character in points (pt)
;<tt>Tag (String)</tt>:string containing additional information, which can be saved in the button for program-controlled access
;<tt>Label (String)</tt>:inscription of button
;<tt>Printable (Boolean)</tt>:the control element can be printed
;<tt>State (Short)</tt>:if 1, the option is activated, otherwise it is deactivated
;<tt>RefValue (String)</tt>:string for saving additional information (for example, for administering data record IDs)
;<tt>TextColor (Long)</tt>:text color of control element
;<tt>HelpText (String)</tt>:automatically displayed help text, which is displayed if the mouse cursor is above the control element
;<tt>HelpURL (String)</tt>: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. {{OOo}} combines the grouped control elements into an array so that the individual buttons of a {{OOo}} Basic program can be reached in the same way.

The following example shows how the models of the control elements of a group can be iterated, exemplary displaying the states of all control elements in a given group:

<source lang="oobas">
Function test
Dim oGroup as object
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

Form = Forms.GetbyIndex(0)

oForm.getGroupByName("MyOptions", oGroup)
msg = ""
for i = LBound(oGroup) to UBound(oGroup)
oCtl = oGroup(i)
msg = msg + oCtl.Name + ": " + (str(oCtl.State)) + chr(10)
next i
MsgBox msg

end Function
</source>

The code corresponds to the previous example for determining a simple control element model. It accesses the array of models using the <tt>GetGroupByName</tt> method (rather than the <tt>GetByName</tt> method to determine simple models).

== Checkboxes ==

The model object of a checkbox form provides the following properties:

;<tt>Enabled (Boolean)</tt>:the control element can be activated
;<tt>Tabstop (Boolean)</tt>:the control element can be reached through the tab key
;<tt>TabIndex (Long)</tt>:position of control element in the activation sequence
;<tt>FontName (String)</tt>:name of font type
;<tt>FontHeight (Single)</tt>:height of character in points (pt)
;<tt>Tag (String)</tt>:string containing additional information, which can be saved in the button for program-controlled access
;<tt>Label (String)</tt>:button label
;<tt>Printable (Boolean)</tt>:the control element can be printed
;<tt>State (Short)</tt>:if 1, the option is activated, otherwise it is deactivated
;<tt>RefValue (String)</tt>:string for saving additional information (for example, for administrating data record IDs)
;<tt>TextColor (Long)</tt>:text color of control element
;<tt>HelpText (String)</tt>:automatically displayed help text, which is displayed if the mouse cursor is above the control element
;<tt>HelpURL (String)</tt>:URL of online help for the corresponding control element

== Text Fields ==

The model objects of text field forms offer the following properties:

;<tt>Align (short)</tt>:orientation of text (0: left-aligned, 1: centered, 2: right-aligned)
;<tt>BackgroundColor (long)</tt>:background color of control element
;<tt>Border (short)</tt>:type of border (0: no border, 1: 3D border, 2: simple border)
;<tt>EchoChar (String)</tt>:echo character for password field
;<tt>FontName (String)</tt>:name of font type
;<tt>FontHeight (Single)</tt>:height of character in points (pt)
;<tt>HardLineBreaks (Boolean)</tt>:the automatic line breaks are permanently inserted in the text of the control element
;<tt>HScroll (Boolean)</tt>:the text has a horizontal scrollbar
;<tt>MaxTextLen (Short)</tt>:maximum length of text; if 0 is specified, there are no limits
;<tt>MultiLine (Boolean)</tt>:permits multi-line entries
;<tt>Printable (Boolean)</tt>:the control element can be printed
;<tt>ReadOnly (Boolean)</tt>:the content of the control element is read-only
;<tt>Enabled (Boolean)</tt>:the control element can be activated
;<tt>Tabstop (Boolean)</tt>:the control element can be reached through the tab key
;<tt>TabIndex (Long)</tt>:position of the control element in the activation sequence
;<tt>FontName (String)</tt>:name of font type
;<tt>FontHeight (Single)</tt>:height of character in points (pt)
;<tt>Text (String)</tt>:text of control element
;<tt>TextColor (Long)</tt>:text color of control element
;<tt>VScroll (Boolean)</tt>:the text has a vertical scrollbar
;<tt>HelpText (String)</tt>:automatically displayed help text, which is displayed if the mouse cursor is above the control element
;<tt>HelpURL (String)</tt>:URL of online help for the corresponding control element

== List Boxes ==

The model object of the list box forms provides the following properties:

;<tt>BackgroundColor (long)</tt>:background color of control element
;<tt>Border (short)</tt>:type of border (0: no border, 1: 3D frame, 2: simple frame)
;<tt>FontDescriptor (struct)</tt>:structure with details of font to be used (in accordance with <idl>com.sun.star.awt.FontDescriptor</idl> structure)
;<tt>LineCount (Short)</tt>:number of lines of control element
;<tt>MultiSelection (Boolean)</tt>:permits multiple selection of entries
;<tt>SelectedItems (Array of Strings)</tt>:list of highlighted entries
;<tt>StringItemList (Array of Strings)</tt>:list of all entries
;<tt>ValueItemList (Array of Variant)</tt>:list containing additional information for each entry (for example, for administrating data record IDs)
;<tt>Printable (Boolean)</tt>:the control element can be printed
;<tt>ReadOnly (Boolean)</tt>:the content of the control element is read-only
;<tt>Enabled (Boolean)</tt>:the control element can be activated
;<tt>Tabstop (Boolean)</tt>:the control element can be reached through the tab key
;<tt>TabIndex (Long)</tt>:position of control element in the activation sequence
;<tt>FontName (String)</tt>:name of font type
;<tt>FontHeight (Single)</tt>:height of character in points (pt)
;<tt>Tag (String)</tt>:string containing additional information which can be saved in the button for program-controlled access
;<tt>TextColor (Long)</tt>:text color of control element
;<tt>HelpText (String)</tt>:automatically displayed help text, which is displayed if the mouse cursor is above the control element
;<tt>HelpURL (String)</tt>:URL of online help for the corresponding control element

{{VBAnote|Through their <tt>ValueItemList</tt> property, list box forms provide a counterpart to the VBA property, <tt>ItemData</tt>, 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:

;<tt>addItem (Item, Pos)</tt>:inserts the string specified in the <tt>Item</tt> at the <tt>Pos</tt> position in the list
;<tt>addItems (ItemArray, Pos)</tt>:inserts the entries listed in the string's <tt>ItemArray</tt> data field in the list at the <tt>Pos</tt> position
;<tt>removeItems (Pos, Count)</tt>:removes <tt>Count</tt> entries as of the <tt>Pos</tt> position
;<tt>selectItem (Item, SelectMode)</tt>:activates or deactivates the highlighting for the element specified in the string <tt>Item</tt> depending on the <tt>SelectMode</tt> variable
;<tt>makeVisible (Pos)</tt>:scrolls through the list field so that the entry specified by <tt>Pos</tt> is visible

{{PDL1}}

EN/documentation/basic guide/control element forms - Revision history

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