Documentation/BASIC Guide/Control Elements

BASIC Guide

{{{parttitle}}}

[[{{{PrevPart}}}|< Previous Section ]]

[[{{{NextPart}}}|Next Section >]]

• The Language of Apache OpenOffice Basic

• Overview of a Basic Program
• Working With Variables
• Strings
• Numbers
• Boolean Values
• Date and Time
• Arrays
• Scope and Life Span of Variables
• Constants
• Operators
• Branching
• Loops
• Procedures and Functions
• Error Handling
• Other Instructions

• Runtime Library

• Conversion Functions
• Strings
• Date and Time
• Files and Directories
• Message and Input Boxes
• Other Functions

• Introduction to the API

• Universal Network Objects (UNO)
• Properties and Methods
• Modules, Services and Interfaces
• Tools for Working with UNO
• Overview of Central Interfaces

• Working with Documents

• The StarDesktop
• Styles and Templates

• Text Documents

• The Structure of Text Documents
• Editing Text Documents
• More than Just Text

• Spreadsheet Documents

• The Structure of Spreadsheets
  • Rows and Columns
  • Cells and Ranges
  • Formatting Spreadsheet Documents
• Editing Spreadsheet Documents

• Drawings and Presentations

• The Structure of Drawings
• Editing Drawing Objects
• Presentations

• Charts (Diagrams)

• Using Charts in Spreadsheets
• The Structure of Charts
• Chart Types

• Databases

• SQL: a Query Language
• Types of Database Access
• Data Sources
• Database Access

• Dialogs

• Working With Dialogs
• Properties
• Events
• Dialog Control Elements

• Forms

• Working With Forms
• Control Element Forms
• Database Forms

< Previous Page

Next Page >

Apache OpenOffice Basic recognizes a range of control elements which can be divided into the following groups:

Entry fields	Buttons	Selection lists	Other
Text fields Date fields Time fields Numerical fields Currency fields Fields adopting any format	Standard buttons Checkboxes Radio Buttons	List boxes Combo-boxes Tree Control	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, and the 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)

Example

The following example shows some of the properties for the buttons:

 Sub cmdButton()
 Dim oDialog As Object Dim ocmdButton As Object
      DialogLibraries.LoadLibrary( "Standard" )
     oDialog = CreateUnoDialog( DialogLibraries.Standard.getByName("myDialog") )
      ocmdButton = oDialog.getControl("cmdOK")
     With ocmdButton.getModel
         .Align = 1                'Orientation; 0 = left, 1 = center, 2 = right
         .FontHeight = 12            'Size
         .FontName = "FreeSans"        'Font type
         .ImageURL = ConvertToUrl("/home/mau/bien.jpg")    'Image to show
         .ImagePosition = 1        'Position 1 = center right
         .PushButtonType = 1        'Type of button 1 = Accept
     End With

     ocmdButton = oDialog.getControl("cmdCancel")
     With ocmdButton.getModel
         .Align = 1
         .FontHeight = 12
         .FontName = "FreeSans"
         .ImageURL = ConvertToUrl("/home/mau/mal.jpg")
         .ImagePosition = 1
         .PushButtonType = 2        'Type of button 2 = Cancel
     End With

     oDialog.execute()
     oDialog.dispose()
 
End Sub

Checkboxes

Checkboxes are used to record a Yes or No value and depending on the mode, they can adopt two or 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.Printable (Boolean)

the control element can be printed

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.TextColor (Long)

text color of control element

Model.HelpText (String)

help text that is displayed when you rest the mouse cursor over the control element

Model.HelpURL (String)

URL of online help for the corresponding control element

Example

The following example shows some of the properties for the checkboxes:

Sub Checkbox1()
 Dim oDialog As Object
 Dim oControl As Object

DialogLibraries.LoadLibrary( "Standard" )
     oDialog = CreateUnoDialog( DialogLibraries.Standard.getByName("MyDialog") )      'Image control
     oControl = oDialog.getControl("icFoto")     'we hide it
     oControl.Visible = False      'Checkbox
     oControl = oDialog.getControl("chkImprimir")
      With oControl.getModel
         .TriState = True        'Triple state
     End With
 
oDialog.execute()
oDialog.dispose()
 
End Sub

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.

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.

Example

An example voor the grouped option button:

 Sub OptionButton1()
 Dim oDialog As Object
 Dim oControl As Object
 
   DialogLibraries.LoadLibrary( "Standard" )
     oDialog = CreateUnoDialog( DialogLibraries.Standard.getByName("MyDialog") )      'Hide the previous controls.
     oControl = oDialog.getControl("icFoto") : oControl.Visible = False
     oControl = oDialog.getControl("chkImprimir") : oControl.Visible = False
 
     'First option button
     oControl = oDialog.getControl("optUbuntu")
     MsgBox oControl.State 

     'Second option button
     oControl = oDialog.getControl("optFedora")
     MsgBox oControl.State
 
     'Third option button
     oControl = oDialog.getControl("optArch")
     MsgBox oControl.State
 
oDialog.execute()
oDialog.dispose()
 
End Sub

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 be called 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.Printable (Boolean)

the control element can be printed

Model.ReadOnly (Boolean)

the content of the control element is read-only

Model.Tabstop (Boolean)

the control element can be reached with the Tab key

Model.Text (String)

text associate with the control element

Model.TextColor (Long)

text color of 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

Model.HelpURL (String)

URL of online help for the corresponding control element

Example

 Sub TextField1()
 Dim oDialog As Object
 Dim oControl As Object 
    DialogLibraries.LoadLibrary( "Standard" )
     oDialog = CreateUnoDialog( DialogLibraries.Standard.getByName("MyDialog") )      'The text field control
     oControl = oDialog.getControl("txtNombre")
     'Set an align property
     oControl.getModel.Align=1
     'Show the dialog box
     oDialog.execute()     'we show the control on close
     MsgBox oControl.Text
     oDialog.dispose()
 
End Sub

Date Fields

A date field makes it possible to enter, display and edit date values. com.sun.star.awt.UnoControlDateField

Time Fields

A time field makes it possible to enter, display, and edit time values. com.sun.star.awt.UnoControlTimeField

Numerical Fields

A numeric field makes it possible to enter, display and edit formatted numeric values. com.sun.star.awt.UnoControlNumericalField

Currency Fields

A currency field makes it possible to enter, display and edit currency values. com.sun.star.awt.UnoControlCurrencyField

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.Printable (Boolean)

the control element can be printed

Model.ReadOnly (Boolean)

the content of the control element is read-only

Model.Tabstop (Boolean)

the control element can be reached with the Tab key

Model.TextColor (Long)

text color of control element

Model.HelpText (String)

automatically displayed help text which is displayed if the mouse cursor is above the control element

Model.HelpURL (String)

URL of online help for the corresponding control element

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.

Combo Boxes

Combo boxes (com.sun.star.awt.UnoControlComboBox service) support the following properties:

Tree Control

Tree boxes (com.sun.star.awt.tree.TreeControlModel service) support the following properties:

Content on this page is licensed under the Public Documentation License (PDL).