OpenOffice.org BASIC Guide - OpenOffice.org wiki
OpenOffice.org BASIC Guide - OpenOffice.org wiki
OpenOffice.org BASIC Guide - OpenOffice.org wiki
Create successful ePaper yourself
Turn your PDF publications into a flip-book with our unique Google optimized e-Paper software.
<strong>OpenOffice</strong>.<strong>org</strong> 3.1<br />
<strong>BASIC</strong> <strong>Guide</strong>
Copyright<br />
This document is published under the PDL. See: http://www.openoffice.<strong>org</strong>/licenses/<br />
PDL.html
3<br />
Contents<br />
Copyright........................................................................................................................2<br />
Preface.......................................................................................9<br />
1 <strong>OpenOffice</strong>.<strong>org</strong> <strong>BASIC</strong> Programming <strong>Guide</strong>..................................11<br />
2 The Language of <strong>OpenOffice</strong>.<strong>org</strong> <strong>BASIC</strong>.......................................15<br />
Program Lines .............................................................................................................16<br />
Comments ...................................................................................................................17<br />
Markers .......................................................................................................................17<br />
Implicit Variable Declaration ........................................................................................18<br />
Explicit Variable Declaration ........................................................................................19<br />
From a Set of ASCII Characters to Unicode.................................................................20<br />
String Variables............................................................................................................21<br />
Specification of Explicit Strings....................................................................................22<br />
Integer Variables .........................................................................................................22<br />
Long Integer Variables ................................................................................................23<br />
Single Variables ..........................................................................................................23<br />
Double Variables .........................................................................................................23<br />
Currency Variables ......................................................................................................24<br />
Floats ..........................................................................................................................24<br />
Specification of Explicit Numbers ................................................................................24<br />
Defining Arrays ............................................................................................................27<br />
Defining values for arrays ...........................................................................................30<br />
Accessing Arrays ........................................................................................................31<br />
Array Creation, value assignment and access example ..............................................31
Local Variables ............................................................................................................31<br />
Public Domain Variables .............................................................................................32<br />
Global Variables ..........................................................................................................33<br />
Private Variables .........................................................................................................33<br />
Defining Constants ......................................................................................................34<br />
Scope of Constants .....................................................................................................34<br />
Predefined Constants ..................................................................................................34<br />
Mathematical Operators ..............................................................................................35<br />
Logical Operators ........................................................................................................35<br />
Comparison Operators ................................................................................................36<br />
If...Then...Else..............................................................................................................36<br />
Select...Case................................................................................................................37<br />
For...Next.....................................................................................................................39<br />
For Each......................................................................................................................39<br />
Do...Loop.....................................................................................................................40<br />
While...Wend................................................................................................................41<br />
Programming Example: Sorting With Embedded Loops .............................................41<br />
Procedures ..................................................................................................................42<br />
Functions ....................................................................................................................43<br />
Terminating Procedures and Functions Prematurely ..................................................44<br />
Passing Parameters ....................................................................................................44<br />
Optional Parameters ...................................................................................................45<br />
Recursion ....................................................................................................................46<br />
The On Error Instruction ..............................................................................................47<br />
The Resume Command ..............................................................................................47<br />
Queries Regarding Error Information ..........................................................................48<br />
Tips for Structured Error Handling ...............................................................................48<br />
Type...End Type...........................................................................................................50<br />
With...End With............................................................................................................51<br />
3 The Runtime Library of <strong>OpenOffice</strong>.<strong>org</strong> Basic..............................55<br />
Implicit and Explicit Type Conversions ........................................................................56<br />
Checking the Content of Variables ..............................................................................58<br />
Working with Sets of Characters .................................................................................60<br />
Accessing Parts of a String .........................................................................................60<br />
Search and Replace ...................................................................................................61
Formatting Strings .......................................................................................................62<br />
Specification of Date and Time Details within the Program Code ...............................64<br />
Extracting Date and Time Details ................................................................................65<br />
Retrieving System Date and Time ...............................................................................66<br />
Administering Files ......................................................................................................67<br />
Writing and Reading Text Files ....................................................................................71<br />
Displaying Messages ..................................................................................................74<br />
Input Box For Querying Simple Strings .......................................................................75<br />
Beep ............................................................................................................................76<br />
Shell ............................................................................................................................76<br />
Wait and WaitUntil .......................................................................................................77<br />
Environ ........................................................................................................................77<br />
4 Introduction to the API...............................................................79<br />
Properties ....................................................................................................................81<br />
Methods ......................................................................................................................81<br />
The supportsService Method ......................................................................................83<br />
Debug Properties ........................................................................................................83<br />
API Reference .............................................................................................................84<br />
Creating Context-Dependent Objects .........................................................................84<br />
Named Access to Subordinate Objects .......................................................................85<br />
Index-Based Access to Subordinate Objects ..............................................................87<br />
Iterative Access to Subordinate Objects ......................................................................88<br />
5 Working with <strong>OpenOffice</strong>.<strong>org</strong> Documents....................................89<br />
ThisComponent ...........................................................................................................90<br />
Basic Information about Documents in <strong>OpenOffice</strong>.<strong>org</strong> ..............................................91<br />
Creating, Opening and Importing Documents .............................................................92<br />
Document Objects ......................................................................................................95<br />
Details about various formatting options ...................................................................100<br />
6 Text Documents.......................................................................103<br />
Paragraphs and Paragraph Portions .........................................................................104<br />
The TextCursor ..........................................................................................................113<br />
Searching for Text Portions .......................................................................................118<br />
Replacing Text Portions ............................................................................................121<br />
Tables ........................................................................................................................123<br />
Text Frames ..............................................................................................................128
Text Fields .................................................................................................................131<br />
Bookmarks ................................................................................................................135<br />
7 Spreadsheet Documents...........................................................137<br />
Spreadsheets ............................................................................................................138<br />
Rows and Columns....................................................................................................139<br />
Cells and Ranges.......................................................................................................141<br />
Formatting Spreadsheet Documents.........................................................................147<br />
Cell Ranges ..............................................................................................................161<br />
Searching and Replacing Cell Contents ....................................................................164<br />
8 Drawings and Presentations.....................................................167<br />
Pages ........................................................................................................................168<br />
Elementary Properties of Drawing Objects ...............................................................169<br />
An Overview of Various Drawing Objects ..................................................................180<br />
Grouping Objects ......................................................................................................187<br />
Rotating and Shearing Drawing Objects ...................................................................189<br />
Searching and Replacing ..........................................................................................190<br />
Working With Presentations ......................................................................................191<br />
9 Charts (Diagrams)....................................................................193<br />
Title, Subtitle and Legend .........................................................................................195<br />
Background ...............................................................................................................197<br />
Diagram ....................................................................................................................197<br />
Wall and Floor ...........................................................................................................198<br />
Axes ..........................................................................................................................199<br />
Properties of Axes .....................................................................................................200<br />
Grids .........................................................................................................................203<br />
Axes Title ..................................................................................................................204<br />
3D Charts ..................................................................................................................206<br />
Stacked Charts .........................................................................................................207<br />
Line Charts ................................................................................................................208<br />
Area Charts ...............................................................................................................208<br />
Bar Charts .................................................................................................................209
Pie Charts .................................................................................................................209<br />
10 Databases...............................................................................211<br />
Queries .....................................................................................................................214<br />
Iteration of Tables ......................................................................................................217<br />
Type-Specific Methods for Retrieving Values ............................................................218<br />
The ResultSet Variants .............................................................................................219<br />
Methods for Navigation in ResultSets .......................................................................220<br />
Modifying Data Records ............................................................................................221<br />
11 Dialogs....................................................................................223<br />
Creating Dialogs .......................................................................................................223<br />
Closing Dialogs .........................................................................................................226<br />
Access to Individual Control Elements ......................................................................227<br />
Working With the Model of Dialogs and Control Elements ........................................227<br />
Name and Title ..........................................................................................................228<br />
Position and Size ......................................................................................................228<br />
Focus and Tabulator Sequence ................................................................................229<br />
Multi-Page Dialogs ....................................................................................................230<br />
Parameters ...............................................................................................................236<br />
Mouse Events ...........................................................................................................237<br />
Keyboard Events .......................................................................................................239<br />
Focus Events ............................................................................................................240<br />
Control Element-Specific Events ...............................................................................241<br />
Buttons ......................................................................................................................242<br />
Option Buttons ..........................................................................................................243<br />
Checkboxes ..............................................................................................................244<br />
Text Fields .................................................................................................................245<br />
List Boxes .................................................................................................................248<br />
12 Forms......................................................................................251<br />
Determining Object Forms ........................................................................................252<br />
The Three Aspects of a Control Element Form .........................................................253<br />
Accessing the Model of Control Element Forms .......................................................253<br />
Accessing the View of Control Element Forms .........................................................254<br />
Accessing the Shape Object of Control Element Forms ...........................................255<br />
Buttons ......................................................................................................................256<br />
Option Buttons ..........................................................................................................258
Checkboxes ..............................................................................................................260<br />
Text Fields .................................................................................................................261<br />
List Boxes .................................................................................................................263<br />
Tables ........................................................................................................................266
Preface<br />
<strong>OpenOffice</strong>.<strong>org</strong> Administration <strong>Guide</strong> describes how to administer an <strong>OpenOffice</strong>.<strong>org</strong><br />
network installation. This guide is intended for system administrators who are<br />
responsible for the installation and setup of <strong>OpenOffice</strong>.<strong>org</strong> on a server.<br />
Note – Throughout this document, the <strong>OpenOffice</strong>.<strong>org</strong> installation directory is<br />
represented in syntax as install-dir.<br />
9
1<br />
C H A P T E R 1<br />
1 <strong>OpenOffice</strong>.<strong>org</strong> <strong>BASIC</strong> Programming<br />
<strong>Guide</strong><br />
This guide provides an introduction to programming with <strong>OpenOffice</strong>.<strong>org</strong> Basic. To<br />
get the most out of this book, you should be familiar with other programming<br />
languages. Extensive examples are provided to help you quickly develop your own<br />
<strong>OpenOffice</strong>.<strong>org</strong> Basic programs.<br />
This guide divides information about <strong>OpenOffice</strong>.<strong>org</strong> administration into several<br />
chapters. The first three chapters introduce you to <strong>OpenOffice</strong>.<strong>org</strong> Basic:<br />
The Language of <strong>OpenOffice</strong>.<strong>org</strong> Basic<br />
Runtime Library<br />
Introduction to the API<br />
These chapters provide an overview of <strong>OpenOffice</strong>.<strong>org</strong> Basic and should be read by<br />
anyone who intends to write <strong>OpenOffice</strong>.<strong>org</strong> Basic programs. The remaining chapters<br />
describe the individual components of the <strong>OpenOffice</strong>.<strong>org</strong> API in more detail and can<br />
be read selectively as required:<br />
Working with Documents<br />
Text Documents<br />
Spreadsheet Documents<br />
Drawings and Presentations<br />
Charts (Diagrams)<br />
Databases<br />
Dialogs<br />
Forms<br />
11
<strong>OpenOffice</strong>.<strong>org</strong> <strong>BASIC</strong> Programming <strong>Guide</strong><br />
About <strong>OpenOffice</strong>.<strong>org</strong> Basic<br />
The <strong>OpenOffice</strong>.<strong>org</strong> Basic programming language has been developed especially for<br />
<strong>OpenOffice</strong>.<strong>org</strong> and is firmly integrated in the Office package.<br />
As the name suggests, <strong>OpenOffice</strong>.<strong>org</strong> Basic is a programming language from the<br />
Basic family. Anyone who has previously worked with other Basic languages — in<br />
particular with Visual Basic or Visual Basic for Applications (VBA) from Microsoft —<br />
will quickly become accustomed to <strong>OpenOffice</strong>.<strong>org</strong> Basic. Large sections of the basic<br />
constructs of <strong>OpenOffice</strong>.<strong>org</strong> Basic are compatible with Visual Basic.<br />
The <strong>OpenOffice</strong>.<strong>org</strong> Basic programming language can be divided into four<br />
components:<br />
The language of <strong>OpenOffice</strong>.<strong>org</strong> Basic: Defines the elementary linguistic<br />
constructs, for example, for variable declarations, loops, and functions.<br />
The runtime library: Provides standard functions which have no direct reference to<br />
<strong>OpenOffice</strong>.<strong>org</strong>, for example, functions for editing numbers, strings, date values,<br />
and files.<br />
The <strong>OpenOffice</strong>.<strong>org</strong> API (Application Programming Interface): Permits access to<br />
<strong>OpenOffice</strong>.<strong>org</strong> documents and allows these to be created, saved, modified, and<br />
printed.<br />
The Dialog Editor: Creates personal dialog windows and provides scope for the<br />
adding of control elements and event handlers.<br />
Note – Compatibility between <strong>OpenOffice</strong>.<strong>org</strong> Basic and VBA relates to the<br />
<strong>OpenOffice</strong>.<strong>org</strong> Basic language as well as the runtime library. The <strong>OpenOffice</strong>.<strong>org</strong><br />
API and the Dialog Editor are not compatible with VBA (standardizing these<br />
interfaces would have made many of the concepts provided in <strong>OpenOffice</strong>.<strong>org</strong><br />
impossible).<br />
Intended Users of <strong>OpenOffice</strong>.<strong>org</strong> Basic<br />
The scope of application for <strong>OpenOffice</strong>.<strong>org</strong> Basic begins where the standard<br />
functions of <strong>OpenOffice</strong>.<strong>org</strong> end. Routine tasks can therefore be automated in<br />
<strong>OpenOffice</strong>.<strong>org</strong> Basic, links can be made to other programs — for example to a<br />
database server — and complex activities can be performed at the press of a button<br />
by using predefined scripts.<br />
<strong>OpenOffice</strong>.<strong>org</strong> Basic offers complete access to all <strong>OpenOffice</strong>.<strong>org</strong> functions,<br />
12 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
<strong>OpenOffice</strong>.<strong>org</strong> <strong>BASIC</strong> Programming <strong>Guide</strong><br />
supports all functions, modifies document types, and provides options for creating<br />
personal dialog windows.<br />
Use of <strong>OpenOffice</strong>.<strong>org</strong> Basic<br />
<strong>OpenOffice</strong>.<strong>org</strong> Basic can be used by any <strong>OpenOffice</strong>.<strong>org</strong> user without any additional<br />
programs or aids. Even in the standard installation, <strong>OpenOffice</strong>.<strong>org</strong> Basic has all the<br />
components needed to create its own Basic macros, including:<br />
The integrated development environment (IDE) which provides an editor for<br />
creating and testing macros.<br />
The interpreter, which is needed to run <strong>OpenOffice</strong>.<strong>org</strong> Basic macros.<br />
The interfaces to various <strong>OpenOffice</strong>.<strong>org</strong> applications, which allow for direct<br />
access to Office documents.<br />
More Information<br />
The components of the <strong>OpenOffice</strong>.<strong>org</strong> API that are discussed in this guide were<br />
selected based on their practical benefits for the <strong>OpenOffice</strong>.<strong>org</strong> Basic programmer.<br />
In general, only parts of the interfaces are discussed. For a more detailed picture, see<br />
the API reference.<br />
The Developer's <strong>Guide</strong> describes the <strong>OpenOffice</strong>.<strong>org</strong> API in more detail than this<br />
guide, but is primarily intended for Java and C++ programmers. Anyone who is<br />
already familiar with <strong>OpenOffice</strong>.<strong>org</strong> Basic programming can find additional<br />
information in the Developer's <strong>Guide</strong> on <strong>OpenOffice</strong>.<strong>org</strong> Basic and <strong>OpenOffice</strong>.<strong>org</strong><br />
programming.<br />
Programmers who want to work directly with Java or C++ rather than <strong>OpenOffice</strong>.<strong>org</strong><br />
Basic should consult the <strong>OpenOffice</strong>.<strong>org</strong> Developer's <strong>Guide</strong> instead of this guide.<br />
<strong>OpenOffice</strong>.<strong>org</strong> programming with Java or C++ is a considerably more complex<br />
process than programming with <strong>OpenOffice</strong>.<strong>org</strong> Basic.<br />
Chapter 1 · <strong>OpenOffice</strong>.<strong>org</strong> <strong>BASIC</strong> Programming <strong>Guide</strong> 13
2<br />
C H A P T E R 2<br />
2 The Language of <strong>OpenOffice</strong>.<strong>org</strong><br />
<strong>BASIC</strong><br />
<strong>OpenOffice</strong>.<strong>org</strong> Basic belongs to the family of Basic languages. Many parts of<br />
<strong>OpenOffice</strong>.<strong>org</strong> Basic are identical to Microsoft Visual Basic for Applications and<br />
Microsoft Visual Basic. Anyone who has already worked with these languages can<br />
quickly become accustomed to <strong>OpenOffice</strong>.<strong>org</strong> Basic.<br />
Programmers of other languages – such as Java, C++, or Delphi – should also find it<br />
easy to familiarize themselves with <strong>OpenOffice</strong>.<strong>org</strong> Basic. <strong>OpenOffice</strong>.<strong>org</strong> Basic is a<br />
fully-developed procedural programming language and no longer uses rudimentary<br />
control structures, such as GoTo and GoSub.<br />
You can also benefit from the advantages of object-oriented programming since an<br />
interface in <strong>OpenOffice</strong>.<strong>org</strong> Basic enables you to use external object libraries. The<br />
entire <strong>OpenOffice</strong>.<strong>org</strong> API is based on these interfaces, which are described in more<br />
detail in the following chapters of this document.<br />
This chapter provides an overview of the key elements and constructs of the<br />
<strong>OpenOffice</strong>.<strong>org</strong> Basic language, as well as the framework in which applications and<br />
libraries are oriented to <strong>OpenOffice</strong>.<strong>org</strong> Basic.<br />
15
The Language of <strong>OpenOffice</strong>.<strong>org</strong> <strong>BASIC</strong><br />
Overview of a Basic Program<br />
<strong>OpenOffice</strong>.<strong>org</strong> Basic is an interpreter language. Unlike C++ or Delphi, the<br />
<strong>OpenOffice</strong>.<strong>org</strong> Basic compiler does not create executable or self-extracting files that<br />
are capable of running automatically. Instead, you execute an <strong>OpenOffice</strong>.<strong>org</strong> Basic<br />
program inside <strong>OpenOffice</strong>.<strong>org</strong>. The code is first checked for obvious errors and then<br />
executed line by line.<br />
Program Lines<br />
The Basic interpreter's line-oriented execution produces one of the key differences<br />
between Basic and other programming languages. Whereas the position of hard line<br />
breaks in the source code of Java, C++, or Delphi programs is irrelevant, each line in<br />
a Basic program forms a self-contained unit. Function calls, mathematical<br />
expressions, and other linguistic elements, such as function and loop headers, must<br />
be completed on the same line that they begin on.<br />
If there is not enough space, or if this results in long lines, then several lines can be<br />
linked together by adding underscores _. The following example shows how four lines<br />
of a mathematical expression can be linked:<br />
LongExpression = (Expression1 * Expression2) + _<br />
(Expression3 * Expression4) + _<br />
(Expression5 * Expression6) + _<br />
(Expression7 * Expression8)<br />
Note – The underscore must always be the last character in a linked line and cannot<br />
be followed by a space or a tab, otherwise the code generates an error.<br />
In addition to linking individual lines, <strong>OpenOffice</strong>.<strong>org</strong> Basic, you can use colons to<br />
divide one line into several sections so that there is enough space for several<br />
expressions. The assignments<br />
a = 1<br />
a = a + 1<br />
a = a + 1<br />
can be written as follows:<br />
a = 1 : a = a + 1 : a = a + 1<br />
16 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Comments<br />
Comments<br />
In addition to the program code to be executed, an <strong>OpenOffice</strong>.<strong>org</strong> Basic program<br />
can also contain comments that explain the individual parts of the program and<br />
provide important information that can be helpful at a later point.<br />
<strong>OpenOffice</strong>.<strong>org</strong> Basic provides two methods for inserting comments in the program<br />
code:<br />
All characters that follow an apostrophe are treated as comments:<br />
Dim A ' This is a comment for variable A<br />
The keyword Rem, followed by the comment:<br />
Rem This comment is introduced by the keyword Rem.<br />
A comment usually includes all characters up to the end of the line. <strong>OpenOffice</strong>.<strong>org</strong><br />
Basic then interprets the following line as a regular instruction again. If comments<br />
cover several lines, each line must be identified as a comment:<br />
Dim B ' This comment for variable B is relatively long<br />
' and stretches over several lines. The<br />
' comment character must therefore be repeated<br />
' in each line.<br />
Markers<br />
A <strong>OpenOffice</strong>.<strong>org</strong> Basic program can contain dozens, hundreds, or even thousands<br />
of markers, which are names for variables, constants, functions, and so on. When<br />
you select a name for a marker, the following rules apply:<br />
Markers can only contain Latin letters, numbers, and underscores (_).<br />
The first character of a marker must be a letter or an underscore.<br />
Markers cannot contain special characters, such as ä â î ß.<br />
The maximum length of a marker is 255 characters.<br />
No distinction is made between uppercase and lowercase characters. The<br />
OneTestVariable marker, for example, defines the same variable as<br />
onetestVariable and ONETESTVARIABLE.<br />
There is, however, one exception to this rule: a distinction is made between<br />
uppercase and lowercase characters for UNO-API constants. More information<br />
about UNO is presented in Introduction to the <strong>OpenOffice</strong>.<strong>org</strong> API.<br />
Chapter 2 · The Language of <strong>OpenOffice</strong>.<strong>org</strong> <strong>BASIC</strong> 17
Markers<br />
Note – The rules for constructing markers are different in <strong>OpenOffice</strong>.<strong>org</strong> Basic than<br />
in VBA. For example, <strong>OpenOffice</strong>.<strong>org</strong> Basic only allows special characters in markers<br />
when using Option Compatible, since they can cause problems in international<br />
projects.<br />
Here are a few examples of correct and incorrect markers:<br />
Surname ' Correct<br />
Surname5 ' Correct (number 5 is not the first digit)<br />
First Name ' Incorrect (spaces are not permitted)<br />
DéjàVu ' Incorrect (letters such as é, à are not permitted)<br />
5Surnames ' Incorrect (the first character must not be a number)<br />
First,Name ' Incorrect (commas and full stops are not permitted)<br />
Enclosing a variable name in square brackets allows names that might otherwise be<br />
disallowed; for example, spaces.<br />
Dim [First Name] As String 'Space accepted in square brackets<br />
Dim [DéjàVu] As Integer 'Special characters in square brackets<br />
[First Name] = "Andrew"<br />
[DéjàVu] = 2<br />
Working With Variables<br />
Implicit Variable Declaration<br />
Basic languages are designed to be easy to use. As a result, <strong>OpenOffice</strong>.<strong>org</strong> Basic<br />
enables the creation of a variable through simple usage and without an explicit<br />
declaration. In other words, a variable exists from the moment that you include it in<br />
your code. Depending on the variables that are already present, the following<br />
example declares up to three new variables:<br />
a = b + c<br />
Declaring variables implicitly is not good programming practice because it can result<br />
in the inadvertent introduction of a new variable through, for example, a typing error.<br />
Instead of producing an error message, the interpreter initializes the typing error as a<br />
new variable with a value of 0. It can be very difficult to locate errors of this kind in<br />
your code.<br />
18 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Explicit Variable Declaration<br />
Explicit Variable Declaration<br />
To prevent errors caused by an implicit declaration of variables, <strong>OpenOffice</strong>.<strong>org</strong> Basic<br />
provides a switch called:<br />
Option Explicit<br />
This must be listed in the first program line of each module and ensures that an error<br />
message is issued if one of the variables used is not declared. The Option Explicit<br />
switch should be included in all Basic modules.<br />
In its simplest form, the command for an explicit declaration of a variable is as<br />
follows:<br />
Dim MyVar<br />
This example declares a variable with the name MyVar and the type variant. A<br />
variant is a universal variable that can record all conceivable values, including strings,<br />
whole numbers, floating point figures, and Boolean values. Here are a few examples<br />
of Variant variables:<br />
MyVar = "Hello World" ' Assignment of a string<br />
MyVar = 1 ' Assignment of a whole number<br />
MyVar = 1.0 ' Assignment of a floating point number<br />
MyVar = True ' Assignment of a Boolean value<br />
The variables declared in the previous example can even be used for different<br />
variable types in the same program. Although this provides considerable flexibility, it<br />
is best to restrict a variable to one variable type. When <strong>OpenOffice</strong>.<strong>org</strong> Basic<br />
encounters an incorrectly defined variable type in a particular context, an error<br />
message is generated.<br />
Use the following style when you make a type-bound variable declaration:<br />
Dim MyVar As Integer ' Declaration of a variable of the integer type<br />
The variable is declared as an integer type and can record whole number values. You<br />
can also use the following style to declare an integer type variable:<br />
Dim MyVar% ' Declaration of a variable of the integer type<br />
The Dim instruction can record several variable declarations:<br />
Dim MyVar1, MyVar2<br />
If you want to assign the variables to a permanent type, you must make separate<br />
assignments for each variable:<br />
Dim MyVar1 As Integer, MyVar2 As Integer<br />
If you do not declare the type for a variable, <strong>OpenOffice</strong>.<strong>org</strong> Basic assigns the<br />
variable a variant type. For example, in the following variable declaration, MyVar1<br />
Chapter 2 · The Language of <strong>OpenOffice</strong>.<strong>org</strong> <strong>BASIC</strong> 19
Explicit Variable Declaration<br />
Strings<br />
becomes a variant and MyVar2 becomes an integer:<br />
Dim MyVar1, MyVar2 As Integer<br />
The following sections list the variable types that are available in <strong>OpenOffice</strong>.<strong>org</strong><br />
Basic and describe how they can be used and declared.<br />
Strings, together with numbers, form the most important basic types of<br />
<strong>OpenOffice</strong>.<strong>org</strong> Basic. A string consists of a sequence of consecutive individual<br />
characters. The computer saves the strings internally as a sequence of numbers<br />
where each number represents one specific character.<br />
From a Set of ASCII Characters to<br />
Unicode<br />
Character sets match characters in a string with a corresponding code (numbers and<br />
characters) in a table that describes how the computer is to display the string.<br />
The ASCII Character Set<br />
The ASCII character set is a set of codes that represent numbers, characters, and<br />
special symbols by one byte. The 0 to 127 ASCII codes correspond to the alphabet<br />
and to common symbols (such as periods, parentheses, and commas), as well as<br />
some special screen and printer control codes. The ASCII character set is commonly<br />
used as a standard format for transferring text data between computers.<br />
However, this character set does not include a range of special characters used in<br />
Europe, such as â, ä, and î, as well as other character formats, such as the Cyrillic<br />
alphabet.<br />
20 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
The ANSI Character Set<br />
From a Set of ASCII Characters to Unicode<br />
Microsoft based its Windows product on the American National Standards Institute<br />
(ANSI) character set, which was gradually extended to include characters that are<br />
missing from the ASCII character set.<br />
Code Pages<br />
The ISO 8859 character sets provide an international standard. The first 128<br />
characters of the ISO character set correspond to the ASCII character set. The ISO<br />
standard introduces new character sets (code pages) so that more languages can<br />
be correctly displayed. However, as a result, the same character value can represent<br />
different characters in different languages.<br />
Unicode<br />
Unicode increases the length of a character to four bytes and combines different<br />
character sets to create a standard to depict as many of the world's languages as<br />
possible. Version 2.0 of Unicode is now supported by many programs — including<br />
<strong>OpenOffice</strong>.<strong>org</strong> and <strong>OpenOffice</strong>.<strong>org</strong> Basic.<br />
String Variables<br />
<strong>OpenOffice</strong>.<strong>org</strong> Basic saves strings as string variables in Unicode. A string variable<br />
can store up to 65535 characters. Internally, <strong>OpenOffice</strong>.<strong>org</strong> Basic saves the<br />
associated Unicode value for every character. The working memory needed for a<br />
string variable depends on the length of the string.<br />
Example declaration of a string variable:<br />
Dim Variable As String<br />
You can also write this declaration as:<br />
Dim Variable$<br />
Note – When porting VBA applications, ensure that the maximum allowed string<br />
length in <strong>OpenOffice</strong>.<strong>org</strong> Basic is observed (65535 characters).<br />
Chapter 2 · The Language of <strong>OpenOffice</strong>.<strong>org</strong> <strong>BASIC</strong> 21
Specification of Explicit Strings<br />
Numbers<br />
Specification of Explicit Strings<br />
To assign an explicit string to a string variable, enclose the string in quotation marks<br />
(").<br />
Dim MyString As String<br />
MyString = " This is a test"<br />
To split a string across two lines, add an ampersand sign at the end of the first line:<br />
Dim MyString As String<br />
MyString = "This string is so long that it " & _<br />
"has been split over two lines."<br />
To include a quotation mark (") in a string, enter it twice at the relevant point:<br />
Dim MyString As String<br />
MyString = "a ""-quotation mark." ' produces a "-quotation mark<br />
<strong>OpenOffice</strong>.<strong>org</strong> Basic supports five basic types for processing numbers:<br />
Integer<br />
Long Integer<br />
Single<br />
Double<br />
Currency<br />
Integer Variables<br />
Integer variables can store any whole number between -32768 and 32767. An integer<br />
variable can take up to two bytes of memory. The type declaration symbol for an<br />
integer variable is %. Calculations that use integer variables are very fast and are<br />
particularly useful for loop counters. If you assign a floating point number to an<br />
integer variable, the number is rounded up or down to the next whole number.<br />
Example declarations for integer variables:<br />
Dim Variable As Integer<br />
Dim Variable%<br />
22 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Long Integer Variables<br />
Long Integer Variables<br />
Long integer variables can store any whole number between –2147483648 and<br />
2147483647. A long integer variable can takes up to four bytes of memory. The type<br />
declaration symbol for a long integer is &. Calculations with long integer variables are<br />
very fast and are particularly useful for loop counters. If you assign a floating point<br />
number to a long integer variable, the number is rounded up or down to the next<br />
whole number.<br />
Example declarations for long integer variables:<br />
Dim Variable as Long<br />
Dim Variable&<br />
Single Variables<br />
Single variables can store any positive or negative floating point number between<br />
3.402823 x 10 38 and 1.401298 x 10 -45 . A single variable can take up to four bytes of<br />
memory. The type declaration symbol for a single variable is !.<br />
Originally, single variables were used to reduce the computing time required for the<br />
more precise double variables. However, these speed considerations no longer apply,<br />
reducing the need for single variables.<br />
Example declarations for single variables:<br />
Dim Variable as Single<br />
Dim Variable!<br />
Double Variables<br />
Double variables can store any positive or negative floating point numbers between<br />
1.79769313486232 x 10 308 and 4.94065645841247 x 10 -324 . A double variable can<br />
take up to eight bytes of memory. Double variables are suitable for precise<br />
calculations. The type declaration symbol is #.<br />
Example declarations of double variables:<br />
Dim Variable As Double<br />
Dim Variable#<br />
Chapter 2 · The Language of <strong>OpenOffice</strong>.<strong>org</strong> <strong>BASIC</strong> 23
Currency Variables<br />
Currency Variables<br />
Currency variables differ from the other variable types by the way they handle values.<br />
The decimal point is fixed and is followed by four decimal places. The variable can<br />
contain up to 15 numbers before the decimal point. A currency variable can store any<br />
value between -922337203685477.5808 and +922337203685477.5807 and takes up<br />
to eight bytes of memory. The type declaration symbol for a currency variable is @.<br />
Currency variables are mostly intended for business calculations that yield<br />
unforeseeable rounding errors due to the use of floating point numbers.<br />
Example declarations of currency variables:<br />
Dim Variable As Currency<br />
Dim Variable@<br />
Floats<br />
The types single, double and currency are often collectively referred to as floats, or<br />
floating-point number types. They can contain numerical values with decimal fractions<br />
of various length, hence the name: The decimal point seems to be able to 'float'<br />
through the number.<br />
You can declare variables of the type float. The actual variable type (single, long,<br />
currency) is determined the moment a value is assigned to the variable:<br />
Dim A As Float<br />
A = 1210.126<br />
Specification of Explicit Numbers<br />
Numbers can be presented in several ways, for example, in decimal format or in<br />
scientific notation, or even with a different base than the decimal system. The<br />
following rules apply to numerical characters in <strong>OpenOffice</strong>.<strong>org</strong> Basic:<br />
24 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Whole Numbers<br />
Specification of Explicit Numbers<br />
The simplest method is to work with whole numbers. They are listed in the source<br />
text without a comma separating the thousand figure:<br />
Dim A As Integer<br />
Dim B As Float<br />
A = 1210<br />
B = 2438<br />
The numbers can be preceded by both a plus (+) or minus (-) sign (with or without a<br />
space in between):<br />
Dim A As Integer<br />
Dim B As Float<br />
A = + 121<br />
B = - 243<br />
Decimal Numbers<br />
When you type a decimal number, use a period (.) as the decimal point. This rule<br />
ensures that source texts can be transferred from one country to another without<br />
conversion.<br />
Dim A As Integer<br />
Dim B As Integer<br />
Dim C As Float<br />
A = 1223.53 ' is rounded<br />
B = - 23446.46 ' is rounded<br />
C = + 3532.76323<br />
You can also use plus (+) or minus (-) signs as prefixes for decimal numbers (again<br />
with or without spaces).<br />
If a decimal number is assigned to an integer variable, <strong>OpenOffice</strong>.<strong>org</strong> Basic rounds<br />
the figure up or down.<br />
Exponential Writing Style<br />
<strong>OpenOffice</strong>.<strong>org</strong> Basic allows numbers to be specified in the exponential writing style,<br />
for example, you can write 1.5e-10 for the number 1.5 x 10 -10 (0.00000000015). The<br />
letter "e" can be lowercase or uppercase with or without a plus sign (+) as a prefix.<br />
Here are a few correct and incorrect examples of numbers in exponential format:<br />
Chapter 2 · The Language of <strong>OpenOffice</strong>.<strong>org</strong> <strong>BASIC</strong> 25
Specification of Explicit Numbers<br />
Dim A As Double<br />
A = 1.43E2 ' Correct<br />
A = + 1.43E2 ' Correct (space between plus and basic number)<br />
A = - 1.43E2 ' Correct (space between minus and basic number)<br />
A = 1.43E-2 ' Correct (negative exponent)<br />
A = 1.43E -2 ' Incorrect (spaces not permitted within the number)<br />
A = 1,43E-2 ' Incorrect (commas not permitted as decimal points)<br />
A = 1.43E2.2 ' Incorrect (exponent must be a whole number)<br />
Note, that in the first and third incorrect examples that no error message is generated<br />
even though the variables return incorrect values. The expression<br />
A = 1.43E -2<br />
is interpreted as 1.43 minus 2, which corresponds to the value -0.57. However, the<br />
value 1.43 x 10 -2 (corresponding to 0.0143) was the intended value. With the value<br />
A = 1.43E2.2<br />
<strong>OpenOffice</strong>.<strong>org</strong> Basic ignores the part of the exponent after the decimal point and<br />
interprets the expression as<br />
A = 1.43E2<br />
Hexadecimal Values<br />
In the hexadecimal system (base 16 system), a 2-digit number corresponds to<br />
precisely one byte. This allows numbers to be handled in a manner which more<br />
closely reflects machine architecture. In the hexadecimal system, the numbers 0 to 9<br />
and the letters A to F are used as numbers. An A stands for the decimal number 10,<br />
while the letter F represents the decimal number 15. <strong>OpenOffice</strong>.<strong>org</strong> Basic lets you<br />
use whole numbered hexadecimal values, so long as they are preceded by &H.<br />
Dim A As Long<br />
A = &HFF ' Hexadecimal value FF, corresponds to the decimal value 255<br />
A = &H10 ' Hexadecimal value 10, corresponds to the decimal value 16<br />
Octal Values<br />
<strong>OpenOffice</strong>.<strong>org</strong> Basic also understands the octal system (base 8 system), which uses<br />
the numbers 0 to 7. You must use whole numbers that are preceded by &O.<br />
Dim A As Long<br />
A = &O77 ' Octal value 77, corresponds to the decimal value 63<br />
A = &O10 ' Octal value 10, corresponds to the decimal value 8<br />
26 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Boolean Values<br />
Specification of Explicit Numbers<br />
Boolean variables can only contain one of two values: True or False. They are<br />
suitable for binary specifications that can only adopt one of two statuses. A Boolean<br />
value is saved internally as a two-byte integer value, where 0 corresponds to the<br />
False and any other value to True. There is no type declaration symbol for Boolean<br />
variables. The declaration can only be made using the supplement As Boolean.<br />
Example declaration of a Boolean variable:<br />
Dim Variable As Boolean<br />
Date and Time<br />
Arrays<br />
Date variables can contain date and time values. When saving date values,<br />
<strong>OpenOffice</strong>.<strong>org</strong> Basic uses an internal format that permits comparisons and<br />
mathematical operations on date and time values. There is no type declaration<br />
symbol for date variables. The declaration can only be made using the supplement As<br />
Date.<br />
Example declaration of a date variable:<br />
Dim Variable As Date<br />
In addition to simple variables (scalars), <strong>OpenOffice</strong>.<strong>org</strong> Basic also supports arrays<br />
(data fields). A data field contains several variables, which are addressed through an<br />
index.<br />
Defining Arrays<br />
Arrays can be defined as follows:<br />
Chapter 2 · The Language of <strong>OpenOffice</strong>.<strong>org</strong> <strong>BASIC</strong> 27
Defining Arrays<br />
Simple Arrays<br />
An array declaration is similar to that of a simple variable declaration. However, unlike<br />
the variable declaration, the array name is followed by parentheses which contain the<br />
specifications for the number of elements. The expression<br />
Dim MyArray(3)<br />
declares an array that has four variables of the variant data type, namely MyArray(0),<br />
MyArray(1), MyArray(2), and MyArray(3).<br />
You can also declare type-specific variables in an array. For example, the following<br />
line declares an array with four integer variables:<br />
Dim MyInteger(3) As Integer<br />
In the previous examples, the index for the array always begins with the standard<br />
start value of zero. As an alternative, a validity range with start and end values can be<br />
specified for the data field declaration. The following example declares a data field<br />
that has six integer values and which can be addressed using the indexes 5 to 10:<br />
Dim MyInteger(5 To 10) As Integer<br />
The indexes do not need to be positive values. The following example also shows a<br />
correct declaration, but with negative data field limits:<br />
Dim MyInteger(-10 To -5) As Integer<br />
It declares an integer data field with 6 values that can be addressed using the<br />
indexes -10 to -5.<br />
There are three limits that you must observe when you define data field indexes:<br />
The smallest possible index is -32768.<br />
The largest possible index is 32767.<br />
The maximum number of elements (within a data field dimension) is 16368.<br />
Note – Other limit values sometimes apply for data field indexes in VBA. The same<br />
also applies to the maximum number of elements possible per dimension. The values<br />
valid there can be found in the relevant VBA documentation.<br />
Specified Value for Start Index<br />
The start index of a data field usually begins with the value 0. Alternatively, you can<br />
change the start index for all data field declarations to the value 1 by using the call:<br />
Option Base 1<br />
28 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Defining Arrays<br />
The call must be included in the header of a module if you want it to apply to all array<br />
declarations in the module. However, this call does not affect the UNO sequences<br />
that are defined through the <strong>OpenOffice</strong>.<strong>org</strong> API whose index always begins with 0.<br />
To improve clarity, you should avoid using Option Base 1.<br />
The number of elements in an array is not affected if you use Option Base 1, only the<br />
start index changes. The declaration<br />
Option Base 1<br />
' ...<br />
Dim MyInteger(3)<br />
creates 4 integer variables which can be described with the expressions<br />
MyInteger(1), MyInteger(2), MyInteger(3), and MyInteger(4).<br />
Note – In <strong>OpenOffice</strong>.<strong>org</strong> Basic, the expression Option Base 1 does not affect the<br />
number of elements in an array as it does in VBA. It is, rather, the start index which<br />
moves in <strong>OpenOffice</strong>.<strong>org</strong> Basic. While the declaration MyInteger(3) creates three<br />
integer values in VBA with the indexes 1 to 3, the same declaration in <strong>OpenOffice</strong>.<strong>org</strong><br />
Basic creates four integer values with the indexes 1 to 4. By using Option<br />
Compatible, <strong>OpenOffice</strong>.<strong>org</strong> Basic behaves like VBA.<br />
Multi-Dimensional Data Fields<br />
In addition to single dimensional data fields, <strong>OpenOffice</strong>.<strong>org</strong> Basic also supports work<br />
with multi-dimensional data fields. The corresponding dimensions are separated from<br />
one another by commas. The example<br />
Dim MyIntArray(5, 5) As Integer<br />
defines an integer array with two dimensions, each with 6 indexes (can be addressed<br />
through the indexes 0 to 5). The entire array can record a total of 6 x 6 = 36 integer<br />
values.<br />
You can define hundreds of dimensions in <strong>OpenOffice</strong>.<strong>org</strong> Basic Arrays; however, the<br />
amount of available memory limits the number of dimensions you can have.<br />
Dynamic Changes in the Dimensions of Data Fields<br />
The previous examples are based on data fields of a specified dimension. You can<br />
also define arrays in which the dimension of the data fields dynamically changes. For<br />
example, you can define an array to contain all of the words in a text that begin with<br />
the letter A. As the number of these words is initially unknown, you need to be able to<br />
Chapter 2 · The Language of <strong>OpenOffice</strong>.<strong>org</strong> <strong>BASIC</strong> 29
Defining Arrays<br />
subsequently change the field limits. To do this in <strong>OpenOffice</strong>.<strong>org</strong> Basic, use the<br />
following call:<br />
ReDim MyArray(10)<br />
Note – Unlike VBA, where you can only dimension dynamic arrays by using Dim<br />
MyArray(), <strong>OpenOffice</strong>.<strong>org</strong> Basic lets you change both static and dynamic arrays<br />
using ReDim.<br />
The following example changes the dimension of the initial array so that it can record<br />
11 or 21 values:<br />
Dim MyArray(4) As Integer ' Declaration with five elements<br />
' ...<br />
ReDim MyArray(10) As Integer ' Increase to 11 elements<br />
' ...<br />
ReDim MyArray(20) As Integer ' Increase to 21 elements<br />
When you reset the dimensions of an array, you can use any of the options outlined<br />
in the previous sections. This includes declaring multi-dimensional data fields and<br />
specifying explicit start and end values. When the dimensions of the data field are<br />
changed, all contents are lost. If you want to keep the original values, use the<br />
Preserve command:<br />
Dim MyArray(10) As Integer ' Defining the initial<br />
' dimensions<br />
' ...<br />
ReDim Preserve MyArray(20) As Integer ' Increase in<br />
' data field, while<br />
' retaining content<br />
When you use Preserve, ensure that the number of dimensions and the type of<br />
variables remain the same.<br />
Note – Unlike VBA, where only the upper limit of the last dimension of a data field<br />
can be changed through Preserve, <strong>OpenOffice</strong>.<strong>org</strong> Basic lets you change other<br />
dimensions as well.<br />
If you use ReDim with Preserve, you must use the same data type as specified in the<br />
original data field declaration.<br />
Defining values for arrays<br />
Values for the Array fields can be stored like this:<br />
MyArray(0) = "somevalue"<br />
30 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Accessing Arrays<br />
Accessing values in an array works like this:<br />
MsgBox("Value:" & MyArray(0))<br />
Accessing Arrays<br />
Array Creation, value assignment and<br />
access example<br />
And example containing all steps that show real array usage:<br />
Sub TestArrayAxess<br />
End Sub<br />
Dim MyArray(3)<br />
MyArray(0) = "lala"<br />
MsgBox("Value:" & MyArray(0))<br />
Scope and Life Span of Variables<br />
A variable in <strong>OpenOffice</strong>.<strong>org</strong> Basic has a limited life span and a limited scope from<br />
which it can be read and used in other program fragments. The amount of time that a<br />
variable is retained, as well as where it can be accessed from, depends on its<br />
specified location and type.<br />
Local Variables<br />
Variables that are declared in a function or a procedure are called local variables:<br />
Sub Test<br />
Dim MyInteger As Integer<br />
' ...<br />
End Sub<br />
Local variables only remain valid as long as the function or the procedure is<br />
executing, and then are reset to zero. Each time the function is called, the values<br />
generated previously are not available.<br />
Chapter 2 · The Language of <strong>OpenOffice</strong>.<strong>org</strong> <strong>BASIC</strong> 31
Local Variables<br />
To keep the previous values, you must define the variable as Static:<br />
Sub Test<br />
Static MyInteger As Integer<br />
' ...<br />
End Sub<br />
Note – Unlike VBA, <strong>OpenOffice</strong>.<strong>org</strong> Basic ensures that the name of a local variable<br />
is not used simultaneously as a global and a private variable in the module header.<br />
When you port a VBA application to <strong>OpenOffice</strong>.<strong>org</strong> Basic, you must change any<br />
duplicate variable names.<br />
Public Domain Variables<br />
Public domain variables are defined in the header section of a module by the<br />
keyword Dim. These variables are available to all of the modules in their library:<br />
Module A:<br />
Dim A As Integer<br />
Sub Test<br />
Flip<br />
Flop<br />
End Sub<br />
Sub Flip<br />
A = A + 1<br />
End Sub<br />
Module B:<br />
Sub Flop<br />
A = A - 1<br />
End Sub<br />
The value of variable A is not changed by the Test function, but is increased by one in<br />
the Flip function and decreased by one in the Flop function. Both of these changes<br />
to the variable are global.<br />
You can also use the keyword Public instead of Dim to declare a public domain<br />
variable:<br />
Public A As Integer<br />
A public domain variable is only available so long as the associated macro is<br />
executing and then the variable is reset.<br />
32 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Global Variables<br />
Global Variables<br />
In terms of their function, global variables are similar to public domain variables,<br />
except that their values are retained even after the associated macro has executed.<br />
Global variables are declared in the header section of a module using the keyword<br />
Global:<br />
Global A As Integer<br />
Private Variables<br />
Private variables are only available in the module in which they are defined. Use the<br />
keyword Private to define the variable:<br />
Private MyInteger As Integer<br />
If several modules contain a Private variable with the same name, <strong>OpenOffice</strong>.<strong>org</strong><br />
Basic creates a different variable for each occurrence of the name. In the following<br />
example, both module A and B have a Private variable called C. The Test function<br />
first sets the Private variable in module A and then the Private variable in module B.<br />
Module A:<br />
Private C As Integer<br />
Sub Test<br />
SetModuleA ' Sets the variable C from module A<br />
SetModuleB ' Sets the variable C from module B<br />
ShowVarA ' Shows the variable C from module A (= 10)<br />
ShowVarB ' Shows the variable C from module B (= 20)<br />
End Sub<br />
Sub SetmoduleeA<br />
C = 10<br />
End Sub<br />
Sub ShowVarA<br />
MsgBox C ' Shows the variable C from module A.<br />
End Sub<br />
Module B:<br />
Private C As Integer<br />
Sub SetModuleB<br />
C = 20<br />
End Sub<br />
Sub ShowVarB<br />
Chapter 2 · The Language of <strong>OpenOffice</strong>.<strong>org</strong> <strong>BASIC</strong> 33
Private Variables<br />
Constants<br />
MsgBox C ' Shows the variable C from module B.<br />
End Sub<br />
Constants are values which may be used but not changed by the program.<br />
Defining Constants<br />
In <strong>OpenOffice</strong>.<strong>org</strong> Basic, use the keyword Const to declare a constant.<br />
Const A = 10<br />
You can also specify the constant type in the declaration:<br />
Const B As Double = 10<br />
Scope of Constants<br />
Constants have the same scope as variables (see Scope and Life Span of Variables),<br />
but the syntax is slightly different. A Const definition in the module header is available<br />
to the code in that module. To make the definition available to other modules, add the<br />
Public keyword.<br />
Public Const one As Integer = 1<br />
Predefined Constants<br />
<strong>OpenOffice</strong>.<strong>org</strong> Basic predefines several constants. Among the most useful are:<br />
True and False, for Boolean assignment statements<br />
PI as a type Double numeric value<br />
Dim bHit as Boolean<br />
34 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Operators<br />
bHit = True<br />
Dim dArea as Double, dRadius as Double<br />
' ... (assign a value to dRadius)<br />
dArea = PI * dRadius * dRadius<br />
Predefined Constants<br />
<strong>OpenOffice</strong>.<strong>org</strong> Basic understands common mathematical, logical, and comparison<br />
operators.<br />
Mathematical Operators<br />
Mathematical operators can be applied to all numbers types, whereas the + operator<br />
can also be used to link strings.<br />
+ Addition of numbers and date values, linking of strings<br />
& Link strings<br />
- Subtraction of numbers and date values<br />
* Multiplication of numbers<br />
/ Division of numbers<br />
\ Division of numbers with a whole number result (rounded)<br />
^ Raising the power of numbers<br />
MOD modulo operation (calculation of the remainder of a division)<br />
Although you can use the + operator to link strings, the + operator can become<br />
confused when linking a number to a string. The & operator is safer when dealing<br />
with strings because it assumes that all arguments should be strings, and converts<br />
the arguments to strings if they are not strings.<br />
Logical Operators<br />
Logical operators allow you to link elements according to the rules of Boolean<br />
algebra. If the operators are applied to Boolean values, the link provides the result<br />
required directly. If used in conjunction with integer and long integer values, the<br />
linking is done at the bit level.<br />
Chapter 2 · The Language of <strong>OpenOffice</strong>.<strong>org</strong> <strong>BASIC</strong> 35
Logical Operators<br />
Branching<br />
AND And linking<br />
OR Or linking<br />
XOR Exclusive or linking<br />
NOT Negation<br />
EQV Equivalent test (both parts True or False)<br />
IMP Implication (if the first expression is true, then the second must also be<br />
true)<br />
Comparison Operators<br />
Comparison operators can be applied to all elementary variable types (numbers, date<br />
details, strings, and Boolean values).<br />
= Equality of numbers, date values and strings<br />
Inequality of numbers, date values and strings<br />
> Greater than check for numbers, date values and strings<br />
>= Greater than or equal to check for numbers, date values and strings<br />
< Less than check for numbers, date values and strings<br />
3 Then<br />
B = 2<br />
End If<br />
36 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
If...Then...Else<br />
The B = 2 assignment only occurs when value of variable A is greater than three. A<br />
variation of the If statement is the If/Else clause:<br />
If A > 3 Then<br />
B = 2<br />
Else<br />
B = 0<br />
End If<br />
In this example, the variable B is assigned the value of 2 when A is greater than 3,<br />
otherwise B is assigned the value of 0.<br />
For more complex statements, you can cascade the If statement, for example:<br />
If A = 0 Then<br />
B = 0<br />
ElseIf A < 3 Then<br />
B = 1<br />
Else<br />
B = 2<br />
End If<br />
If the value of variable A equals zero, B is assigned the value 0. If A is less than 3 (but<br />
not equal to zero), then B is assigned the value 1. In all other instances (that is, if A is<br />
greater than or equal to 3), B is assigned the value 2.<br />
Select...Case<br />
The Select...Case instruction is an alternative to the cascaded If statement and is<br />
used when you need to check a value against various conditions:<br />
Select Case DayOfWeek<br />
Case 1:<br />
NameOfWeekday = "Sunday"<br />
Case 2:<br />
NameOfWeekday = "Monday"<br />
Case 3:<br />
NameOfWeekday = "Tuesday"<br />
Case 4:<br />
NameOfWeekday = "Wednesday"<br />
Case 5:<br />
NameOfWeekday = "Thursday"<br />
Case 6:<br />
NameOfWeekday = "Friday"<br />
Case 7:<br />
NameOfWeekday = "Saturday"<br />
End Select<br />
In this example, the name of a weekday corresponds to a number, so that the<br />
DayOfWeek variable is assigned the value of 1 for Sunday, 2 for Monday value, and so<br />
Chapter 2 · The Language of <strong>OpenOffice</strong>.<strong>org</strong> <strong>BASIC</strong> 37
Select...Case<br />
Loops<br />
on.<br />
The Select command is not restricted to simple 1:1 assignments — you can also<br />
specify comparison operators or lists of expressions in a Case branch. The following<br />
example lists the most important syntax variants:<br />
Select Case Var<br />
Case 1 To 5<br />
' ... Var is between the numbers 1 and 5 (including the values 1 and 5).<br />
Case > 100<br />
' ... Var is greater than 100<br />
Case 6, 7, 8<br />
' ... Var is 6, 7 or 8<br />
Case 6, 7, 8, > 15, < 0<br />
' ... Var is 6, 7, 8, greater than 15, or less than 0<br />
Case Else<br />
' ... all other instances<br />
End Select<br />
Now consider a misleading (advanced) example, and a common error:<br />
Select Case Var<br />
Case Var = 8<br />
' ... Var is 0<br />
Case Else<br />
' ... all other instances<br />
End Select<br />
The statement (Var = 8) evaluates to TRUE if Var is 8, and FALSE otherwise. TRUE<br />
is -1 and FALSE is 0. The Select Case statement evaluates the expression, which is<br />
TRUE or FALSE, and then compares that value to Var. When Var is 0, there is a<br />
match. If you understand the last example, then you also know why this example<br />
does not do what it appears<br />
Select Case Var<br />
Case Var > 8 And Var < 11<br />
' ... Var is 0<br />
Case Else<br />
' ... all other instances<br />
End Select<br />
A loop executes a code block for the number of passes that are specified. You can<br />
also have loops with an undefined number of passes.<br />
38 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
For...Next<br />
For...Next<br />
The For...Next loop has a fixed number of passes. The loop counter defines the<br />
number of times that the loop is to be executed. In the following example, variable I<br />
is the loop counter, with an initial value of 1. The counter is incremented by 1 at the<br />
end of each pass. When variable I equals 10, the loop stops.<br />
Dim I<br />
For I = 1 To 10<br />
' ... Inner part of loop<br />
Next I<br />
If you want to increment the loop counter by a value other than 1 at the end of each<br />
pass, use the Step function:<br />
Dim I<br />
For I = 1 To 10 Step 0.5<br />
' ... Inner part of loop<br />
Next I<br />
In the preceding example, the counter is increased by 0.5 at the end of each pass<br />
and the loop is executed 19 times.<br />
You can also use negative step values:<br />
Dim I<br />
For I = 10 To 1 Step -1<br />
' ... Inner part of loop<br />
Next I<br />
In this example, the counter begins at 10 and is reduced by 1 at the end of each pass<br />
until the counter is 1.<br />
The Exit For instruction allows you to exit a For loop prematurely. In the following<br />
example, the loop is terminated during the fifth pass:<br />
Dim I<br />
For I = 1 To 10<br />
If I = 5 Then<br />
Exit For<br />
End If<br />
' ... Inner part of loop<br />
Next I<br />
For Each<br />
The For Each...Next loop variation in VBA is supported in <strong>OpenOffice</strong>.<strong>org</strong> Basic. For<br />
Each loops do not use an explicit counter like a For...Next loop does. A For Each<br />
Chapter 2 · The Language of <strong>OpenOffice</strong>.<strong>org</strong> <strong>BASIC</strong> 39
For Each<br />
loop says "do this to everything in this set", rather than "do this n times". For<br />
example:<br />
Const d1 = 2<br />
Const d2 = 3<br />
Const d3 = 2<br />
Dim i<br />
Dim a(d1, d2, d3)<br />
For Each i In a()<br />
' ... Inner part of loop<br />
Next i<br />
The loop will execute 36 times.<br />
Do...Loop<br />
The Do...Loop is not linked to a fixed number of passes. Instead, the Do...Loop is<br />
executed until a certain condition is met. There are four versions of the Do...Loop. In<br />
the first two examples, the code within the loop may not be executed at all ("do 0<br />
times" logic). In the latter examples, the code will be executed at least once. (In the<br />
following examples, A > 10 represents any condition):<br />
1 The Do While...Loop version<br />
Do While A > 10<br />
' ... loop body<br />
Loop<br />
checks whether the condition after the While is true before every pass and only then<br />
executes the loop.<br />
2 The Do Until...Loop version<br />
Do Until A > 10<br />
' ... loop body<br />
Loop<br />
executes the loop as long as the condition after the Until evaluates to false.<br />
3 The Do...Loop While version<br />
Do<br />
' ... loop body<br />
Loop While A > 10<br />
only checks the condition after the first loop pass and terminates if the condition after<br />
the While evaluates to false.<br />
40 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
4 The Do...Loop Until version<br />
Do<br />
' ... loop body<br />
Loop Until A > 10<br />
Do...Loop<br />
also checks its condition after the first pass, but terminates if the condition after the<br />
Until evaluates to true.<br />
As in the For...Next loop, the Do...Loop also provides a terminate command. The<br />
Exit Do command can exit at loop at any point within the loop.<br />
Do<br />
If A = 4 Then<br />
Exit Do<br />
End If<br />
' ... loop body<br />
Loop While A > 10<br />
While...Wend<br />
The While...Wend loop construct works exactly the same as the Do While...Loop,<br />
but with the disadvantage that there is no Exit command available. The following two<br />
loops produce identical results:<br />
Do While A > 10<br />
' ... loop body<br />
Loop<br />
While A > 10<br />
' ... loop body<br />
Wend<br />
Programming Example: Sorting With<br />
Embedded Loops<br />
There are many ways to use loops, for example, to search lists, return values, or<br />
execute complex mathematical tasks. The following example is an algorithm that<br />
uses two loops to sort a list by names.<br />
Sub Sort<br />
Dim Entry(1 To 10) As String<br />
Dim Count As Integer<br />
Dim Count2 As Integer<br />
Dim Temp As String<br />
Chapter 2 · The Language of <strong>OpenOffice</strong>.<strong>org</strong> <strong>BASIC</strong> 41
Programming Example: Sorting With Embedded Loops<br />
Entry(1) = "Patty"<br />
Entry(2) = "Kurt"<br />
Entry(3) = "Thomas"<br />
Entry(4) = "Michael"<br />
Entry(5) = "David"<br />
Entry(6) = "Cathy"<br />
Entry(7) = "Susie"<br />
Entry(8) = "Edward"<br />
Entry(9) = "Christine"<br />
Entry(10) = "Jerry"<br />
For Count = 1 To 9<br />
For Count2 = Count + 1 To 10<br />
If Entry(Count) > Entry(Count2) Then<br />
Temp = Entry(Count)<br />
Entry(Count) = Entry(Count2)<br />
Entry(Count2) = Temp<br />
End If<br />
Next Count2<br />
Next Count<br />
For Count = 1 To 10<br />
Print Entry(Count)<br />
Next Count<br />
End Sub<br />
The values are interchanged as pairs several times until they are finally sorted in<br />
ascending order. Like bubbles, the variables gradually migrate to the right position.<br />
For this reason, this algorithm is also known as a Bubble Sort.<br />
Procedures and Functions<br />
Procedures and functions form pivotal points in the structure of a program. They<br />
provide the framework for dividing a complex problem into various sub-tasks.<br />
Procedures<br />
A procedure executes an action without providing an explicit value. Its syntax is<br />
Sub Test<br />
' ... here is the actual code of the procedure<br />
End Sub<br />
The example defines a procedure called Test that contains code that can be<br />
42 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Procedures<br />
accessed from any point in the program. The call is made by entering the procedure<br />
name at the relevant point of the program.<br />
Functions<br />
A function, just like a procedure, combines a block of programs to be executed into<br />
one logical unit. However, unlike a procedure, a function provides a return value.<br />
Function Test<br />
' ... here is the actual code of the function<br />
Test = 123<br />
End Function<br />
The return value is assigned using simple assignment. The assignment does not<br />
need to be placed at the end of the function, but can be made anywhere in the<br />
function.<br />
The preceding function can be called within a program as follows:<br />
Dim A<br />
A = Test<br />
The code defines a variable A and assigns the result of the Test function to it.<br />
The return value can be overwritten several times within the function. As with classic<br />
variable assignment, the function in this example returns the value that was last<br />
assigned to it.<br />
Function Test<br />
Test = 12<br />
' ...<br />
Test = 123<br />
End Function<br />
In this example, the return value of the function is 123.<br />
If nothing is assigned, the function returns a zero value (number 0 for numerical<br />
values and a blank for strings).<br />
The return value of a function can be any type. The type is declared in the same way<br />
as a variable declaration:<br />
Function Test As Integer<br />
' ... here is the actual code of the function<br />
End Function<br />
Chapter 2 · The Language of <strong>OpenOffice</strong>.<strong>org</strong> <strong>BASIC</strong> 43
Terminating Procedures and Functions Prematurely<br />
Terminating Procedures and Functions<br />
Prematurely<br />
In <strong>OpenOffice</strong>.<strong>org</strong> Basic, you can use the Exit Sub and Exit Function commands to<br />
terminate a procedure or function prematurely, for example, for error handling. These<br />
commands stop the procedure or function and return the program to the point at<br />
which the procedure or function was called up.<br />
The following example shows a procedure which terminates implementation when the<br />
ErrorOccured variable has the value True.<br />
Sub Test<br />
Dim ErrorOccured As Boolean<br />
' ...<br />
If ErrorOccured Then<br />
Exit Sub<br />
End If<br />
' ...<br />
End Sub<br />
Passing Parameters<br />
Functions and procedures can receive one or more parameters. Essential<br />
parameters must be enclosed in parentheses after the function or procedure names.<br />
The following example defines a procedure that expects an integer value A and a<br />
string B as parameters.<br />
Sub Test (A As Integer, B As String)<br />
' ...<br />
End Sub<br />
Parameters are normally passed by Reference in <strong>OpenOffice</strong>.<strong>org</strong> Basic. Changes<br />
made to the variables are retained when the procedure or function is exited:<br />
Sub Test<br />
Dim A As Integer<br />
A = 10<br />
ChangeValue(A)<br />
' The parameter A now has the value 20<br />
End Sub<br />
Sub ChangeValue(TheValue As Integer)<br />
TheValue = 20<br />
End Sub<br />
In this example, the value A that is defined in the Test function is passed as a<br />
parameter to the ChangeValue function. The value is then changed to 20 and passed<br />
44 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
to TheValue, which is retained when the function is exited.<br />
Passing Parameters<br />
You can also pass a parameter as a value if you do not want subsequent changes to<br />
the parameter to affect the value that is originally passed. To specify that a parameter<br />
is to be passed as a value, ensure that the ByVal keyword precedes the variable<br />
declaration in the function header.<br />
In the preceding example, if we replace the ChangeValue function then the<br />
superordinate variable A remains unaffected by this change. After the call for the<br />
ChangeValue function, variable A retains the value 10.<br />
Sub ChangeValue(ByVal TheValue As Integer)<br />
TheValue = 20<br />
End Sub<br />
Note – The method for passing parameters to procedures and functions in<br />
<strong>OpenOffice</strong>.<strong>org</strong> Basic is virtually identical to that in VBA. By default, the parameters<br />
are passed by reference. To pass parameters as values, use the ByVal keyword. In<br />
VBA, you can also use the keyword ByRef to force a parameter to be passed by<br />
reference. <strong>OpenOffice</strong>.<strong>org</strong> Basic recognizes but ignores this keyword, because this is<br />
already the default procedure in <strong>OpenOffice</strong>.<strong>org</strong> Basic.<br />
Optional Parameters<br />
Functions and procedures can only be called up if all the necessary parameters are<br />
passed during the call.<br />
<strong>OpenOffice</strong>.<strong>org</strong> Basic lets you define parameters as optional, that is, if the<br />
corresponding values are not included in a call, <strong>OpenOffice</strong>.<strong>org</strong> Basic passes an<br />
empty parameter. In the following example the A parameter is obligatory, whereas the<br />
B parameter is optional.<br />
Sub Test(A As Integer, Optional B As Integer)<br />
' ...<br />
End Sub<br />
The IsMissing function checks whether a parameter has been passed or is left out.<br />
Sub Test(A As Integer, Optional B As Integer)<br />
Dim B_Local As Integer<br />
' Check whether B parameter is actually present<br />
If Not IsMissing (B) Then<br />
B_Local = B ' B parameter present<br />
Else<br />
B_Local = 0 ' B parameter missing -> default value 0<br />
End If<br />
Chapter 2 · The Language of <strong>OpenOffice</strong>.<strong>org</strong> <strong>BASIC</strong> 45
Optional Parameters<br />
' ... Start the actual function<br />
End Sub<br />
The example first tests whether the B parameter has been passed and, if necessary,<br />
passes the same parameter to the internal B_Local variable. If the corresponding<br />
parameter is not present, then a default value (in this instance, the value 0) is passed<br />
to B_Local rather than the passed parameter.<br />
Note – The ParamArray keyword present in VBA is not supported in <strong>OpenOffice</strong>.<strong>org</strong><br />
Basic.<br />
Recursion<br />
A recursive procedure or function is one that has the ability to call itself until it detects<br />
that some base condition has been satisfied. When the function is called with the<br />
base condition, a result is returned.<br />
The following example uses a recursive function to calculate the factorial of the<br />
numbers 42, -42, and 3.14:<br />
Sub Main<br />
Msgbox CalculateFactorial( 42 ) ' Displays 1,40500611775288E+51<br />
Msgbox CalculateFactorial( -42 ) ' Displays "Invalid number for<br />
factorial!"<br />
Msgbox CalculateFactorial( 3.14 ) ' Displays "Invalid number for<br />
factorial!"<br />
End Sub<br />
Function CalculateFactorial( Number )<br />
If Number < 0 Or Number Int( Number ) Then<br />
CalculateFactorial = "Invalid number for factorial!"<br />
ElseIf Number = 0 Then<br />
CalculateFactorial = 1<br />
Else<br />
' This is the recursive call:<br />
CalculateFactorial = Number * CalculateFactorial( Number - 1 )<br />
Endif<br />
End Function<br />
The example returns the factorial of the number 42 by recursively calling the<br />
CalculateFactorial function until it reaches the base condition of 0! = 1.<br />
Note – The recursion levels are set at different levels based on the software<br />
platform. For Windows the recursion level is 5800. For Solaris and Linux, an<br />
evaluation of the stacksize is performed and the recursion level is calculated.<br />
46 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Error Handling<br />
Recursion<br />
Correct handling of error situations is one of the most time-consuming tasks of<br />
programming. <strong>OpenOffice</strong>.<strong>org</strong> Basic provides a range of tools for simplifying error<br />
handling.<br />
The On Error Instruction<br />
The On Error instruction is the key to any error handling:<br />
Sub Test<br />
On Error Goto ErrorHandler<br />
' ... undertake task during which an error may occur<br />
Exit Sub<br />
ErrorHandler:<br />
' ... individual code for error handling<br />
End Sub<br />
The On Error Goto ErrorHandler line defines how <strong>OpenOffice</strong>.<strong>org</strong> Basic proceeds in<br />
the event of an error. The Goto ErrorHandler ensures that <strong>OpenOffice</strong>.<strong>org</strong> Basic<br />
exits the current program line and then executes the ErrorHandler: code.<br />
The Resume Command<br />
The Resume Next command continues the program from the line that follows where<br />
the error occurred in the program after the code in the error handler has been<br />
executed:<br />
ErrorHandler:<br />
' ... individual code for error handling<br />
Resume Next<br />
Use the Resume Proceed command to specify a jump point for continuing the program<br />
after error handling:<br />
ErrorHandler:<br />
' ... individual code for error handling<br />
Resume Proceed<br />
Proceed:<br />
' ... the program continues here after the error<br />
Chapter 2 · The Language of <strong>OpenOffice</strong>.<strong>org</strong> <strong>BASIC</strong> 47
The Resume Command<br />
To continue a program without an error message when an error occurs, use the<br />
following format:<br />
Sub Test<br />
On Error Resume Next<br />
' ... perform task during which an error may occur<br />
End Sub<br />
Use the On Error Resume Next command with caution as its effect is global.<br />
Queries Regarding Error Information<br />
In error handling, it is useful to have a description of the error and to know where and<br />
why the error occurred:<br />
The Err variable contains the number of errors that has occurred.<br />
The Error$ variable contains a description of the error.<br />
The Erl variable contains the line number where the error occurred.<br />
The call<br />
MsgBox "Error " & Err & ": " & Error$ & " (line : " & Erl & ")"<br />
shows how the error information can be displayed in a message window.<br />
Note – Whereas VBA summarizes the error messages in a statistical object called<br />
Err, <strong>OpenOffice</strong>.<strong>org</strong> Basic provides the Err, Error$, and Erl variables.<br />
The status information remains valid until the program encounters a Resume or On<br />
Error command, whereupon the information is reset.<br />
Note – In VBA, the Err.Clear method of the Err object resets the error status after<br />
an error occurs. In <strong>OpenOffice</strong>.<strong>org</strong> Basic, this is accomplished with the On Error or<br />
Resume commands.<br />
Tips for Structured Error Handling<br />
Both the definition command, On Error, and the return command, Resume, are<br />
variants of the Goto construct.<br />
48 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Tips for Structured Error Handling<br />
If you want to cleanly structure your code to prevent generating errors when you use<br />
this construct, you should not use jump commands without monitoring them.<br />
Care should be taken when you use the On Error Resume Next command as this<br />
dismisses all open error messages.<br />
The best solution is to use only one approach for error handling within a program -<br />
keep error handling separate from the actual program code and do not jump back to<br />
the original code after the error occurs.<br />
The following code is an example of an error handling procedure:<br />
Sub Example<br />
' Define error handler at the start of the function<br />
On Error Goto ErrorHandler<br />
' ... Here is the actual program code<br />
On Error Goto 0 ' Deactivate error handling<br />
' End of regular program implementation<br />
Exit Sub<br />
' Start point of error handling<br />
ErrorHandler:<br />
' Check whether error was expected<br />
If Err = ExpectedErrorNo Then<br />
' ... Process error<br />
Else<br />
' ... Warning of unexpected error<br />
End If<br />
On Error Goto 0 ' Deactivate error handling<br />
End Sub<br />
This procedure begins with the definition of an error handler, followed by the actual<br />
program code. At the end of the program code, the error handling is deactivated by<br />
the On Error Goto 0 call and the procedure implementation is ended by the Exit Sub<br />
command (not to be confused with End Sub).<br />
The example first checks if the error number corresponds to the expected number (as<br />
stored in the imaginary ExpectedErrorNo constant) and then handles the error<br />
accordingly. If another error occurs, the system outputs a warning. It is important to<br />
check the error number so that unanticipated errors can be detected.<br />
The On Error Goto 0 call at the end of the code resets the status information of the<br />
error (the error code in the Err system variables) so that an error occurring at a later<br />
date can be clearly recognized.<br />
Chapter 2 · The Language of <strong>OpenOffice</strong>.<strong>org</strong> <strong>BASIC</strong> 49
Tips for Structured Error Handling<br />
Other Instructions<br />
Type...End Type<br />
A struct is a collection of data fields, that can be manipulated as a single item. In<br />
older terms, you may think of a struct as a record, or part of a record.<br />
The API often uses pre-defined structs, but these are UNO structs, a highlyspecialized<br />
kind of struct.<br />
Definition<br />
With the Type...End Type statements, you can define your own (non-UNO) structs:<br />
Type aMenuItem 'assign the name of the type<br />
'Define the data fields within the struct. Each<br />
' definition looks like a Dim statement, without the "Dim".<br />
aCommand as String<br />
aText as String<br />
End Type 'close the definition<br />
Instance<br />
The Type definition is only a pattern or template, not a set of actual variables. To<br />
make an instance of the type, actual variables that can be read and stored, use the<br />
Dim as New statement:<br />
Dim maItem as New aMenuItem<br />
Scope<br />
As shown in the example below, the Type definition may be written at the start of a<br />
module (before the first Sub or Function). The definition will then be available to all<br />
routines in the module.<br />
As of <strong>OpenOffice</strong>.<strong>org</strong> Version 3.0, unlike variables, there is no way to make the<br />
definition accessible outside of the module.<br />
50 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Type...End Type<br />
An instance of the new type is a variable, and follows the usual rules for variable<br />
scope (see Scope and Life Span of Variables).<br />
An example of how to use the definition, and how to reference the fields within an<br />
instance, appears in the section on With...End With.<br />
With...End With<br />
Qualifiers<br />
In general, Basic does not look inside a container, such as an Object, to see what<br />
names might be defined there. If you want to use such a name, you must tell Basic<br />
where to look. You do that by using the name of the object as a qualifier. Write it<br />
before the inner name, and separate it by a period:<br />
MyObject.SomeName<br />
Since containers may hold other containers, you may need more than one qualifier.<br />
Write the qualifiers in order, from outer to inner:<br />
OuterObject.InnerObject.FarInsideObject.SomeName<br />
These names may also be described as, "concatenated with the dot-operator ('.')".<br />
The With Alternative<br />
The With...End With bracketing statements provide an alternative to writing out all<br />
the qualifiers, every time - and some of the qualifiers in the API can be quite long. You<br />
specify the qualifiers in the With statement. Until Basic encounters the End With<br />
statement, it looks for partly-qualified names: names that begin with a period (unary<br />
dot-operator). The compiler uses the qualifiers from the With as though they were<br />
written in front of the partly-qualified name.<br />
Chapter 2 · The Language of <strong>OpenOffice</strong>.<strong>org</strong> <strong>BASIC</strong> 51
With...End With<br />
Example 1: A User-defined Struct<br />
This example shows how you may define and use a struct, and how to reference the<br />
items within it, both with and without With. Either way, the names of the data fields<br />
(from the Type definition) must be qualified by the name of the instance (from the Dim<br />
statement).<br />
Type aMenuItem<br />
aCommand as String<br />
aText as String<br />
End Type<br />
Sub Main<br />
'Create an instance of the user-defined struct.<br />
' Note the keyword, "New".<br />
Dim maItem as New aMenuItem<br />
With maItem<br />
.aCommand = ".uno:Copy"<br />
.aText = "~Copy"<br />
End With<br />
MsgBox "Command: " & maItem.aCommand & Chr(13) _<br />
& "Text: " & maItem.aText<br />
End Sub<br />
Example 2: Case statement<br />
In Cells and Ranges, the following example has the qualifiers in the Case statements<br />
written out completely, for clarity. You can write it more easily, this way:<br />
Dim Doc As Object<br />
Dim Sheet As Object<br />
Dim Cell As Object<br />
Doc = StarDesktop.CurrentComponent<br />
Sheet = Doc.Sheets(0)<br />
Cell = Sheet.getCellByPosition(1,1) 'Cell "B2" (0-based!)<br />
Cell.Value = 1000<br />
With com.sun.star.table.CellContentType<br />
Select Case Cell.Type<br />
Case .EMPTY<br />
MsgBox "Content: Empty"<br />
Case .VALUE<br />
MsgBox "Content: Value"<br />
Case .TEXT<br />
MsgBox "Content: Text"<br />
Case .FORMULA<br />
MsgBox "Content: Formula"<br />
End Select<br />
End With<br />
52 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Notice that the With construct must be entirely outside of the Select construct.<br />
With...End With<br />
Chapter 2 · The Language of <strong>OpenOffice</strong>.<strong>org</strong> <strong>BASIC</strong> 53
3<br />
C H A P T E R 3<br />
3 The Runtime Library of<br />
<strong>OpenOffice</strong>.<strong>org</strong> Basic<br />
The following sections present the central functions of the runtime library:<br />
Conversion Functions<br />
Strings<br />
Date and Time<br />
Files and Directories<br />
Message and Input Boxes<br />
Other Functions<br />
Conversion Functions<br />
In many situations, circumstances arise in which a variable of one type has to be<br />
changed into a variable of another type.<br />
55
Implicit and Explicit Type Conversions<br />
Implicit and Explicit Type Conversions<br />
The easiest way to change a variable from one type to another is to use an<br />
assignment.<br />
Dim A As String<br />
Dim B As Integer<br />
B = 101<br />
A = B<br />
In this example, variable A is a string, and variable B is an integer. <strong>OpenOffice</strong>.<strong>org</strong><br />
Basic ensures that variable B is converted to a string during assignment to variable A.<br />
This conversion is much more elaborate than it appears: the integer B remains in the<br />
working memory in the form of a two-byte long number. A, on the other hand, is a<br />
string, and the computer saves a one- or two-byte long value for each character<br />
(each number). Therefore, before copying the content from B to A, B has to be<br />
converted into A's internal format.<br />
Unlike most other programming languages, Basic performs type conversion<br />
automatically. However, this may have fatal consequences. Upon closer inspection,<br />
the following code sequence<br />
Dim A As String<br />
Dim B As Integer<br />
Dim C As Integer<br />
B = 1<br />
C = 1<br />
A = B + C<br />
which at first glance seems straightforward, ultimately proves to be something of a<br />
trap. The Basic interpreter first calculates the result of the addition process and then<br />
converts this into a string, which, as its result, produces the string 2.<br />
If, on the other hand, the Basic interpreter first converts the start values B and C into a<br />
string and applies the plus operator to the result, it produces the string 11.<br />
The same applies when using variant variables:<br />
Dim A<br />
Dim B<br />
Dim C<br />
B = 1<br />
C = "1"<br />
A = B + C<br />
Since variant variables may contain both numbers and strings, it is unclear whether<br />
variable A is assigned the number 2 or the string 11.<br />
56 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Implicit and Explicit Type Conversions<br />
The error sources noted for implicit type conversions can only be avoided by careful<br />
programming; for example, by not using the variant data type.<br />
To avoid other errors resulting from implicit type conversions, <strong>OpenOffice</strong>.<strong>org</strong> Basic<br />
offers a range of conversion functions, which you can use to define when the data<br />
type of an operation should be converted:<br />
CStr(Var)<br />
CInt(Var)<br />
CLng(Var)<br />
CSng(Var)<br />
CDbl(Var)<br />
converts any data type into a string.<br />
converts any data types into an integer value.<br />
converts any data types into a long value.<br />
converts any data types into a single value.<br />
converts any data types into a double value.<br />
CBool(Var)<br />
converts any data types into a Boolean value.<br />
CDate(Var)<br />
converts any data types into a date value.<br />
You can use these conversion functions to define how <strong>OpenOffice</strong>.<strong>org</strong> Basic should<br />
perform these type conversion operations:<br />
Dim A As String<br />
Dim B As Integer<br />
Dim C As Integer<br />
B = 1<br />
C = 1<br />
A = CStr(B + C) ' B and C are added together first, then<br />
' converted to the string "2"<br />
A = CStr(B) + CStr(C) ' B and C are converted into a string,then<br />
' combined to produce the string "11"<br />
During the first addition in the example, <strong>OpenOffice</strong>.<strong>org</strong> Basic first adds the integer<br />
variables and then converts the result into a chain of characters. A is assigned the<br />
string 2. In the second instance, the integer variables are first converted into two<br />
strings and then linked with one another by means of the assignment. A is therefore<br />
assigned the string 11.<br />
Chapter 3 · The Runtime Library of <strong>OpenOffice</strong>.<strong>org</strong> Basic 57
Implicit and Explicit Type Conversions<br />
The numerical CSng and CDbl conversion functions also accept decimal numbers. The<br />
symbol defined in the corresponding country-specific settings must be used as the<br />
decimal point symbol. Conversely, the CStr methods use the currently selected<br />
country-specific settings when formatting numbers, dates and time details.<br />
The Val function is different from the Csng, Cdbl and Cstr methods. It converts a<br />
string into a number; however it always expects a period to be used as the decimal<br />
point symbol.<br />
Dim A As String<br />
Dim B As Double<br />
A = "2.22"<br />
B = Val(A) ' Is converted correctly regardless of the<br />
' country-specific settings<br />
Checking the Content of Variables<br />
In some instances, the date cannot be converted:<br />
Dim A As String<br />
Dim B As Date<br />
A = "test"<br />
B = A ' Creates error message<br />
In the example shown, the assignment of the test string to a date variable makes no<br />
sense, so the Basic interpreter reports an error. The same applies when attempting to<br />
assign a string to a Boolean variable:<br />
Dim A As String<br />
Dim B As Boolean<br />
A = "test"<br />
B = A ' Creates error message<br />
Again, the basic interpreter reports an error.<br />
These error messages can be avoided by checking the program before an<br />
assignment, in order to establish whether the content of the variable to be assigned<br />
matches the type of the target variable. <strong>OpenOffice</strong>.<strong>org</strong> Basic provides the following<br />
test functions for this purpose:<br />
IsNumeric(Value)<br />
checks whether a value is a number.<br />
58 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
IsDate(Value)<br />
checks whether a value is a date.<br />
IsArray(Value)<br />
checks whether a value is an array.<br />
Checking the Content of Variables<br />
These functions are especially useful when querying user input. For example, you<br />
can check whether a user has typed a valid number or date.<br />
If IsNumeric(UserInput) Then<br />
ValidInput = UserInput<br />
Else<br />
ValidInput = 0<br />
MsgBox "Error message."<br />
End If<br />
In the previous example, if the UserInput variable contains a valid numerical value,<br />
then this is assigned to the ValidInput variable. If UserInput does not contain a valid<br />
number, ValidInput is assigned the value 0 and an error message is returned.<br />
While test functions exist for checking numbers, date details and arrays in<br />
<strong>OpenOffice</strong>.<strong>org</strong> Basic, a corresponding function for checking Boolean values does<br />
not exist. The functionality can, however, be imitated by using the IsBoolean function:<br />
Function IsBoolean(Value As Variant) As Boolean<br />
On Error Goto ErrorIsBoolean:<br />
Dim Dummy As Boolean<br />
Dummy = Value<br />
IsBoolean = True<br />
On Error Goto 0<br />
Exit Sub<br />
ErrorIsBoolean:<br />
IsBoolean = False<br />
On Error Goto 0<br />
End Function<br />
The IsBoolean function defines an internal Dummy help variable of the Boolean type<br />
and tries to assign this to the transferred value. If assignment is successful, the<br />
function returns True. If it fails, a runtime error is produced, the error handler<br />
intercepts the error, and the function returns False.<br />
Note – If a string in <strong>OpenOffice</strong>.<strong>org</strong> Basic contains a non-numerical value and if this<br />
is assigned to a number, <strong>OpenOffice</strong>.<strong>org</strong> Basic does not produce an error message,<br />
but stops converting the string at the first invalid character. This procedure differs<br />
from VBA. There, an error is triggered and program implementation terminated if a<br />
corresponding assignment is executed.<br />
Chapter 3 · The Runtime Library of <strong>OpenOffice</strong>.<strong>org</strong> Basic 59
Checking the Content of Variables<br />
Strings<br />
Working with Sets of Characters<br />
When administering strings, <strong>OpenOffice</strong>.<strong>org</strong> Basic uses the set of Unicode<br />
characters. The Asc and Chr functions allow the Unicode value belonging to a<br />
character to be established and/or the corresponding character to be found for a<br />
Unicode value. The following expressions assign the various Unicode values to the<br />
code variable:<br />
Code = Asc("A") ' Latin letter A (Unicode-value 65)<br />
Code = Asc("€") ' Euro character (Unicode-value 8364)<br />
Code = Asc("Л") ' Cyrillic letter Л (Unicode-value 1083)<br />
Conversely, the expression<br />
MyString = Chr(13)<br />
ensures that the MyString string is initialized with the value of the number 13, which<br />
stands for a hard line break.<br />
The Chr command is often used in Basic languages to insert control characters in a<br />
string. The assignment<br />
MyString = Chr(9) + "This is a test" + Chr(13)<br />
therefore ensures that the text is preceded by a tab character (Unicode-value 9) and<br />
that a hard line break (Unicode-value 13) is added after the text.<br />
Accessing Parts of a String<br />
<strong>OpenOffice</strong>.<strong>org</strong> Basic provides three functions that return partial strings, plus a length<br />
function:<br />
Left(MyString, Length)<br />
returns the first Length characters of MyString.<br />
Right(MyString, Length)<br />
returns the last Length characters of MyString.<br />
60 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Mid(MyString, Start, Length)<br />
returns first Length characters of MyString as of the Start position.<br />
Len(MyString)<br />
returns the number of characters in MyString.<br />
Here are a few example calls for the named functions:<br />
Dim MyString As String<br />
Dim MyResult As String<br />
Dim MyLen As Integer<br />
MyString = "This is a small test"<br />
MyResult = Left(MyString,5) ' Provides the string "This "<br />
MyResult = Right(MyString, 5) ' Provides the string " test"<br />
MyResult = Mid(MyString, 8, 5) ' Provides the string " a sm"<br />
MyLen = Len(MyString) ' Provides the value 20<br />
Search and Replace<br />
Accessing Parts of a String<br />
<strong>OpenOffice</strong>.<strong>org</strong> Basic provides the InStr function for searching for a partial string<br />
within another string:<br />
ResultString = InStr (MyString, SearchString)<br />
The SearchString parameter specifies the string to be searched for within MyString.<br />
The function returns a number that contains the position at which the SearchString<br />
first appears within MyString. If you want to find other matches for the string, the<br />
function also provides the opportunity to specify an optional start position from which<br />
<strong>OpenOffice</strong>.<strong>org</strong> Basic begins the search. In this case, the syntax of the function is:<br />
ResultString = InStr(StartPosition, MyString, SearchString)<br />
In the previous examples, InStr ignores uppercase and lowercase characters. To<br />
change the search so that InStr is case sensitive, add the parameter 0, as shown in<br />
the following example:<br />
ResultString = InStr(MyString, SearchString, 0)<br />
Using the previous functions for editing strings, programmers can search for and<br />
replace one string in another string:<br />
Function Replace(Source As String, Search As String, NewPart As String)<br />
Dim Result As String<br />
Dim StartPos As Long<br />
Dim CurrentPos As Long<br />
Result = ""<br />
StartPos = 1<br />
Chapter 3 · The Runtime Library of <strong>OpenOffice</strong>.<strong>org</strong> Basic 61
Search and Replace<br />
CurrentPos = 1<br />
If Search = "" Then<br />
Result = Source<br />
Else<br />
Do While CurrentPos 0<br />
CurrentPos = InStr(StartPos, Source, Search)<br />
If CurrentPos 0 Then<br />
Result = Result + Mid(Source, StartPos, _<br />
CurrentPos - StartPos)<br />
Result = Result + NewPart<br />
StartPos = CurrentPos + Len(Search)<br />
Else<br />
Result = Result + Mid(Source, StartPos, Len(Source))<br />
End If ' Position 0<br />
Loop<br />
End If<br />
Replace = Result<br />
End Function<br />
The function searches through the transferred Search string in a loop by means of<br />
InStr in the original term Source. If it finds the search term, it takes the part before<br />
the expression and writes it to the Result return buffer. It adds the NewPart section at<br />
the point of the search term Search. If no more matches are found for the search<br />
term, the function establishes the part of the string still remaining and adds this to the<br />
return buffer. It returns the string produced in this way as the result of the<br />
replacement process.<br />
Since replacing parts of character sequences is one of the most frequently used<br />
functions, the Mid function in <strong>OpenOffice</strong>.<strong>org</strong> Basic has been extended so that this<br />
task is performed automatically. The following example replaces three characters with<br />
the string is from the sixth position of the MyString string.<br />
Dim MyString As String<br />
MyString = "This was my text"<br />
Mid(MyString, 6, 3, "is")<br />
Formatting Strings<br />
The Format function formats numbers as a string. To do this, the function expects a<br />
Format expression to be specified, which is then used as the template for formatting<br />
the numbers. Each place holder within the template ensures that this item is<br />
formatted correspondingly in the output value. The five most important place holders<br />
within a template are the zero (0), pound sign (#), period (.), comma (,) and dollar<br />
sign ($) characters.<br />
62 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Formatting Strings<br />
The 0 character within the template ensures that a number is always placed at the<br />
corresponding point. If a number is not provided, 0 is displayed in its place.<br />
A . stands for the decimal point symbol defined by the operating system in the<br />
country-specific settings.<br />
The example below shows how the 0 and . characters can define the digits after the<br />
decimal point in an expression:<br />
MyFormat = "0.00"<br />
MyString = Format(-1579.8, MyFormat) ' Provides "-1579,80"<br />
MyString = Format(1579.8, MyFormat) ' Provides "1579,80"<br />
MyString = Format(0.4, MyFormat) ' Provides "0,40"<br />
MyString = Format(0.434, MyFormat) ' Provides "0,43"<br />
In the same way, zeros can be added in front of a number to achieve the desired<br />
length:<br />
MyFormat = "0000.00"<br />
MyString = Format(-1579.8, MyFormat) ' Provides "-1579,80"<br />
MyString = Format(1579.8, MyFormat) ' Provides "1579,80"<br />
MyString = Format(0.4, MyFormat) ' Provides "0000,40"<br />
MyString = Format(0.434, MyFormat) ' Provides "0000,43"<br />
A , represents the character that the operating system uses for a thousands<br />
separator, and the # stands for a digit or place that is only displayed if it is required by<br />
the input string.<br />
MyFormat = "#,##0.00"<br />
MyString = Format(-1579.8, MyFormat) ' Provides "-1.579,80"<br />
MyString = Format(1579.8, MyFormat) ' Provides "1.579,80"<br />
MyString = Format(0.4, MyFormat) ' Provides "0,40"<br />
MyString = Format(0.434, MyFormat) ' Provides "0,43"<br />
In place of the $ place holder, the Format function displays the relevant currency<br />
symbol defined by the system (this example assumes a European locale has been<br />
defined):<br />
MyFormat = "#,##0.00 $"<br />
MyString = Format(-1579.8, MyFormat) ' Provides "-1.579,80 €"<br />
MyString = Format(1579.8, MyFormat) ' Provides "1.579,80 €"<br />
MyString = Format(0.4, MyFormat) ' Provides "0,40 €"<br />
MyString = Format(0.434, MyFormat) ' Provides "0,43 €"<br />
The format instructions used in VBA for formatting date and time details can also be<br />
used:<br />
sub main<br />
dim myDate as date<br />
myDate = "01/06/98"<br />
TestStr = Format(myDate, "mm-dd-yyyy") ' 01-06-1998<br />
MsgBox TestStr<br />
end sub<br />
Chapter 3 · The Runtime Library of <strong>OpenOffice</strong>.<strong>org</strong> Basic 63
Formatting Strings<br />
Date and Time<br />
<strong>OpenOffice</strong>.<strong>org</strong> Basic provides the Date data type, which saves the date and time<br />
details in binary format.<br />
Specification of Date and Time Details<br />
within the Program Code<br />
You can assign a date to a date variable through the assignment of a simple string:<br />
Dim MyDate As Date<br />
MyDate = "24.1.2002"<br />
This assignment can function properly because <strong>OpenOffice</strong>.<strong>org</strong> Basic automatically<br />
converts the date value defined as a string into a date variable. This type of<br />
assignment, however, can cause errors, date and time values are defined and<br />
displayed differently in different countries.<br />
Since <strong>OpenOffice</strong>.<strong>org</strong> Basic uses the country-specific settings of the operating<br />
system when converting a string into a date value, the expression shown previously<br />
only functions correctly if the country-specific settings match the string expression.<br />
To avoid this problem, the DateSerial function should be used to assign a fixed value<br />
to a date variable:<br />
Dim MyVar As Date<br />
MyDate = DateSerial (2001, 1, 24)<br />
The function parameter must be in the sequence: year, month, day. The function<br />
ensures that the variable is actually assigned the correct value regardless of the<br />
country-specific settings<br />
The TimeSerial function formats time details in the same way that the DateSerial<br />
function formats dates:<br />
Dim MyVar As Date<br />
MyDate = TimeSerial(11, 23, 45)<br />
Their parameters should be specified in the sequence: hours, minutes, seconds.<br />
64 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Extracting Date and Time Details<br />
Extracting Date and Time Details<br />
The following functions form the counterpart to the DateSerial and TimeSerial<br />
functions:<br />
Day(MyDate)<br />
returns the day of the month from MyDate.<br />
Month(MyDate)<br />
returns the month from MyDate.<br />
Year(MyDate)<br />
returns the year from MyDate.<br />
Weekday(MyDate)<br />
returns the number of the weekday from MyDate.<br />
Hour(MyTime)<br />
returns the hours from MyTime.<br />
Minute(MyTime)<br />
returns the minutes from MyTime.<br />
Second(MyTime)<br />
returns the seconds from MyTime.<br />
These functions extract the date or time sections from a specified Date variable. The<br />
following example checks whether the date saved in MyDate is in the year 2003.<br />
Dim MyDate As Date<br />
' ... Initialization of MyDate<br />
If Year(MyDate) = 2003 Then<br />
' ... Specified date is in the year 2003<br />
End If<br />
In the same way, the following example checks whether MyTime is between 12 and 14<br />
hours.<br />
Dim MyTime As Date<br />
' ... Initialization of MyTime<br />
If Hour(MyTime) >= 12 And Hour(MyTime) < 14 Then<br />
' ... Specified time is between 12 and 14 hours<br />
End If<br />
The Weekday function returns the number of the weekday for the transferred date:<br />
Dim MyDate As Date<br />
Chapter 3 · The Runtime Library of <strong>OpenOffice</strong>.<strong>org</strong> Basic 65
Extracting Date and Time Details<br />
Dim MyWeekday As String<br />
' ... initialize MyDate<br />
Select Case WeekDay(MyDate)<br />
case 1<br />
MyWeekday = "Sunday"<br />
case 2<br />
MyWeekday = "Monday"<br />
case 3<br />
MyWeekday = "Tuesday"<br />
case 4<br />
MyWeekday = "Wednesday"<br />
case 5<br />
MyWeekday = "Thursday"<br />
case 6<br />
MyWeekday = "Friday"<br />
case 7<br />
MyWeekday = "Saturday"<br />
End Select<br />
Note – Sunday is considered the first day of the week.<br />
Retrieving System Date and Time<br />
The following functions are available in <strong>OpenOffice</strong>.<strong>org</strong> Basic to retrieve the system<br />
time and system date:<br />
Date<br />
Time<br />
Now<br />
returns the present date as a string. The format depends on localization<br />
settings.<br />
returns the present time as a string.<br />
returns the present point in time (date and time) as a combined value of type<br />
Date.<br />
Files and Directories<br />
Working with files is one of the basic tasks of an application. The <strong>OpenOffice</strong>.<strong>org</strong> API<br />
provides you with a whole range of objects with which you can create, open and<br />
66 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Retrieving System Date and Time<br />
modify Office documents. These are presented in detail in the Introduction to the<br />
<strong>OpenOffice</strong>.<strong>org</strong> API. Regardless of this, in some instances you will have to directly<br />
access the file system, search through directories or edit text files. The runtime library<br />
from <strong>OpenOffice</strong>.<strong>org</strong> Basic provides several fundamental functions for these tasks.<br />
Note – Some DOS-specific file and directory functions are no longer provided in<br />
<strong>OpenOffice</strong>.<strong>org</strong>, or their function is only limited. For example, support for the ChDir,<br />
ChDrive and CurDir functions is not provided. Some DOS-specific properties are no<br />
longer used in functions that expect file properties as parameters (for example, to<br />
differentiate from concealed files and system files). This change became necessary<br />
to ensure the greatest possible level of platform independence for <strong>OpenOffice</strong>.<strong>org</strong>.<br />
Administering Files<br />
Compatibility Mode<br />
The CompatibilityMode statement and function provide greater compatibility with<br />
VBA, by changing the operation of certain functions. The effect on any particular<br />
function is described with that function, below.<br />
As a statement, CompatibilityMode( value ) takes a Boolean value to set or clear<br />
the mode. As a function, CompatibilityMode() returns the Boolean value of the<br />
mode.<br />
CompatibilityMode( True ) 'set mode<br />
CompatibilityMode( False) 'clear mode<br />
Dim bMode as Boolean<br />
bMode = CompatibilityMode()<br />
Searching Through Directories<br />
The Dir function in <strong>OpenOffice</strong>.<strong>org</strong> Basic is responsible for searching through<br />
directories for files and sub-directories. When first requested, a string containing the<br />
path of the directories to be searched must be assigned to Dir as its first parameter.<br />
The second parameter of Dir specifies the file or directory to be searched for.<br />
<strong>OpenOffice</strong>.<strong>org</strong> Basic returns the name of the first directory entry found. To retrieve<br />
the next entry, the Dir function should be requested without parameters. If the Dir<br />
function finds no more entries, it returns an empty string.<br />
Chapter 3 · The Runtime Library of <strong>OpenOffice</strong>.<strong>org</strong> Basic 67
Administering Files<br />
The following example shows how the Dir function can be used to request all files<br />
located in one directory. The procedure saves the individual file names in the<br />
AllFiles variable and then displays this in a message box.<br />
Sub ShowFiles<br />
Dim NextFile As String<br />
Dim AllFiles As String<br />
AllFiles = ""<br />
NextFile = Dir("C:\", 0)<br />
While NextFile ""<br />
AllFiles = AllFiles & Chr(13) & NextFile<br />
NextFile = Dir<br />
Wend<br />
MsgBox AllFiles<br />
End Sub<br />
The 0 (zero) used as the second parameter in the Dir function ensures that Dir only<br />
returns the names of files and directories are ignored. The following parameters can<br />
be specified here:<br />
0 : returns normal files<br />
16 : sub-directories<br />
The following example is virtually the same as the preceding example, but the Dir<br />
function transfers the value 16 as a parameter, which returns the sub-directories of a<br />
folder rather than the file names.<br />
Sub ShowDirs<br />
Dim NextDir As String<br />
Dim AllDirs As String<br />
AllDirs = ""<br />
NextDir = Dir("C:\", 16)<br />
While NextDir ""<br />
AllDirs = AllDirs & Chr(13) & NextDir<br />
NextDir = Dir<br />
Wend<br />
MsgBox AllDirs<br />
End Sub<br />
Note – When requested in <strong>OpenOffice</strong>.<strong>org</strong> Basic, the Dir function, using the<br />
parameter 16, only returns the sub-directories of a folder. In VBA, the function also<br />
returns the names of the standard files so that further checking is needed to retrieve<br />
the directories only. When using the CompatibilityMode ( true ) function,<br />
<strong>OpenOffice</strong>.<strong>org</strong> Basic behaves like VBA and the Dir function, using parameter 16,<br />
returns sub-directories and standard files.<br />
68 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Administering Files<br />
Note – The options provided in VBA for searching through directories specifically for<br />
files with the concealed, system file, archived, and volume name properties does<br />
not exist in <strong>OpenOffice</strong>.<strong>org</strong> Basic because the corresponding file system functions<br />
are not available on all operating systems.<br />
Note – The path specifications listed in Dir may use the * and ? place holders in<br />
both VBA and <strong>OpenOffice</strong>.<strong>org</strong> Basic. In <strong>OpenOffice</strong>.<strong>org</strong> Basic, the * place holder may<br />
however only be the last character of a file name and/or file extension, which is not<br />
the case in VBA.<br />
Creating and Deleting Directories<br />
<strong>OpenOffice</strong>.<strong>org</strong> Basic provides the MkDir function for creating directories.<br />
MkDir ("C:\SubDir1")<br />
This function creates directories and sub-directories. All directories needed within a<br />
hierarchy are also created, if required. For example, if only the C:\SubDir1 directory<br />
exists, then a call<br />
MkDir ("C:\SubDir1\SubDir2\SubDir3\")<br />
creates both the C:\SubDir1\SubDir2 directory and the C:\SubDir1\SubDir2\SubDir3<br />
directory.<br />
The RmDir function deletes directories.<br />
RmDir ("C:\SubDir1\SubDir2\SubDir3\")<br />
If the directory contains sub-directories or files, these are also deleted. You should<br />
therefore be careful when using RmDir.<br />
Note – In VBA, the MkDir and RmDir functions only relate to the current directory. In<br />
<strong>OpenOffice</strong>.<strong>org</strong> Basic on the other hand, MkDir and RmDir can be used to create or<br />
delete levels of directories.<br />
Note – In VBA, RmDir produces an error message if a directory contains a file. In<br />
<strong>OpenOffice</strong>.<strong>org</strong> Basic, the directory and all its files are deleted. If you use the<br />
CompatibilityMode ( true ) function, <strong>OpenOffice</strong>.<strong>org</strong> Basic will behave like VBA.<br />
Chapter 3 · The Runtime Library of <strong>OpenOffice</strong>.<strong>org</strong> Basic 69
Administering Files<br />
Copying, Renaming, Deleting and Checking the<br />
Existence of Files<br />
The following call creates a copy of the Source file under the name of Destination:<br />
FileCopy(Source, Destination)<br />
With the help of the following function you can rename the OldName file with NewName.<br />
The As keyword syntax, and the fact that a comma is not used, goes back to the roots<br />
of the Basic language.<br />
Name OldName As NewName<br />
The following call deletes the Filename file. If you want to delete directory (including<br />
its files) use the RmDir function.<br />
Kill(Filename)<br />
The FileExists function can be used to check whether a file exists:<br />
If FileExists(Filename) Then<br />
MsgBox "file exists."<br />
End If<br />
Reading and Changing File Properties<br />
When working with files, it is sometimes important to be able to establish the file<br />
properties, the time the file was last changed and the length of the file.<br />
The following call returns some properties about a file.<br />
Dim Attr As Integer<br />
Attr = GetAttr(Filename)<br />
The return value is provided as a bit mask in which the following values are possible:<br />
1 : read-only file<br />
16 : name of a directory<br />
The following example determines the bit mask of the test.txt file and checks<br />
whether this is read-only whether it is a directory. If neither of these apply,<br />
FileDescription is assigned the "normal" string.<br />
Dim FileMask As Integer<br />
Dim FileDescription As String<br />
FileMask = GetAttr("test.txt")<br />
If (FileMask AND 1) > 0 Then<br />
FileDescription = FileDescription & " read-only "<br />
End IF<br />
70 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
If (FileMask AND 16) > 0 Then<br />
FileDescription = FileDescription & " directory "<br />
End IF<br />
If FileDescription = "" Then<br />
FileDescription = " normal "<br />
End IF<br />
MsgBox FileDescription<br />
Administering Files<br />
Note – The flags used in VBA for querying the concealed, system file,archived<br />
and volume name file properties are not supported in <strong>OpenOffice</strong>.<strong>org</strong> Basic because<br />
these are Windows-specific and are not or are only partially available on other<br />
operating systems.<br />
The SetAttr function permits the properties of a file to be changed. The following call<br />
can therefore be used to provide a file with read-only status:<br />
SetAttr("test.txt", 1)<br />
An existing read-only status can be deleted with the following call:<br />
SetAttr("test.txt", 0)<br />
The date and time of the last amendment to a file are provided by the FileDateTime<br />
function. The date is formatted here in accordance with the country-specific settings<br />
used on the system.<br />
FileDateTime("test.txt") ' Provides date and time of the last file<br />
amendment.<br />
The FileLen function determines the length of a file in bytes (as long integer value).<br />
FileLen("test.txt") ' Provides the length of the file in bytes<br />
Writing and Reading Text Files<br />
<strong>OpenOffice</strong>.<strong>org</strong> Basic provides a whole range of methods for reading and writing files.<br />
The following explanations relate to working with text files (not text documents).<br />
Writing Text Files<br />
Before a text file is accessed, it must first be opened. To do this, a free file handle is<br />
needed, which clearly identifies the file for subsequent file access.<br />
Chapter 3 · The Runtime Library of <strong>OpenOffice</strong>.<strong>org</strong> Basic 71
Writing and Reading Text Files<br />
The FreeFile function is used to create a free file handle:<br />
FileNo = FreeFile<br />
FileNo is an integer variable that receives the file handle. The handle is then used as<br />
a parameter for the Open instruction, which opens the file.<br />
To open a file so that it can be written as a text file, the Open call is:<br />
Open Filename For Output As #FileNo<br />
Filename is a string containing the name of the file. FileNo is the handle created by<br />
the FreeFile function.<br />
Once the file is opened, the Print instruction can create the file contents, line by line:<br />
Print #FileNo, "This is a test line."<br />
FileNo also stands for the file handle here. The second parameter specifies the text<br />
that is to be saved as a line of the text file.<br />
Once the writing process has been completed, the file must be closed using a Close<br />
call:<br />
Close #FileNo<br />
Again here, the file handle should be specified.<br />
The following example shows how a text file is opened, written, and closed:<br />
Dim FileNo As Integer<br />
Dim CurrentLine As String<br />
Dim Filename As String<br />
Filename = "c:\data.txt" ' Define file name<br />
FileNo = FreeFile ' Establish free file handle<br />
Open Filename For Output As #FileNo ' Open file (writing mode)<br />
Print #FileNo, "This is a line of text" ' Save line<br />
Print #FileNo, "This is another line of text" ' Save line<br />
Close #FileNo ' Close file<br />
Reading Text Files<br />
Text files are read in the same way that they are written. The Open instruction used to<br />
open the file contains the For Input expression in place of the For Output<br />
expression and, rather than the Print command for writing data, the Line Input<br />
instruction should be used to read the data.<br />
Finally, when calling up a text file, the eof instruction is used to check whether the<br />
72 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
end of the file has been reached:<br />
eof(FileNo)<br />
The following example shows how a text file can be read:<br />
Dim FileNo As Integer<br />
Dim CurrentLine As String<br />
Dim File As String<br />
Dim Msg as String<br />
' Define filename<br />
Filename = "c:\data.txt"<br />
' Establish free file handle<br />
FileNo = Freefile<br />
' Open file (reading mode)<br />
Open Filename For Input As FileNo<br />
' Check whether file end has been reached<br />
Do While not eof(FileNo)<br />
' Read line<br />
Line Input #FileNo, CurrentLine<br />
If CurrentLine "" then<br />
Msg = Msg & CurrentLine & Chr(13)<br />
end if<br />
Loop<br />
' Close file<br />
Close #FileNo<br />
Msgbox Msg<br />
Writing and Reading Text Files<br />
The individual lines are retrieved in a Do While loop, saved in the Msg variable, and<br />
displayed at the end in a message box.<br />
Message and Input Boxes<br />
<strong>OpenOffice</strong>.<strong>org</strong> Basic provides the MsgBox and InputBox functions for basic user<br />
communication.<br />
Chapter 3 · The Runtime Library of <strong>OpenOffice</strong>.<strong>org</strong> Basic 73
Displaying Messages<br />
Displaying Messages<br />
MsgBox displays a basic information box, which can have one or more buttons. In its<br />
simplest variant the MsgBox only contains text and an OK button:<br />
MsgBox "This is a piece of information!"<br />
The appearance of the information box can be changed using a parameter. The<br />
parameter provides the option of adding additional buttons, defining the pre-assigned<br />
button, and adding an information symbol.<br />
Note – By convention, the symbolic names given below are written in UPPERCASE,<br />
to mark them as predefined, rather than user-defined. However, the names are not<br />
case-sensitive.<br />
The values for selecting the buttons are:<br />
0, MB_OK - OK button<br />
1, MB_OKCANCEL - OK and Cancel button<br />
2, MB_ABORTRETRYIGNORE - Abort, Retry, and Ignore buttons<br />
3, MB_YESNOCANCEL - Yes, No, and Cancel buttons<br />
4, MB_YESNO - Yes and No buttons<br />
5, MB_RETRYCANCEL - Retry and Cancel buttons<br />
To set a button as the default button, add one of the following values to the parameter<br />
value from the list of button selections. For example, to create Yes, No and Cancel<br />
buttons (value 3) where Cancel is the default (value 512), the parameter value is 3 +<br />
512 = 515. The expression MB_YESNOCANCEL + MB_DEFBUTTON3 is harder to write, but<br />
easier to understand.<br />
0, MB_DEFBUTTON1 - First button is default value<br />
256, MB_DEFBUTTON2 - Second button is default value<br />
512, MB_DEFBUTTON3 - Third button is default value<br />
Finally, the following information symbols are available and can also be displayed by<br />
adding the relevant parameter values:<br />
16, MB_ICONSTOP - Stop sign<br />
32, MB_ICONQUESTION - Question mark<br />
48, MB_ICONEXCLAMATION - Exclamation point<br />
64, MB_ICONINFORMATION - Tip icon<br />
The following call displays an information box with the Yes and No buttons (value 4),<br />
of which the second button (No) is set as the default value (value 256) and which also<br />
receives a question mark (value 32), 4+256+32=292.<br />
74 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Displaying Messages<br />
MsgBox "Do you want to continue?", 292<br />
' or,<br />
MsgBox "Do you want to continue?", MB_YESNO + MB_DEFBUTTON2 + MB_ICONQUESTION<br />
If an information box contains several buttons, then a return value should be queried<br />
to determine which button has been pressed. The following return values are<br />
available in this instance:<br />
1, IDOK - Ok<br />
2, IDCANCEL - Cancel<br />
3, IDABORT - Abort<br />
4, IDRETRY - Retry<br />
5 - Ignore<br />
6, IDYES - Yes<br />
7, IDNO - No<br />
In the previous example, checking the return values could be as follows:<br />
Dim iBox as Integer<br />
iBox = MB_YESNO + MB_DEFBUTTON2 + MB_ICONQUESTION<br />
If MsgBox ("Do you want to continue?", iBox) = IDYES Then<br />
' or,<br />
If MsgBox ("Do you want to continue?", 292) = 6 Then<br />
' Yes button pressed<br />
Else<br />
' No button pressed<br />
End IF<br />
In addition to the information text and the parameter for arranging the information<br />
box, MsgBox also permits a third parameter, which defines the text for the box title:<br />
MsgBox "Do you want to continue?", 292, "Box Title"<br />
If no box title is specified, the default is “soffice”.<br />
Input Box For Querying Simple Strings<br />
The InputBox function queries simple strings from the user. It is therefore a simple<br />
alternative to configuring dialogs. InputBox receives three standard parameters:<br />
An information text.<br />
A box title.<br />
A default value which can be added within the input area.<br />
InputVal = InputBox("Please enter value:", "Test", "default value")<br />
As a return value, the InputBox provides the string typed by the user.<br />
Chapter 3 · The Runtime Library of <strong>OpenOffice</strong>.<strong>org</strong> Basic 75
Input Box For Querying Simple Strings<br />
Other Functions<br />
Beep<br />
The Beep function causes the system to play a sound that can be used to warn the<br />
user of an incorrect action. Beep does not have any parameters:<br />
Beep ' creates an informative tone<br />
Shell<br />
External programs can be started using the Shell function.<br />
Shell(Pathname, Windowstyle, Param)<br />
Pathname defines the path of the program to be executed.<br />
Windowstyle defines the window in which the program is started.<br />
The following values are possible:<br />
0 - The program receives the focus and is started in a concealed window.<br />
1 - The program receives the focus and is started in a normal-sized window.<br />
2 - The program receives the focus and is started in a minimized window.<br />
3 - The program receives the focus and is started in a maximized window.<br />
4 - The program is started in a normal-sized window, without receiving the focus.<br />
6 - The program is started in a minimized window, the focus remains in the current<br />
window.<br />
10 - The program is started in full screen mode.<br />
The third parameter, Param, permits command line parameters to be transferred to<br />
the program to be started.<br />
76 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Wait and WaitUntil<br />
Wait and WaitUntil<br />
The Wait statement suspends program execution for a specified time. The waiting<br />
period is specified in milliseconds. The command:<br />
Wait 2000<br />
specifies a delay of 2 seconds (2000 milliseconds).<br />
The WaitUntil statement provides a greater degree of compatibility with VBA<br />
parameter usage. WaitUntil takes a parameter of type Date, with a combined date<br />
and time value. The command:<br />
WaitUntil Now + TimeValue("00:00:02")<br />
specifies the same delay, 2 seconds, as the previous example.<br />
Environ<br />
The Environ function returns the environmental variables of the operating system.<br />
Depending on the system and configuration, various types of data are saved here.<br />
The following call determines the environment variables of temporary directory of the<br />
operating system:<br />
Dim TempDir<br />
TempDir=Environ ("TEMP")<br />
Chapter 3 · The Runtime Library of <strong>OpenOffice</strong>.<strong>org</strong> Basic 77
4<br />
C H A P T E R 4<br />
4 Introduction to the API<br />
<strong>OpenOffice</strong>.<strong>org</strong> objects and methods, such as paragraphs, spreadsheets, and fonts,<br />
are accessible to <strong>OpenOffice</strong>.<strong>org</strong> Basic through the <strong>OpenOffice</strong>.<strong>org</strong> application<br />
programming interface, or API. Through the API, for example, documents can be<br />
created, opened, modified and printed. The API can be used not only by<br />
<strong>OpenOffice</strong>.<strong>org</strong> Basic, but also by other programming languages, such as Java and<br />
C++. The interface between the API and various programming languages is provided<br />
by something called Universal Network Objects (UNO).<br />
This chapter provides a background on the API. Building on this background, the<br />
following chapters will show how the API can be used to make <strong>OpenOffice</strong>.<strong>org</strong> do<br />
what you want it to do.<br />
Universal Network Objects (UNO)<br />
<strong>OpenOffice</strong>.<strong>org</strong> provides a programming interface in the form of the Universal<br />
Network Objects (UNO). This is an object-oriented programming interface which<br />
<strong>OpenOffice</strong>.<strong>org</strong> sub-divides into various objects which for their part ensure programcontrolled<br />
access to the Office package.<br />
Since <strong>OpenOffice</strong>.<strong>org</strong> Basic is a procedural programming language, several linguistic<br />
constructs have had to be added to it which enable the use of UNO.<br />
79
Introduction to the API<br />
To use a Universal Network Object in <strong>OpenOffice</strong>.<strong>org</strong> Basic, you will need a variable<br />
declaration for the associated object. The declaration is made using the Dim<br />
instruction (see The Language of <strong>OpenOffice</strong>.<strong>org</strong> Basic). The Object type designation<br />
should be used to declare an object variable:<br />
Dim Obj As Object<br />
The call declares an object variable named Obj.<br />
The object variable created must then be initialized so that it can be used. This can<br />
be done using the createUnoService function:<br />
Obj = createUnoService("com.sun.star.frame.Desktop")<br />
This call assigns to the Obj variable a reference to the newly created object.<br />
com.sun.star.frame.Desktop resembles an object type; however in UNO terminology<br />
it is called a service rather than a type. In accordance with UNO philosophy, an Obj is<br />
described as a reference to an object which supports the com.sun.star.frame.Desktop<br />
service. The service term used in <strong>OpenOffice</strong>.<strong>org</strong> Basic therefore corresponds to the<br />
type and class terms used in other programming languages.<br />
There is, however, one main difference: a Universal Network Object may support<br />
several services at the same time. Some UNO services in turn support other services<br />
so that, through one object, you are provided with a whole range of services. For<br />
example, that the aforementioned object, which is based on the<br />
com.sun.star.frame.Desktop service, can also include other services for loading<br />
documents and for ending the program.<br />
Note – Whereas the structure of an object in VBA is defined by the class to which it<br />
belongs, in <strong>OpenOffice</strong>.<strong>org</strong> Basic the structure is defined through the services which<br />
it supports. A VBA object is always assigned to precisely one single class. A<br />
<strong>OpenOffice</strong>.<strong>org</strong> Basic object can, however, support several services.<br />
Properties and Methods<br />
An object in <strong>OpenOffice</strong>.<strong>org</strong> Basic provides a range of properties and methods which<br />
can be called by means of the object.<br />
80 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Properties<br />
Properties<br />
Properties are like the properties of an object; for example, Filename and Title for a<br />
Document object.<br />
The properties are set by means of a simple assignment:<br />
Document.Title = "{{OOo}} Basic Programmer's <strong>Guide</strong>"<br />
Document.Filename = "basguide.odt"<br />
A property, just like a normal variable, has a type that defines which values it can<br />
record. The preceding Filename and Title properties are of the string type.<br />
Real Properties and Imitated Properties<br />
Most of the properties of an object in <strong>OpenOffice</strong>.<strong>org</strong> Basic are defined as such in the<br />
UNO description of the service. In addition to these "real" properties, there are also<br />
properties in <strong>OpenOffice</strong>.<strong>org</strong> Basic which consist of two methods at the UNO level.<br />
One of these is used to query the value of the property and the other is issued to set<br />
it (get and set methods). The property has been virtually imitated from two methods.<br />
Character objects in UNO, for example, provide the getPosition and setPosition<br />
methods through which the associated key point can be called up and changed. The<br />
<strong>OpenOffice</strong>.<strong>org</strong> Basic programmer can access the values through the Position<br />
property. Regardless of this, the original methods are also available (in our example,<br />
getPosition and setPosition).<br />
Methods<br />
Methods can be understood as functions that relate directly to an object and through<br />
which this object is called. The preceding Document object could, for example, provide<br />
a Save method, which can be called as follows:<br />
Document.Save()<br />
Methods, just like functions, may contain parameters and return values. The syntax of<br />
such method calls is oriented towards classic functions. The following call also<br />
specifies the True parameter for the document object when requesting the Save<br />
method.<br />
Ok = Document.Save(True)<br />
Chapter 4 · Introduction to the API 81
Methods<br />
Once the method has been completed, Save saves a return value in the Ok variable.<br />
Modules, Services and Interfaces<br />
<strong>OpenOffice</strong>.<strong>org</strong> provides hundreds of services. To provide an overview of these<br />
services, they have been combined into modules. The modules are of no other<br />
functional importance for <strong>OpenOffice</strong>.<strong>org</strong> Basic programmers. When specifying a<br />
service name, it is only the module name which is of any importance because this<br />
must be also listed in the name. The complete name of a service consists of the<br />
com.sun.star expression, which specifies that it is a <strong>OpenOffice</strong>.<strong>org</strong> service, followed<br />
by the module name, such as frame, and finally the actual service name, such as<br />
Desktop. The complete name in the named example would be:<br />
com.sun.star.frame.Desktop<br />
In addition to the module and service terms, UNO introduces the term 'interface'.<br />
While this term may be familiar to Java programmers, it is not used in Basic.<br />
An interface combines several methods. In the strictest sense of the word, a service<br />
in UNO does not support methods, but rather interfaces, which in turn provide<br />
different methods. In other words, the methods are assigned (as combinations) to the<br />
service in interfaces. This detail may be of interest in particular to Java- or C++<br />
programmers, since in these languages, the interface is needed to request a method.<br />
In <strong>OpenOffice</strong>.<strong>org</strong> Basic, this is irrelevant. Here, the methods are called directly by<br />
means of the relevant object.<br />
For an understanding of the API, it is, however, useful to have the assignment of<br />
methods to various interfaces handy, since many interfaces are used in the different<br />
services. If you are familiar with an interface, then you can transfer your knowledge<br />
from one service to another.<br />
Some central interfaces are used so frequently, triggered by different services, that<br />
they are shown again at the end of this chapter.<br />
Tools for Working with UNO<br />
The question remains as to which objects — or services if we are going to remain<br />
with UNO terminology — support which properties, methods and interfaces and how<br />
these can be determined. In addition to this guide, you can get more information<br />
82 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
about objects from the following sources: the supportsService method, the debug<br />
methods as well as the Developer's <strong>Guide</strong>, and the API reference.<br />
The supportsService Method<br />
Methods<br />
A number of UNO objects support the supportsService method, with which you can<br />
establish whether an object supports a particular service. The following call, for<br />
example, determines whether the TextElement object supports the<br />
com.sun.star.text.Paragraph service.<br />
Ok = TextElement.supportsService("com.sun.star.text.Paragraph")<br />
Debug Properties<br />
Every UNO object in <strong>OpenOffice</strong>.<strong>org</strong> Basic knows what properties, methods and<br />
interfaces it already contains. It provides properties that return these in the form of a<br />
list. The corresponding properties are:<br />
DBG_properties<br />
returns a string containing all properties of an object<br />
DBG_methods<br />
returns a string containing all methods of an object<br />
DBG_supportedInterfaces<br />
returns a string containing all interfaces which support an object.<br />
The following program code shows how DBG_properties and DBG_methods can be<br />
used in real-life applications. It first creates the com.sun.star.frame.Desktop service<br />
and then displays the supported properties and methods in message boxes.<br />
Dim Obj As Object<br />
Obj = createUnoService("com.sun.star.frame.Desktop")<br />
MsgBox Obj.DBG_Properties<br />
MsgBox Obj.DBG_methods<br />
When using DBG_properties, note that the function returns all properties that one<br />
particular service can theoretically support. No assurances are, however, provided for<br />
whether these can also be used by the object in question. Before calling up<br />
properties, you must therefore use the IsEmpty function to check whether this is<br />
Chapter 4 · Introduction to the API 83
Debug Properties<br />
actually available.<br />
API Reference<br />
More information about the available services, and their interfaces, methods and<br />
properties can be found in the reference for the <strong>OpenOffice</strong>.<strong>org</strong> API.<br />
Overview of Central Interfaces<br />
Some interfaces of <strong>OpenOffice</strong>.<strong>org</strong> can be found in many parts of the <strong>OpenOffice</strong>.<strong>org</strong><br />
API. They define sets of methods for abstract tasks which can be applied to various<br />
problems. Here, you will find an overview of the most common of these interfaces.<br />
The origin of the objects is explained at a later point in this guide. At this point, only<br />
some of the abstract aspects of objects, for which the <strong>OpenOffice</strong>.<strong>org</strong> API provides<br />
some central interfaces, are discussed.<br />
Creating Context-Dependent Objects<br />
The <strong>OpenOffice</strong>.<strong>org</strong> API provides two options for creating objects. One can be found<br />
in the createUnoService function mentioned at the start of this chapter.<br />
createUnoService creates an object which can be used universally. Such objects and<br />
services are also known as context-independent services.<br />
In addition to context-independent services, there are also context-dependent<br />
services whose objects are only useful when used in conjunction with another object.<br />
A drawing object for a spreadsheet document, for example, can therefore only exist in<br />
conjunction with this one document.<br />
84 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Creating Context-Dependent Objects<br />
com.sun.star.lang.XMultiServiceFactory Interface<br />
Context-dependent objects are usually created by means of an object method, on<br />
which the object depends. The createInstance method, which is defined in the<br />
XMultiServiceFactory interface, is used in particular in the document objects.<br />
The drawing object can, for example, be created as follows using a spreadsheet<br />
object:<br />
Dim RectangleShape As Object<br />
RectangleShape = _<br />
Spreadsheet.createInstance("com.sun.star.drawing.RectangleShape")<br />
A paragraph template in a text document is created in the same way:<br />
Dim Style as Object<br />
Style = Textdocument.createInstance("com.sun.star.style.ParagraphStyle")<br />
Named Access to Subordinate Objects<br />
The XNameAccess and XNameContainer interfaces are used in objects that contain<br />
subordinate objects, which can be addressed using a natural language name.<br />
While XNamedAccess permits access to the individual objects, XNameContainer takes<br />
on the insertion, modification and deletion of elements.<br />
com.sun.star.container.XNameAccess Interface<br />
An example of the use of XNameAccess is provided by the sheets object of a<br />
spreadsheet. It combines all the pages within the spreadsheet. The individual pages<br />
are accessed from the sheets object, by using the getByName method from<br />
XNameAccess:<br />
Dim Sheets As Object<br />
Dim Sheet As Object<br />
Sheets = Spreadsheet.Sheets<br />
Sheet = Sheets.getByName("Sheet1")<br />
The getElementNames method provides an overview of the names of all elements. As<br />
a result, it returns a data field containing the names. The following example shows<br />
how all element names of a spreadsheet can thereby be determined and displayed in<br />
a loop:<br />
Chapter 4 · Introduction to the API 85
Named Access to Subordinate Objects<br />
Dim Sheets As Object<br />
Dim SheetNames<br />
Dim I As Integer<br />
Sheets = Spreadsheet.Sheets<br />
SheetNames = Sheets.getElementNames<br />
For I=LBound(SheetNames) To UBound(SheetNames)<br />
MsgBox SheetNames(I)<br />
Next I<br />
The hasByName method of the XNameAccess interface reveals whether a subordinate<br />
object with a particular name exists within the basic object. The following example<br />
therefore displays a message that informs the user whether the Spreadsheet object<br />
contains a page of the name Sheet1.<br />
Dim Sheets As Object<br />
Sheets = Spreadsheet.Sheets<br />
If Sheets.HasByName("Sheet1") Then<br />
MsgBox " Sheet1 available"<br />
Else<br />
MsgBox "Sheet1 not available"<br />
End If<br />
com.sun.star.container.XNameContainer Interface<br />
The XNameContainer interface takes on the insertion, deletion and modification of<br />
subordinate elements in a basic object. The functions responsible are insertByName,<br />
removeByName and replaceByName.<br />
The following is a practical example of this. It calls a text document, which contains a<br />
StyleFamilies object and uses this to in turn make the paragraph templates<br />
(ParagraphStyles) of the document available.<br />
Dim StyleFamilies As Object<br />
Dim ParagraphStyles As Object<br />
Dim NewStyle As Object<br />
StyleFamilies = Textdoc.StyleFamilies<br />
ParagraphStyles = StyleFamilies.getByName("ParagraphStyles")<br />
ParagraphStyles.insertByName("NewStyle", NewStyle)<br />
ParagraphStyles.replaceByName("ChangingStyle", NewStyle)<br />
ParagraphStyles.removeByName("OldStyle")<br />
The insertByName line inserts the NewStyle style under the name of the same name<br />
in the ParagraphStyles object. The replaceByName line changes the object behind<br />
ChangingStyle into NewStyle. Finally, the removeByName call removes the object<br />
behind OldStyle from ParagraphStyles.<br />
86 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Index-Based Access to Subordinate Objects<br />
Index-Based Access to Subordinate<br />
Objects<br />
The XIndexAccess and XIndexContainer interfaces are used in objects which contain<br />
subordinate objects and which can be addressed using an index.<br />
XIndexAccess provides the methods for accessing individual objects.<br />
XIndexContainer provides methods for inserting and removing elements.<br />
com.sun.star.container.XIndexAccess Interface<br />
XIndexAccess provides the getByIndex and getCount methods for calling the<br />
subordinate objects. getByIndex provides an object with a particular index. getCount<br />
returns how many objects are available.<br />
Dim Sheets As Object<br />
Dim Sheet As Object<br />
Dim I As Integer<br />
Sheets = Spreadsheet.Sheets<br />
For I = 0 to Sheets.getCount() - 1<br />
Sheet = Sheets.getByIndex(I)<br />
' Editing sheet<br />
Next I<br />
The example shows a loop that runs through all sheet elements one after another<br />
and saves a reference to each in the Sheet object variable. When working with the<br />
indexes, note that getCount returns the number of elements. The elements in<br />
getByIndex however are numbered beginning with 0. The counting variable of the<br />
loop therefore runs from 0 to getCount()-1.<br />
com.sun.star.container.XIndexContainer Interface<br />
The XIndexContainer interface provides the insertByIndex and removeByIndex<br />
functions. The parameters are structured in the same way as the corresponding<br />
functions in XNameContainer.<br />
Chapter 4 · Introduction to the API 87
Iterative Access to Subordinate Objects<br />
Iterative Access to Subordinate<br />
Objects<br />
In some instances, an object may contain a list of subordinate objects that cannot be<br />
addressed by either a name or an index. In these situations, the XEnumeration and<br />
XenumerationAccess interfaces are appropriate. They provide a mechanism through<br />
which all subordinate elements of an objects can be passed, step by step, without<br />
having to use direct addressing.<br />
com.sun.star.container.XEnumeration and<br />
XenumerationAccess Interfaces<br />
The basic object must provide the XEnumerationAccess interface, which contains only<br />
a createEnumeration method. This returns an auxiliary object, which in turn provides<br />
the XEnumeration interface with the hasMoreElements and nextElement methods.<br />
Through these, you then have access to the subordinate objects.<br />
The following example steps through all the paragraphs of a text:<br />
Dim ParagraphEnumeration As Object<br />
Dim Paragraph As Object<br />
ParagraphEnumeration = Textdoc.Text.createEnumeration<br />
While ParagraphEnumeration.hasMoreElements()<br />
Paragraph = ParagraphEnumeration.nextElement()<br />
Wend<br />
The example first creates a ParagraphEnumeration auxiliary object. This gradually<br />
returns the individual paragraphs of the text in a loop. The loop is terminated as soon<br />
as the hasMoreElements method returns the False value, signaling that the end of the<br />
text has been reached.<br />
88 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
5<br />
C H A P T E R 5<br />
5 Working with <strong>OpenOffice</strong>.<strong>org</strong><br />
Documents<br />
The <strong>OpenOffice</strong>.<strong>org</strong> API has been structured so that as many of its parts as possible<br />
can be used universally for different tasks. This includes the interfaces and services<br />
for creating, opening, saving, converting, and printing documents and for template<br />
administration. Since these function areas are available in all types of documents,<br />
they are explained first in this chapter.<br />
The StarDesktop<br />
Templates<br />
The StarDesktop<br />
When working with documents, two services are used most frequently:<br />
The com.sun.star.frame.Desktop service, which is similar to the core service of<br />
<strong>OpenOffice</strong>.<strong>org</strong>. It provides the functions for the frame object of <strong>OpenOffice</strong>.<strong>org</strong>,<br />
under which all document windows are classified. Documents can also be<br />
created, opened and imported using this service.<br />
The basic functionality for the individual document objects is provided by the<br />
com.sun.star.document.OfficeDocument service. This provides the methods for<br />
saving, exporting and printing documents.<br />
89
Working with <strong>OpenOffice</strong>.<strong>org</strong> Documents<br />
The com.sun.star.frame.Desktop service is created automatically when<br />
<strong>OpenOffice</strong>.<strong>org</strong> is started. This service can be addressed in <strong>OpenOffice</strong>.<strong>org</strong> Basic<br />
using the global name StarDesktop.<br />
The most important interface of the StarDesktop is<br />
com.sun.star.frame.XComponentLoader. This basically covers the<br />
loadComponentFromURL method, which is responsible for creating, importing, and<br />
opening documents.<br />
The name of the StarDesktop object dates back to StarOffice 5, in which all<br />
document windows were embedded in one common application called StarDesktop.<br />
In the present version of <strong>OpenOffice</strong>.<strong>org</strong>, a visible StarDesktop is no longer used.<br />
The name StarDesktop was, however, retained for the frame object of<br />
<strong>OpenOffice</strong>.<strong>org</strong> because it clearly indicates that this is a basic object for the entire<br />
application.<br />
The StarDesktop object replaces the Application object of StarOffice 5 which<br />
previously applied as a root object. However, unlike the old Application object,<br />
StarDesktop is primarily responsible for opening new documents. The functions<br />
resident in the old Application object for controlling the on-screen depiction of<br />
<strong>OpenOffice</strong>.<strong>org</strong> (for example, FullScreen, FunctionBarVisible, Height, Width, Top,<br />
Visible) are no longer used.<br />
Note – Whereas the active document in Word is accessed through<br />
Application.ActiveDocument and in Excel through Application.ActiveWorkbook, in<br />
<strong>OpenOffice</strong>.<strong>org</strong>, the StarDesktop is responsible for this task. The active document<br />
object is accessed in <strong>OpenOffice</strong>.<strong>org</strong> through the StarDesktop.CurrentComponent<br />
property, or through ThisComponent.<br />
ThisComponent<br />
The global name ThisComponent generally returns the same object as<br />
StarDesktop.CurrentComponent, with one significant advantage. If you are running<br />
from within the Basic IDE, debugging or exploring, then StarDesktop returns the<br />
Basic IDE itself. This is probably not what you want. ThisComponent returns the last<br />
previously active document.<br />
90 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Basic Information about Documents in <strong>OpenOffice</strong>.<strong>org</strong><br />
Basic Information about Documents in<br />
<strong>OpenOffice</strong>.<strong>org</strong><br />
When working with <strong>OpenOffice</strong>.<strong>org</strong> documents, it is useful to deal with some of the<br />
basic issues of document administration in <strong>OpenOffice</strong>.<strong>org</strong>. This includes the way in<br />
which file names are structured for <strong>OpenOffice</strong>.<strong>org</strong> documents, as well as the format<br />
in which files are saved.<br />
File Names in URL Notation<br />
Since <strong>OpenOffice</strong>.<strong>org</strong> is a platform-independent application, it uses URL notation<br />
(which is independent of any operating system), as defined in the Internet Standard<br />
RFC 1738 for file names. Standard file names using this system begin with the prefix<br />
file:/// followed by the local path. If the file name contains sub-directories, then<br />
these are separated by a single forward slash, not with a backslash usually used<br />
under Windows. The following path references the test.odt file in the doc directory<br />
on the C: drive.<br />
file:///C:/doc/test.odt<br />
To convert local file names into an URL, <strong>OpenOffice</strong>.<strong>org</strong> provides the ConvertToUrl<br />
function. To convert a URL into a local file name, <strong>OpenOffice</strong>.<strong>org</strong> provides the<br />
ConvertFromUrl function:<br />
MsgBox ConvertToUrl("C:\doc\test.odt")<br />
' supplies file:///C:/doc/test.odt<br />
MsgBox ConvertFromUrl("file:///C:/doc/test.odt")<br />
' supplies (under Windows) c:\doc\test.odt<br />
The example converts a local file name into a URL and displays it in a message box.<br />
It then converts a URL into a local file name and also displays this.<br />
The Internet Standard RFC 1738, upon which this is based, permits use of the 0-9,<br />
a-z, and A-Z characters. All other characters are inserted as escape coding in the<br />
URLs. To do this, they are converted into their hexadecimal value in the ISO 8859-1<br />
(ISO-Latin) set of characters and are preceded by a percent sign. A space in a local<br />
file name therefore, for example, becomes a %20 in the URL.<br />
XML File Format<br />
<strong>OpenOffice</strong>.<strong>org</strong> documents are based on the XML file format. XML-based files can be<br />
opened and edited with other programs.<br />
Chapter 5 · Working with <strong>OpenOffice</strong>.<strong>org</strong> Documents 91
Basic Information about Documents in <strong>OpenOffice</strong>.<strong>org</strong><br />
Compression of Files<br />
Since XML is based on standard text files, the resultant files are usually very large.<br />
<strong>OpenOffice</strong>.<strong>org</strong> therefore compresses the files and saves them as a ZIP file. By<br />
means of a storeAsURL method option, the user can save the original XML files<br />
directly. See storeAsURL Method Options, below.<br />
Creating, Opening and Importing<br />
Documents<br />
Documents are opened, imported and created using the method<br />
StarDesktop.loadComponentFromURL(URL, Frame, SearchFlags, FileProperties)<br />
The first parameter of loadComponentFromURL specifies the URL of the associated file.<br />
As the second parameter, loadComponentFromURL expects a name for the frame<br />
object of the window that <strong>OpenOffice</strong>.<strong>org</strong> creates internally for its administration. The<br />
predefined _blank name is usually specified here, and this ensures that<br />
<strong>OpenOffice</strong>.<strong>org</strong> creates a new window. Alternatively, _hidden can also be specified,<br />
and this ensures that the corresponding document is loaded but remains invisible.<br />
Using these parameters, the user can open a <strong>OpenOffice</strong>.<strong>org</strong> document, since place<br />
holders (dummy values) can be assigned to the last two parameters:<br />
Dim Doc As Object<br />
Dim Url As String<br />
Dim Dummy() 'An (empty) array of PropertyValues<br />
Url = "file:///C:/test.odt"<br />
Doc = StarDesktop.loadComponentFromURL(Url, "_blank", 0, Dummy)<br />
The preceding call opens the text.odt file and displays this in a new window.<br />
Any number of documents can be opened in this way in <strong>OpenOffice</strong>.<strong>org</strong> Basic and<br />
then edited using the returned document objects.<br />
Note – StarDesktop.loadComponentFromURL supersedes the Documents.Add and<br />
Documents.Open methods from the old <strong>OpenOffice</strong>.<strong>org</strong> API.<br />
92 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Creating, Opening and Importing Documents<br />
Replacing the Content of the Document Window<br />
The named _blank and _hidden values for the Frame parameter ensure that<br />
<strong>OpenOffice</strong>.<strong>org</strong> creates a new window for every call from loadComponentFromURL. In<br />
some situations, it is useful to replace the content of an existing window. In this case,<br />
the frame object of the window should contain an explicit name. Note that this name<br />
must not begin with an underscore. Furthermore, the SearchFlags parameter must be<br />
set so that the corresponding framework is created, if it does not already exist. The<br />
corresponding constant for SearchFlags is:<br />
SearchFlags = com.sun.star.frame.FrameSearchFlag.CREATE + _<br />
com.sun.star.frame.FrameSearchFlag.ALL<br />
The following example shows how the content of an opened window can be replaced<br />
with the help of the frame parameter and SearchFlags:<br />
Dim Doc As Object<br />
Dim Dummy()<br />
Dim Url As String<br />
Dim SearchFlags As Long<br />
SearchFlags = com.sun.star.frame.FrameSearchFlag.CREATE + _<br />
com.sun.star.frame.FrameSearchFlag.ALL<br />
Url = "file:///C:/test.odt"<br />
Doc = StarDesktop.loadComponentFromURL(Url, "MyFrame", SearchFlags, Dummy)<br />
MsgBox "Press OK to display the second document."<br />
Url = "file:///C:/test2.odt"<br />
Doc = StarDesktop.loadComponentFromURL(Url, "MyFrame", _<br />
SearchFlags, Dummy)<br />
The example first opens the test.odt file in a new window with the frame name of<br />
MyFrame. Once the message box has been confirmed, it replaces the content of the<br />
window with the test2.odt file.<br />
loadComponentFromURL Method Options<br />
The fourth parameter of the loadComponentFromURL function is a PropertyValue data<br />
field. which provides <strong>OpenOffice</strong>.<strong>org</strong> with various options for opening and creating<br />
documents. The data field must provide a PropertyValue structure for each option in<br />
which the name of the option is saved as a string as well as the associated value.<br />
loadComponentFromURL supports the following options:<br />
AsTemplate (Boolean)<br />
if true, loads a new, untitled document from the given URL. If is false, template<br />
files are loaded for editing.<br />
Chapter 5 · Working with <strong>OpenOffice</strong>.<strong>org</strong> Documents 93
Creating, Opening and Importing Documents<br />
CharacterSet (String)<br />
defines which set of characters a document is based on.<br />
FilterName (String)<br />
specifies a special filter for the loadComponentFromURL function. The filter names<br />
available are defined in the<br />
\share\config\registry\instance\<strong>org</strong>\openoffice\office\TypeDetection.xm<br />
l file.<br />
FilterOptions (String)<br />
defines additional options for filters.<br />
JumpMark (String)<br />
once a document has been opened, jumps to the position defined in JumpMark.<br />
Password (String)<br />
transfers a password for a protected file.<br />
ReadOnly (Boolean)<br />
loads a read-only document.<br />
The following example shows how a text file separated by a comma in<br />
<strong>OpenOffice</strong>.<strong>org</strong> Calc can be opened using the FilterName option.<br />
Dim Doc As Object<br />
Dim FileProperties(1) As New com.sun.star.beans.PropertyValue<br />
Dim Url As String<br />
Url = "file:///C:/doc.csv"<br />
FileProperties(0).Name = "FilterName"<br />
FileProperties(0).Value ="Text - txt - csv (StarCalc)"<br />
FileProperties(1).Name = "FilterOptions"<br />
FileProperties(1).value = "44,34,0,1"<br />
Doc = StarDesktop.loadComponentFromURL(Url, "_blank", 0, FileProperties())<br />
The FileProperties data field covers precisely one value because it records one<br />
option. The Filtername property defines whether <strong>OpenOffice</strong>.<strong>org</strong> uses a<br />
<strong>OpenOffice</strong>.<strong>org</strong> Calc text filter to open files.<br />
Creating New Documents<br />
<strong>OpenOffice</strong>.<strong>org</strong> automatically creates a new document if the document specified in<br />
the URL is a template.<br />
Alternatively, if only an empty document without any adaptation is needed, a<br />
94 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
private:factory URL can be specified:<br />
Dim Dummy()<br />
Dim Url As String<br />
Dim Doc As Object<br />
Creating, Opening and Importing Documents<br />
Url = "private:factory/swriter"<br />
Doc = StarDesktop.loadComponentFromURL(Url, "_blank", 0, Dummy())<br />
The call creates an empty <strong>OpenOffice</strong>.<strong>org</strong> writer document.<br />
Document Objects<br />
The loadComponentFromURL function introduced in the previous section returns a<br />
document object. This supports the com.sun.star.document.OfficeDocument service,<br />
which in turn provides two central interfaces:<br />
The com.sun.star.frame.XStorable interface, which is responsible for saving<br />
documents.<br />
The com.sun.star.view.XPrintable interface, which contains the methods for<br />
printing documents.<br />
Saving and Exporting Documents<br />
<strong>OpenOffice</strong>.<strong>org</strong> documents are saved directly through the document object. The<br />
store method of the com.sun.star.frame.XStorable interface is available for this<br />
purpose:<br />
Doc.store()<br />
This call functions provided that the document has already been assigned a memory<br />
space. This is not the case for new documents. In this instance, the storeAsURL<br />
method is used. This method is also defined in com.sun.star.frame.XStorable and can<br />
be used to define the location of the document:<br />
Dim URL As String<br />
Dim Dummy()<br />
Url = "file:///C:/test3.odt"<br />
Doc.storeAsURL(URL, Dummy())<br />
In addition to the preceding methods, com.sun.star.frame.XStorable also provides<br />
some help methods which are useful when saving documents. These are:<br />
Chapter 5 · Working with <strong>OpenOffice</strong>.<strong>org</strong> Documents 95
Document Objects<br />
hasLocation()<br />
specifies whether the document has already been assigned a URL.<br />
isReadonly()<br />
specifies whether a document has read-only protection.<br />
isModified()<br />
specifies whether a document has been modified since it was last saved.<br />
The code for saving a document can be extended by these options so that the<br />
document is only saved if the object has actually been modified and the file name is<br />
only queried if it is actually needed:<br />
If (Doc.isModified) Then<br />
If (Doc.hasLocation And (Not Doc.isReadOnly)) Then<br />
Doc.store()<br />
Else<br />
Doc.storeAsURL(URL, Dummy())<br />
End If<br />
End If<br />
The example first checks whether the relevant document has been modified since it<br />
was last saved. It only continues with the saving process if this is the case. If the<br />
document has already been assigned a URL and is not a read-only document, it is<br />
saved under the existing URL. If it does not have a URL or was opened in its readonly<br />
status, it is saved under a new URL.<br />
storeAsURL Method Options<br />
As with the loadComponentFromURL method, some options can also be specified in the<br />
form of a PropertyValue data field using the storeAsURL method. These determine<br />
the procedure <strong>OpenOffice</strong>.<strong>org</strong> uses when saving a document. storeAsURL provides<br />
the following options:<br />
CharacterSet (String)<br />
defines which set of characters a document is based on.<br />
FilterName (String)<br />
specifies a special filter for the loadComponentFromURL function. The filter names<br />
available are defined in the<br />
\share\config\registry\instance\<strong>org</strong>\openoffice\office\TypeDetection.xm<br />
l file.<br />
FilterOptions (String)<br />
defines additional options for filters.<br />
96 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Overwrite (Boolean)<br />
allows a file which already exists to be overwritten without a query.<br />
Password (String)<br />
transfers the password for a protected file.<br />
Unpacked (Boolean)<br />
saves the document (not compressed) in sub-directories.<br />
Document Objects<br />
The following example shows how the Overwrite option can be used in conjunction<br />
with storeAsURL:<br />
Dim Doc As Object<br />
Dim FileProperties(0) As New com.sun.star.beans.PropertyValue<br />
Dim Url As String<br />
' ... Initialize Doc<br />
Url = "file:///c:/test3.odt"<br />
FileProperties(0).Name = "Overwrite"<br />
FileProperties(0).Value = True<br />
Doc.storeAsURL(Url, FileProperties())<br />
The example then saves Doc under the specified file name if a file already exists<br />
under the name.<br />
Printing Documents<br />
Similar to saving, documents are printed out directly by means of the document<br />
object. The Print method of the com.sun.star.view.Xprintable interface is provided for<br />
this purpose. In its simplest form, the print call is:<br />
Dim Dummy()<br />
Doc.print(Dummy())<br />
As in the case of the loadComponentFromURL method, the Dummy parameter is a<br />
PropertyValue data field through which <strong>OpenOffice</strong>.<strong>org</strong> can specify several options<br />
for printing.<br />
The options of the print method<br />
The print method expects a PropertyValue data field as a parameter, which reflects<br />
the settings of the print dialog of <strong>OpenOffice</strong>.<strong>org</strong>:<br />
Chapter 5 · Working with <strong>OpenOffice</strong>.<strong>org</strong> Documents 97
Document Objects<br />
CopyCount (Integer)<br />
specifies the number of copies to be printed.<br />
FileName (String)<br />
prints the document in the specified file.<br />
Collate (Boolean)<br />
advises the printer to collate the pages of the copies.<br />
Sort (Boolean)<br />
sorts the pages when printing out several copies (CopyCount > 1).<br />
Pages (String)<br />
contains the list of the pages to be printed (syntax as specified in print dialog).<br />
The following example shows how several pages of a document can be printed out<br />
using the Pages option:<br />
Dim Doc As Object<br />
Dim PrintProperties(0) As New com.sun.star.beans.PropertyValue<br />
PrintProperties(0).Name="Pages"<br />
PrintProperties(0).Value="1-3; 7; 9"<br />
Doc.print(PrintProperties())<br />
Printer selection and settings<br />
The com.sun.star.view.XPrintable interface provides the Printer property, which<br />
selects the printer. This property receives a PropertyValue data field with the<br />
following settings:<br />
Name (String)<br />
specifies the name of printer.<br />
PaperOrientation (Enum)<br />
specifies the paper orientation (com.sun.star.view.PaperOrientation.PORTRAIT<br />
value for portrait format, com.sun.star.view.PaperOrientation.LANDSCAPE for<br />
landscape format).<br />
PaperFormat (Enum)<br />
specifies the paper format (for example, com.sun.star.view.PaperFormat.A4 for<br />
DIN A4 or com.sun.star.view.PaperFormat.Letter for US letters).<br />
PaperSize (Size)<br />
specifies the paper size in hundredths of a millimeter.<br />
98 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Templates<br />
Document Objects<br />
The following example shows how a printer can be changed and the paper size set<br />
with the help of the Printer property.<br />
Dim Doc As Object<br />
Dim PrinterProperties(1) As New com.sun.star.beans.PropertyValue<br />
Dim PaperSize As New com.sun.star.awt.Size<br />
PaperSize.Width = 20000 ' corresponds to 20 cm<br />
PaperSize.Height = 20000 ' corresponds to 20 cm<br />
PrinterProperties (0).Name="Name"<br />
PrinterProperties (0).Value="My HP Laserjet"<br />
PrinterProperties (1).Name="PaperSize"<br />
PrinterProperties (1).Value=PaperSize<br />
Doc.Printer = PrinterProperties()<br />
The example defines an object named PaperSize with the com.sun.star.awt.Size<br />
type. This is needed to specify the paper size. Furthermore, it creates a data field for<br />
two PropertyValue entries named PrinterProperties. This data field is then<br />
initialized with the values to be set and assigned the Printer property. From the<br />
standpoint of UNO, the printer is not a real property but an imitated one.<br />
Templates are named lists containing formatting attributes. They move through all<br />
applications of <strong>OpenOffice</strong>.<strong>org</strong> and help to significantly simplify formatting. If the user<br />
changes one of the attributes of a template, then <strong>OpenOffice</strong>.<strong>org</strong> automatically<br />
adjusts all document sections depending on the attribute. The user can therefore, for<br />
example, change the font type of all level one headers by means of a central<br />
modification in the document. Depending on the relevant document types,<br />
<strong>OpenOffice</strong>.<strong>org</strong> recognizes a whole range of different types of template.<br />
<strong>OpenOffice</strong>.<strong>org</strong> Writer supports the following templates:<br />
Character templates<br />
Paragraph templates<br />
Frame templates<br />
Page templates<br />
Numbering templates<br />
<strong>OpenOffice</strong>.<strong>org</strong> Calc supports the following templates:<br />
Cell template<br />
Page templates<br />
<strong>OpenOffice</strong>.<strong>org</strong> Impress supports the following templates:<br />
Character element templates<br />
Chapter 5 · Working with <strong>OpenOffice</strong>.<strong>org</strong> Documents 99
Document Objects<br />
Presentation templates<br />
In <strong>OpenOffice</strong>.<strong>org</strong> terminology, the different types of templates are called<br />
StyleFamilies in accordance with the com.sun.star.style.StyleFamily service on<br />
which they are based. The StyleFamilies are accessed by means of the document<br />
object:<br />
Dim Doc As Object<br />
Dim Sheet As Object<br />
Dim StyleFamilies As Object<br />
Dim CellStyles As Object<br />
Doc = StarDesktop.CurrentComponent<br />
StyleFamilies = Doc.StyleFamilies<br />
CellStyles = StyleFamilies.getByName("CellStyles")<br />
The example uses the StyleFamilies property of a spreadsheet document to<br />
establish a list containing all available cell templates.<br />
The individual templates can be accessed directly by means of an index:<br />
Dim Doc As Object<br />
Dim Sheet As Object<br />
Dim StyleFamilies As Object<br />
Dim CellStyles As Object<br />
Dim CellStyle As Object<br />
Dim I As Integer<br />
Doc = StarDesktop.CurrentComponent<br />
StyleFamilies = Doc.StyleFamilies<br />
CellStyles = StyleFamilies.getByName("CellStyles")<br />
For I = 0 To CellStyles.Count - 1<br />
CellStyle = CellStyles(I)<br />
MsgBox CellStyle.Name<br />
Next I<br />
The loop added since the previous example displays the names of all cell templates<br />
one after another in a message box.<br />
Details about various formatting<br />
options<br />
Each type of template provides a whole range of individual formatting properties.<br />
Here is an overview of the most important formatting properties and the points at<br />
which they are explained:<br />
Character properties, com.sun.star.style.CharacterProperties service<br />
100 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Paragraph properties, com.sun.star.text.Paragraph service<br />
Cell properties, com.sun.star.table.CellProperties service<br />
Page properties, com.sun.star.style.PageProperties service<br />
Character element properties, Various services<br />
Details about various formatting options<br />
The format properties are by no means restricted to the applications in which these<br />
are explained, but instead can be used universally. For example, most of the page<br />
properties described in Spreadsheets can therefore be used not only in<br />
<strong>OpenOffice</strong>.<strong>org</strong> Calc, but also in <strong>OpenOffice</strong>.<strong>org</strong> Writer.<br />
More information about working with templates can be found in the Default values for<br />
character and paragraph properties section in Text Documents.<br />
Chapter 5 · Working with <strong>OpenOffice</strong>.<strong>org</strong> Documents 101
6<br />
C H A P T E R 6<br />
6 Text Documents<br />
In addition to pure strings, text documents also contain formatting information. These<br />
may appear at any point in the text. The structure is further complicated by tables.<br />
These include not only single-dimensional strings, but also two-dimensional fields.<br />
Most word processing programs now finally provide the option of placing drawing<br />
objects, text frames and other objects within a text. These may be outside the flow of<br />
text and can be positioned anywhere on the page.<br />
This chapter presents the central interfaces and services of text documents.<br />
The Structure of Text Documents<br />
Editing Text Documents<br />
More than Just Text<br />
The first section deals with the anatomy of text documents and concentrates on how<br />
a <strong>OpenOffice</strong>.<strong>org</strong> Basic program can be used to take iterative steps through a<br />
<strong>OpenOffice</strong>.<strong>org</strong> document. It focuses on paragraphs, paragraph portions and their<br />
formatting.<br />
The second section focuses on efficiently working with text documents. For this<br />
purpose, <strong>OpenOffice</strong>.<strong>org</strong> provides several help objects, such as the TextCursor<br />
object, which extend beyond those specified in the first section.<br />
The third section moves beyond work with texts. It concentrates on tables, text<br />
frames, text fields, bookmarks, content directories and more.<br />
Information about how to create, open, save and print documents is described in<br />
Working with Documents, because it can be used not only for text documents, but<br />
also for other types of documents.<br />
103
Text Documents<br />
The Structure of Text Documents<br />
A text document can essentially contain four types of information:<br />
The actual text<br />
Templates for formatting characters, paragraphs, and pages<br />
Non-text elements such as tables, graphics and drawing objects<br />
Global settings for the text document<br />
This section concentrates on the text and associated formatting options.<br />
Paragraphs and Paragraph Portions<br />
The core of a text document consists of a sequence of paragraphs. These are neither<br />
named nor indexed and there is therefore no possible way of directly accessing<br />
individual paragraphs. The paragraphs can however be sequentially traversed with<br />
the help of the Enumeration object described in Introduction to the API. This allows<br />
the paragraphs to be edited.<br />
When working with the Enumeration object, one special scenario should, however, be<br />
noted: it not only returns paragraphs, but also tables (strictly speaking, in<br />
<strong>OpenOffice</strong>.<strong>org</strong> Writer, a table is a special type of paragraph). Before accessing a<br />
returned object, you should therefore check whether the returned object supports the<br />
com.sun.star.text.Paragraph service for paragraphs or the<br />
com.sun.star.text.TextTable service for tables.<br />
The following example traverses the contents of a text document in a loop and uses a<br />
message in each instance to inform the user whether the object in question is a<br />
paragraph or table.<br />
Dim Doc As Object<br />
Dim Enum As Object<br />
Dim TextElement As Object<br />
' Create document object<br />
Doc = StarDesktop.CurrentComponent<br />
' Create enumeration object<br />
Enum = Doc.Text.createEnumeration<br />
' loop over all text elements<br />
104 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
While Enum.hasMoreElements<br />
TextElement = Enum.nextElement<br />
Paragraphs and Paragraph Portions<br />
If TextElement.supportsService("com.sun.star.text.TextTable") Then<br />
MsgBox "The current block contains a table."<br />
End If<br />
If TextElement.supportsService("com.sun.star.text.Paragraph") Then<br />
MsgBox "The current block contains a paragraph."<br />
End If<br />
Wend<br />
The example creates a Doc document object which references the current<br />
<strong>OpenOffice</strong>.<strong>org</strong> document. With the aid of Doc, the example then creates an<br />
Enumeration object that traverses through the individual parts of the text (paragraphs<br />
and tables) and assigns the current element to TextElement object. The example<br />
uses the supportsService method to check whether the TextElement is a paragraph<br />
or a table.<br />
Paragraphs<br />
The com.sun.star.text.Paragraph service grants access to the content of a paragraph.<br />
The text in the paragraph can be retrieved and modified using the String property:<br />
Dim Doc As Object<br />
Dim Enum As Object<br />
Dim TextElement As Object<br />
Doc = StarDesktop.CurrentComponent<br />
Enum = Doc.Text.createEnumeration<br />
While Enum.hasMoreElements<br />
TextElement = Enum.nextElement<br />
If TextElement.supportsService("com.sun.star.text.Paragraph") Then<br />
TextElement.String = Replace(TextElement.String, "you", "U")<br />
TextElement.String = Replace(TextElement.String, "too", "2")<br />
TextElement.String = Replace(TextElement.String, "for", "4")<br />
End If<br />
Wend<br />
The example opens the current text document and passes through it with the help of<br />
the Enumeration object. It uses the TextElement.String property in all paragraphs to<br />
access the relevant paragraphs and replaces the you, too and for strings with the<br />
U, 2 and 4 characters. The Replace function used for replacing does not fall within<br />
the standard linguistic scope of <strong>OpenOffice</strong>.<strong>org</strong> Basic. This is an instance of the<br />
example function described in Search and Replace.<br />
Chapter 6 · Text Documents 105
Paragraphs and Paragraph Portions<br />
Note – The content of the procedure described here for accessing the paragraphs<br />
of a text is comparable with the Paragraphs listing used in VBA, which is provided in<br />
the Range and Document objects available there. Whereas in VBA the paragraphs are<br />
accessed by their number (for example, by the Paragraph(1) call), in <strong>OpenOffice</strong>.<strong>org</strong><br />
Basic, the Enumeration object described previously should be used.<br />
There is no direct counterpart in <strong>OpenOffice</strong>.<strong>org</strong> Basic for the Characters,<br />
Sentences and Words lists provided in VBA. You do, however, have the option of<br />
switching to a TextCursor which allows for navigation at the level of characters,<br />
sentences and words.<br />
Paragraph Portions<br />
The previous example may change the text as requested, but it may sometimes also<br />
destroy the formatting.<br />
This is because a paragraph in turn consists of individual sub-objects. Each of these<br />
sub-objects contains its own formatting information. If the center of a paragraph, for<br />
example, contains a word printed in bold, then it will be represented in<br />
<strong>OpenOffice</strong>.<strong>org</strong> by three paragraph portions: the portion before the bold type, then<br />
the word in bold, and finally the portion after the bold type, which is again depicted as<br />
normal.<br />
If the text of the paragraph is now changed using the paragraph's String property,<br />
then <strong>OpenOffice</strong>.<strong>org</strong> first deletes the old paragraph portions and inserts a new<br />
paragraph portion. The formatting of the previous sections is then lost.<br />
To prevent this effect, the user can access the associated paragraph portions rather<br />
than the entire paragraph. Paragraphs provide their own Enumeration object for this<br />
purpose. The following example shows a double loop which passes over all<br />
paragraphs of a text document and the paragraph portions they contain and applies<br />
the replacement processes from the previous example:<br />
Dim Doc As Object<br />
Dim Enum1 As Object<br />
Dim Enum2 As Object<br />
Dim TextElement As Object<br />
Dim TextPortion As Object<br />
Doc = StarDesktop.CurrentComponent<br />
Enum1 = Doc.Text.createEnumeration<br />
' loop over all paragraphs<br />
While Enum1.hasMoreElements<br />
TextElement = Enum1.nextElement<br />
106 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Paragraphs and Paragraph Portions<br />
If TextElement.supportsService("com.sun.star.text.Paragraph") Then<br />
Enum2 = TextElement.createEnumeration<br />
' loop over all sub-paragraphs<br />
While Enum2.hasMoreElements<br />
TextPortion = Enum2.nextElement<br />
MsgBox "'" & TextPortion.String & "'"<br />
TextPortion.String = Replace(TextPortion.String, "you", "U")<br />
TextPortion.String = Replace(TextPortion.String, "too", "2")<br />
TextPortion.String = Replace(TextPortion.String, "for", "4")<br />
Wend<br />
End If<br />
Wend<br />
The example runs through a text document in a double loop. The outer loop refers to<br />
the paragraphs of the text. The inner loop processes the paragraph portions in these<br />
paragraphs. The example code modifies the content in each of these paragraph<br />
portions using the String property of the string. as is the case in the previous<br />
example for paragraphs. Since however, the paragraph portions are edited directly,<br />
their formatting information is retained when replacing the string.<br />
Formatting<br />
There are various ways of formatting text. The easiest way is to assign the format<br />
properties directly to the text sequence. This is called direct formatting. Direct<br />
formatting is used in particular with short documents because the formats can be<br />
assigned by the user with the mouse. You can, for example, highlight a certain word<br />
within a text using bold type or center a line.<br />
In addition to direct formatting, you can also format text using templates. This is<br />
called indirect formatting. With indirect formatting, the user assigns a pre-defined<br />
template to the relevant text portion. If the layout of the text is changed at a later date,<br />
the user only needs to change the template. <strong>OpenOffice</strong>.<strong>org</strong> then changes the way in<br />
which all text portions which use this template are depicted.<br />
Note – In VBA, the formatting properties of an object are usually spread over a<br />
range of sub-objects (for example, Range.Font, Range.Borders, Range.Shading,<br />
Range.ParagraphFormat). The properties are accessed by means of cascading<br />
expressions (for example, Range.Font.AllCaps). In <strong>OpenOffice</strong>.<strong>org</strong> Basic, the<br />
formatting properties on the other hand are available directly, using the relevant<br />
objects (TextCursor, Paragraph, and so on). You will find an overview of the<br />
character and paragraph properties available in <strong>OpenOffice</strong>.<strong>org</strong> in the following two<br />
sections.<br />
Chapter 6 · Text Documents 107
Paragraphs and Paragraph Portions<br />
Note – The formatting properties can be found in each object (Paragraph,<br />
TextCursor, and so on) and can be applied directly.<br />
Character Properties<br />
Those format properties that refer to individual characters are described as character<br />
properties. These include bold type and the font type. Objects that allow character<br />
properties to be set have to support the com.sun.star.style.CharacterProperties<br />
service. <strong>OpenOffice</strong>.<strong>org</strong> recognizes a whole range of services that support this<br />
service. These include the previously described com.sun.star.text.Paragraph services<br />
for paragraphs as well as the com.sun.star.text.TextPortion services for paragraph<br />
portions.<br />
The com.sun.star.style.CharacterProperties service does not provide any interfaces,<br />
but instead offers a range of properties through which character properties can be<br />
defined and called. A complete list of all character properties can be found in the<br />
<strong>OpenOffice</strong>.<strong>org</strong> API reference. The following list describes the most important<br />
properties:<br />
CharFontName (String)<br />
name of font type selected.<br />
CharColor (Long)<br />
text color.<br />
CharHeight (Float)<br />
character height in points (pt).<br />
CharUnderline (Constant group)<br />
type of underscore (constants in accordance with<br />
com.sun.star.awt.FontUnderline).<br />
CharWeight (Constant group)<br />
font weight (constants in accordance with com.sun.star.awt.FontWeight).<br />
CharBackColor (Long)<br />
background color.<br />
CharKeepTogether (Boolean)<br />
suppression of automatic line break.<br />
108 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
CharStyleName (String)<br />
name of character template.<br />
Paragraph Properties<br />
Paragraphs and Paragraph Portions<br />
Formatting information that does not refer to individual characters, but to the entire<br />
paragraph is considered to be a paragraph property. This includes the distance of the<br />
paragraph from the edge of the page as well as line spacing. The paragraph<br />
properties are available through the com.sun.star.style.ParagraphProperties service.<br />
Even the paragraph properties are available in various objects. All objects that<br />
support the com.sun.star.text.Paragraph service also provide support for the<br />
paragraph properties in com.sun.star.style.ParagraphProperties.<br />
A complete list of the paragraph properties can be found in the <strong>OpenOffice</strong>.<strong>org</strong> API<br />
reference. The most common paragraph properties are:<br />
ParaAdjust (enum)<br />
vertical text orientation (constants in accordance with<br />
com.sun.star.style.ParagraphAdjust).<br />
ParaLineSpacing (struct)<br />
line spacing (structure in accordance with com.sun.star.style.LineSpacing).<br />
ParaBackColor (Long)<br />
background color.<br />
ParaLeftMargin (Long)<br />
left margin in 100ths of a millimeter.<br />
ParaRightMargin (Long)<br />
right margin in 100ths of a millimeter.<br />
ParaTopMargin (Long)<br />
top margin in 100ths of a millimeter.<br />
ParaBottomMargin (Long)<br />
bottom margin in 100ths of a millimeter.<br />
ParaTabStops (Array of struct)<br />
type and position of tabs (array with structures of the type<br />
com.sun.star.style.TabStop).<br />
Chapter 6 · Text Documents 109
Paragraphs and Paragraph Portions<br />
ParaStyleName (String)<br />
name of the paragraph template.<br />
Example: simple HTML export<br />
The following example demonstrates how to work with formatting information. It<br />
iterates through a text document and creates a simple HTML file. Each paragraph is<br />
recorded in its own HTML element for this purpose. Paragraph portions displayed<br />
in bold type are marked using a HTML element when exporting.<br />
Dim FileNo As Integer, Filename As String, CurLine As String<br />
Dim Doc As Object<br />
Dim Enum1 As Object, Enum2 As Object<br />
Dim TextElement As Object, TextPortion As Object<br />
Filename = "c:\text.html"<br />
FileNo = Freefile<br />
Open Filename For Output As #FileNo<br />
Print #FileNo, ""<br />
Doc = StarDesktop.CurrentComponent<br />
Enum1 = Doc.Text.createEnumeration<br />
' loop over all paragraphs<br />
While Enum1.hasMoreElements<br />
TextElement = Enum1.nextElement<br />
If TextElement.supportsService("com.sun.star.text.Paragraph") Then<br />
Enum2 = TextElement.createEnumeration<br />
CurLine = ""<br />
' loop over all paragraph portions<br />
While Enum2.hasMoreElements<br />
TextPortion = Enum2.nextElement<br />
If TextPortion.CharWeight = com.sun.star.awt.FontWeight.BOLD THEN<br />
CurLine = CurLine & "" & TextPortion.String & ""<br />
Else<br />
CurLine = CurLine & TextPortion.String<br />
End If<br />
Wend<br />
' output the line<br />
CurLine = CurLine & ""<br />
Print #FileNo, CurLine<br />
End If<br />
Wend<br />
' write HTML footer<br />
Print #FileNo, ""<br />
Close #FileNo<br />
110 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Paragraphs and Paragraph Portions<br />
The basic structure of the example is oriented towards the examples for running<br />
though the paragraph portions of a text already discussed previously. The functions<br />
for writing the HTML file, as well as a test code that checks the font weight of the<br />
corresponding text portions and provides paragraph portions in bold type with a<br />
corresponding HTML tag, have been added.<br />
Default values for character and paragraph<br />
properties<br />
Direct formatting always takes priority over indirect formatting. In other words,<br />
formatting using templates is assigned a lower priority than direct formatting in a text.<br />
Establishing whether a section of a document has been directly or indirectly formatted<br />
is not easy. The symbol bars provided by <strong>OpenOffice</strong>.<strong>org</strong> show the common text<br />
properties such as font type, weight and size. However, whether the corresponding<br />
settings are based on template or direct formatting in the text is still unclear.<br />
<strong>OpenOffice</strong>.<strong>org</strong> Basic provides the getPropertyState method, with which<br />
programmers can check how a certain property was formatted. As a parameter, this<br />
takes the name of the property and returns a constant that provides information about<br />
the origin of the formatting. The following responses, which are defined in the<br />
com.sun.star.beans.PropertyState enumeration, are possible:<br />
com.sun.star.beans.PropertyState.DIRECT_VALUE<br />
the property is defined directly in the text (direct formatting)<br />
com.sun.star.beans.PropertyState.DEFAULT_VALUE<br />
the property is defined by a template (indirect formatting)<br />
com.sun.star.beans.PropertyState.AMBIGUOUS_VALUE<br />
the property is unclear. This status arises, for example, when querying the bold<br />
type property of a paragraph, which includes both words depicted in bold and<br />
words depicted in normal font.<br />
The following example shows how format properties can be edited in <strong>OpenOffice</strong>.<strong>org</strong>.<br />
It searches through a text for paragraph portions which have been depicted as bold<br />
type using direct formatting. If it encounters a corresponding paragraph portion, it<br />
deletes the direct formatting using the setPropertyToDefault method and assigns a<br />
MyBold character template to the corresponding paragraph portion.<br />
Dim Doc As Object<br />
Dim Enum1 As Object<br />
Dim Enum2 As Object<br />
Dim TextElement As Object<br />
Dim TextPortion As Object<br />
Chapter 6 · Text Documents 111
Paragraphs and Paragraph Portions<br />
Doc = StarDesktop.CurrentComponent<br />
Enum1 = Doc.Text.createEnumeration<br />
' loop over all paragraphs<br />
While Enum1.hasMoreElements<br />
TextElement = Enum1.nextElement<br />
If TextElement.supportsService("com.sun.star.text.Paragraph") Then<br />
Enum2 = TextElement.createEnumeration<br />
' loop over all paragraph portions<br />
While Enum2.hasMoreElements<br />
TextPortion = Enum2.nextElement<br />
If TextPortion.CharWeight = _<br />
com.sun.star.awt.FontWeight.BOLD AND _<br />
TextPortion.getPropertyState("CharWeight") = _<br />
com.sun.star.beans.PropertyState.DIRECT_VALUE Then<br />
TextPortion.setPropertyToDefault("CharWeight")<br />
TextPortion.CharStyleName = "MyBold"<br />
End If<br />
Wend<br />
End If<br />
Wend<br />
Editing Text Documents<br />
The previous section has already discussed a whole range of options for editing text<br />
documents, focusing on the com.sun.star.text.TextPortion and<br />
com.sun.star.text.Paragraph services, which grant access to paragraph portions as<br />
well as paragraphs. These services are appropriate for applications in which the<br />
content of a text is to be edited in one pass through a loop. However, this is not<br />
sufficient for many problems. <strong>OpenOffice</strong>.<strong>org</strong> provides the<br />
com.sun.star.text.TextCursor service for more complicated tasks, including navigating<br />
backward within a document or navigating based on sentences and words rather than<br />
TextPortions.<br />
112 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
The TextCursor<br />
The TextCursor<br />
A TextCursor in the <strong>OpenOffice</strong>.<strong>org</strong> API is comparable with the visible cursor used in<br />
a <strong>OpenOffice</strong>.<strong>org</strong> document. It marks a certain point within a text document and can<br />
be navigated in various directions through the use of commands. The TextCursor<br />
objects available in <strong>OpenOffice</strong>.<strong>org</strong> Basic should not, however, be confused with the<br />
visible cursor. These are two very different things.<br />
Note – Terminology differs from that used in VBA: In terms of scope of function, the<br />
Range object from VBA can be compared with the TextCursor object in<br />
<strong>OpenOffice</strong>.<strong>org</strong> and not — as the name possibly suggests — with the Range object in<br />
<strong>OpenOffice</strong>.<strong>org</strong>.<br />
The TextCursor object in <strong>OpenOffice</strong>.<strong>org</strong>, for example, provides methods for<br />
navigating and changing text which are included in the Range object in VBA (for<br />
example, MoveStart, MoveEnd, InsertBefore, InsertAfter). The corresponding<br />
counterparts of the TextCursor object in <strong>OpenOffice</strong>.<strong>org</strong> are described in the following<br />
sections.<br />
Navigating within a Text<br />
The TextCursor object in <strong>OpenOffice</strong>.<strong>org</strong> Basic acts independently from the visible<br />
cursor in a text document. A program-controlled position change of a TextCursor<br />
object has no impact whatsoever on the visible cursor. Several TextCursor objects<br />
can even be opened for the same document and used in various positions, which are<br />
independent of one another.<br />
A TextCursor object is created using the createTextCursor call:<br />
Dim Doc As Object<br />
Dim Cursor As Object<br />
Doc = StarDesktop.CurrentComponent<br />
Cursor = Doc.Text.createTextCursor()<br />
The Cursor object created in this way supports the com.sun.star.text.TextCursor<br />
service, which in turn provides a whole range of methods for navigating within text<br />
documents. The following example first moves the TextCursor ten characters to the<br />
left and then three characters to the right:<br />
Cursor.goLeft(10, False)<br />
Cursor.goRight(3, False)<br />
A TextCursor can highlight a complete area. This can be compared with highlighting<br />
Chapter 6 · Text Documents 113
The TextCursor<br />
a point in the text using the mouse. The False parameter in the previous function call<br />
specifies whether the area passed over with the cursor movement is highlighted. For<br />
example, the TextCursor in the following example<br />
Cursor.goLeft(10, False)<br />
Cursor.goRight(3, True)<br />
first moves ten characters to the right without highlighting, and then moves back three<br />
characters and highlights this. The area highlighted by the TextCursor therefore<br />
begins after the seventh character in the text and ends after the tenth character.<br />
Here are the central methods that the com.sun.star.text.TextCursor service provides<br />
for navigation:<br />
goLeft (Count, Expand)<br />
jumps Count characters to the left.<br />
goRight (Count, Expand)<br />
jumps Count characters to the right.<br />
gotoStart (Expand)<br />
jumps to the start of the text document.<br />
gotoEnd (Expand)<br />
jumps to the end of the text document.<br />
gotoRange (TextRange, Expand)<br />
jumps to the specified TextRange-Object.<br />
gotoStartOfWord (Expand)<br />
jumps to the start of the current word.<br />
gotoEndOfWord (Expand)<br />
jumps to the end of the current word.<br />
gotoNextWord (Expand)<br />
jumps to the start of the next word.<br />
gotoPreviousWord (Expand)<br />
jumps to the start of the previous word.<br />
isStartOfWord ()<br />
returns True if the TextCursor is at the start of a word.<br />
isEndOfWord ()<br />
returns True if the TextCursor is at the end of a word.<br />
114 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
gotoStartOfSentence (Expand)<br />
jumps to the start of the current sentence.<br />
gotoEndOfSentence (Expand)<br />
jumps to the end of the current sentence.<br />
gotoNextSentence (Expand)<br />
jumps to the start of the next sentence.<br />
gotoPreviousSentence (Expand)<br />
jumps to the start of the previous sentence.<br />
isStartOfSentence ()<br />
returns True if the TextCursor is at the start of a sentence.<br />
isEndOfSentence ()<br />
returns True if the TextCursor is at the end of a sentence.<br />
gotoStartOfParagraph (Expand)<br />
jumps to the start of the current paragraph.<br />
gotoEndOfParagraph (Expand)<br />
jumps to the end of the current paragraph.<br />
gotoNextParagraph (Expand)<br />
jumps to the start of the next paragraph.<br />
gotoPreviousParagraph (Expand)<br />
jumps to the start of the previous paragraph.<br />
isStartOfParagraph ()<br />
returns True if the TextCursor is at the start of a paragraph.<br />
isEndOfParagraph ()<br />
returns True if the TextCursor is at the end of a paragraph.<br />
The TextCursor<br />
The text is divided into sentences on the basis of sentence symbols. Periods are, for<br />
example, interpreted as symbols indicating the end of sentences.<br />
The Expand parameter is a Boolean value which specifies whether the area passed<br />
over during navigation is to be highlighted. All navigation methods furthermore return<br />
a parameter which specifies whether the navigation was successful or whether the<br />
action was terminated for lack of text.<br />
The following is a list of several methods for editing highlighted areas using a<br />
Chapter 6 · Text Documents 115
The TextCursor<br />
TextCursor and which also support the com.sun.star.text.TextCursor service:<br />
collapseToStart ()<br />
resets the highlighting and positions the TextCursor at the start of the previously<br />
highlighted area.<br />
collapseToEnd ()<br />
resets the highlighting and positions the TextCursor at the end of the previously<br />
highlighted area.<br />
isCollapsed ()<br />
returns True if the TextCursor does not cover any highlighting at present.<br />
Formatting Text with TextCursor<br />
The com.sun.star.text.TextCursor service supports all the character and paragraph<br />
properties that were presented at the start of this chapter.<br />
The following example shows how these can be used in conjunction with a<br />
TextCursor. It passes through a complete document and formats the first word of<br />
every sentence in bold type.<br />
Dim Doc As Object<br />
Dim Cursor As Object<br />
Dim Proceed As Boolean<br />
Doc = StarDesktop.CurrentComponent<br />
Cursor = Doc.Text.createTextCursor<br />
Do<br />
Cursor.gotoEndOfWord(True)<br />
Cursor.CharWeight = com.sun.star.awt.FontWeight.BOLD<br />
Proceed = Cursor.gotoNextSentence(False)<br />
Cursor.gotoNextWord(False)<br />
Loop While Proceed<br />
The example first creates a document object for the text that has just been opened.<br />
Then it iterates through the entire text, sentence by sentence, and highlights each of<br />
the first words and formats this in bold.<br />
Retrieving and Modifying Text Contents<br />
If a TextCursor contains a highlighted area, then this text is available by means of the<br />
String property of the TextCursor object. The following example uses the String<br />
property to display the first words of a sentence in a message box:<br />
116 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Dim Doc As Object<br />
Dim Cursor As Object<br />
Dim Proceed As Boolean<br />
Doc = StarDesktop.CurrentComponent<br />
Cursor = Doc.Text.createTextCursor<br />
Do<br />
Cursor.gotoEndOfWord(True)<br />
MsgBox Cursor.String<br />
Proceed = Cursor.gotoNextSentence(False)<br />
Cursor.gotoNextWord(False)<br />
Loop While Proceed<br />
The TextCursor<br />
The first word of each sentence can be modified in the same way using the String<br />
property:<br />
Dim Doc As Object<br />
Dim Cursor As Object<br />
Dim Proceed As Boolean<br />
Doc = StarDesktop.CurrentComponent<br />
Cursor = Doc.Text.createTextCursor<br />
Do<br />
Cursor.gotoEndOfWord(True)<br />
Cursor.String = "Ups"<br />
Proceed = Cursor.gotoNextSentence(False)<br />
Cursor.gotoNextWord(False)<br />
Loop While Proceed<br />
If the TextCursor contains a highlighted area, an assignment to the String property<br />
replaces this with the new text. If there is no highlighted area, the text is inserted at<br />
the present TextCursor position.<br />
Inserting Control Codes<br />
In some situations, it is not the actual text of a document, but rather its structure that<br />
needs modifying. <strong>OpenOffice</strong>.<strong>org</strong> provides control codes for this purpose. These are<br />
inserted in the text and influence its structure. The control codes are defined in the<br />
com.sun.star.text.ControlCharacter group of constants. The following control codes<br />
are available in <strong>OpenOffice</strong>.<strong>org</strong>:<br />
PARAGRAPH_BREAK<br />
paragraph break.<br />
LINE_BREAK<br />
line break within a paragraph.<br />
Chapter 6 · Text Documents 117
The TextCursor<br />
SOFT_HYPHEN<br />
possible point for syllabification.<br />
HARD_HYPHEN<br />
obligatory point for syllabification.<br />
HARD_SPACE<br />
protected space that is not spread out or compressed in justified text.<br />
To insert the control codes, you need not only the cursor but also the associated text<br />
document objects. The following example inserts a paragraph after the 20th character<br />
of a text:<br />
Dim Doc As Object<br />
Dim Cursor As Object<br />
Dim Proceed As Boolean<br />
Doc = StarDesktop.CurrentComponent<br />
Cursor = Doc.Text.createTextCursor<br />
Cursor.goRight(20, False)<br />
Doc.Text.insertControlCharacter(Cursor, _<br />
com.sun.star.text.ControlCharacter.PARAGRAPH_BREAK, False)<br />
The False parameter in the call of the insertControlCharacter method ensures that<br />
the area currently highlighted by the TextCursor remains after the insert operation. If<br />
the True parameter is passed here, then insertControlCharacter replaces the<br />
current text.<br />
Searching for Text Portions<br />
In many instances, it is the case that a text is to be searched for a particular term and<br />
the corresponding point needs to be edited. All <strong>OpenOffice</strong>.<strong>org</strong> documents provide a<br />
special interface for this purpose, and this interface always functions in accordance<br />
with the same principle: Before a search process, what is commonly referred to as a<br />
SearchDescriptor must first be created. This defines what <strong>OpenOffice</strong>.<strong>org</strong> searches<br />
for in a document. A SearchDescriptor is an object which supports the<br />
com.sun.star.util. SearchDescriptor service and can be created by means of the<br />
createSearchDescriptor method of a document:<br />
Dim SearchDesc As Object<br />
SearchDesc = Doc.createSearchDescriptor<br />
Once the SearchDescriptor has been created, it receives the text to be searched for:<br />
SearchDesc.searchString="any text"<br />
118 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Searching for Text Portions<br />
In terms of its function, the SearchDescriptor is best compared with the search<br />
dialog from <strong>OpenOffice</strong>.<strong>org</strong>. In a similar way to the search window, the settings<br />
needed for a search can be set in the SearchDescriptor object.<br />
The properties are provided by the com.sun.star.util.SearchDescriptor service:<br />
SearchBackwards (Boolean)<br />
searches through the text backward rather than forward.<br />
SearchCaseSensitive (Boolean)<br />
takes uppercase and lowercase characters into consideration during the<br />
search.<br />
SearchRegularExpression (Boolean)<br />
treats the search expression like a regular expression.<br />
SearchStyles (Boolean)<br />
searches through the text for the specified paragraph template.<br />
SearchWords (Boolean)<br />
only searches for complete words.<br />
The <strong>OpenOffice</strong>.<strong>org</strong> SearchSimilarity (or “fuzzy match”) function is also available in<br />
<strong>OpenOffice</strong>.<strong>org</strong> Basic. With this function, <strong>OpenOffice</strong>.<strong>org</strong> searches for an expression<br />
that may be similar to but not exactly the same as the search expression. The<br />
number of additional, deleted and modified characters for these expressions can be<br />
defined individually. Here are the associated properties of the<br />
com.sun.star.util.SearchDescriptor service:<br />
SearchSimilarity (Boolean)<br />
performs a similarity search.<br />
SearchSimilarityAdd (Short)<br />
number of characters which may be added for a similarity search.<br />
SearchSimilarityExchange (Short)<br />
number of characters which may be replaced as part of a similarity search.<br />
SearchSimilarityRemove (Short)<br />
number of characters which may be removed as part of a similarity search.<br />
SearchSimilarityRelax (Boolean)<br />
takes all deviation rules into consideration at the same time for the search<br />
expression.<br />
Chapter 6 · Text Documents 119
Searching for Text Portions<br />
Once the SearchDescriptor has been prepared as requested, it can be applied to the<br />
text document. The <strong>OpenOffice</strong>.<strong>org</strong> documents provide the findFirst and findNext<br />
methods for this purpose:<br />
Found = Doc.findFirst (SearchDesc)<br />
Do While Found<br />
' Suchergebnis bearbeiten<br />
Found = Doc.findNext( Found.End, Search)<br />
Loop<br />
The example finds all matches in a loop and returns a TextRange object, which refers<br />
to the found text passage.<br />
Example: Similarity Search<br />
This example shows how a text can be searched for the word "turnover" and the<br />
results formatted in bold type. A similarity search is used so that not only the word<br />
“turnover”, but also the plural form "turnovers" and declinations such as "turnover's"<br />
are found. The found expressions differ by up to two letters from the search<br />
expression:<br />
Dim SearchDesc As Object<br />
Dim Doc As Object<br />
Doc = StarDesktop.CurrentComponent<br />
SearchDesc = Doc.createSearchDescriptor<br />
SearchDesc.SearchString="turnover"<br />
SearchDesc.SearchSimilarity = True<br />
SearchDesc.SearchSimilarityAdd = 2<br />
SearchDesc.SearchSimilarityExchange = 2<br />
SearchDesc.SearchSimilarityRemove = 2<br />
SearchDesc.SearchSimilarityRelax = False<br />
Found = Doc.findFirst (SearchDesc)<br />
Do While Found<br />
Found.CharWeight = com.sun.star.awt.FontWeight.BOLD<br />
Found = Doc.findNext( Found.End, Search)<br />
Loop<br />
Note – The basic idea of search and replace in <strong>OpenOffice</strong>.<strong>org</strong> is comparable to<br />
that used in VBA. Both interfaces provide you with an object, through which the<br />
properties for searching and replacing can be defined. This object is then applied to<br />
the required text area in order to perform the action. Whereas the responsible<br />
auxiliary object in VBA can be reached through the Find property of the Range object,<br />
in <strong>OpenOffice</strong>.<strong>org</strong> Basic it is created by the createSearchDescriptor or<br />
createReplaceDescriptor call of the document object. Even the search properties<br />
and methods available differ.<br />
120 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Searching for Text Portions<br />
As in the old API from <strong>OpenOffice</strong>.<strong>org</strong>, searching and replacing text in the new API is<br />
also performed using the document object. Whereas previously there was an object<br />
called SearchSettings especially for defining the search options, in the new object<br />
searches are now performed using a SearchDescriptor or ReplaceDescriptor object<br />
for automatically replacing text. These objects cover not only the options, but also the<br />
current search text and, if necessary, the associated text replacement. The descriptor<br />
objects are created using the document object, completed in accordance with the<br />
relevant requests, and then transferred back to the document object as parameters<br />
for the search methods.<br />
Replacing Text Portions<br />
Just as with the search function, the replacement function from <strong>OpenOffice</strong>.<strong>org</strong> is<br />
also available in <strong>OpenOffice</strong>.<strong>org</strong> Basic. The two functions are handled identically. A<br />
special object which records the parameters for the process is also first needed for a<br />
replacement process. It is called a ReplaceDescriptor and supports the<br />
com.sun.star.util.ReplaceDescriptor<br />
service. All the properties of the SearchDescriptor described in the previous<br />
paragraph are also supported by ReplaceDescriptor. For example, during a<br />
replacement process, case sensitivity can also be activated and deactivated, and<br />
similarity searches can be performed.<br />
The following example demonstrates the use of ReplaceDescriptors for a search<br />
within a <strong>OpenOffice</strong>.<strong>org</strong> document.<br />
Dim I As Long<br />
Dim Doc As Object<br />
Dim Replace As Object<br />
Dim BritishWords(5) As String<br />
Dim USWords(5) As String<br />
BritishWords() = Array("colour", "neighbour", "centre", "behaviour", _<br />
"metre", "through")<br />
USWords() = Array("color", "neighbor", "center", "behavior", _<br />
"meter", "thru")<br />
Doc = StarDesktop.CurrentComponent<br />
Replace = Doc.createReplaceDescriptor<br />
For I = 0 To 5<br />
Replace.SearchString = BritishWords(I)<br />
Replace.ReplaceString = USWords(I)<br />
Doc.replaceAll(Replace)<br />
Next I<br />
Chapter 6 · Text Documents 121
Replacing Text Portions<br />
The expressions for searching and replacing are set using the SearchString and<br />
ReplaceString properties of the ReplaceDescriptors. The actual replacement<br />
process is finally implemented using the replaceAll method of the document object,<br />
which replaces all occurrences of the search expression.<br />
Example: searching and replacing text with regular<br />
expressions<br />
The replacement function of <strong>OpenOffice</strong>.<strong>org</strong> is particularly effective when used in<br />
conjunction with regular expressions. These provide the option of defining a variable<br />
search expression with place holders and special characters rather than a fixed<br />
value.<br />
The regular expressions supported by <strong>OpenOffice</strong>.<strong>org</strong> are described in detail in the<br />
online help section for <strong>OpenOffice</strong>.<strong>org</strong>. Here are a few examples:<br />
A period within a search expression stands for any character. The search<br />
expression sh.rt therefore can stand for both for shirt and for short.<br />
The character ^ marks the start of a paragraph. All occurrences of the name Peter<br />
that are at the start of a paragraph can therefore be found using the search<br />
expression ^Peter.<br />
The character $ marks a paragraph end. All occurrences of the name Peter that<br />
are at the end of a paragraph can therefore be found using the search expression<br />
Peter$.<br />
A * indicates that the preceding character may be repeated any number of times.<br />
It can be combined with the period as a place holder for any character. The<br />
temper.*e expression, for example, can stand for the expressions temperance and<br />
temperature.<br />
The following example shows how all empty lines in a text document can be removed<br />
with the help of the regular expression ^$:<br />
Dim Doc As Object<br />
Dim Replace As Object<br />
Dim I As Long<br />
Doc = StarDesktop.CurrentComponent<br />
Replace = Doc.createReplaceDescriptor<br />
Replace.SearchRegularExpression = True<br />
Replace.SearchString = "^$"<br />
Replace.ReplaceString = ""<br />
Doc.replaceAll(Replace)<br />
122 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
More Than Just Text<br />
Replacing Text Portions<br />
So far, this chapter has only dealt with text paragraphs and their portions. But text<br />
documents may also contain other objects. These include tables, drawings, text fields<br />
and directories. All of these objects can be anchored to any point within a text.<br />
Thanks to these common features, all of these objects in <strong>OpenOffice</strong>.<strong>org</strong> support a<br />
common basic service called com.sun.star.text.TextContent. This provides the<br />
following properties:<br />
AnchorType (Enum)<br />
determines the anchor type of a TextContent object (default values in<br />
accordance with com.sun.star.text.TextContentAnchorType enumeration).<br />
AnchorTypes (sequence of Enum)<br />
enumeration of all AnchorTypes which support a special TextContent object.<br />
TextWrap (Enum)<br />
determines the text wrap type around a TextContent object (default values in<br />
accordance with com.sun.star.text.WrapTextMode enumeration).<br />
The TextContent objects also share some methods – in particular, those for creating,<br />
inserting and deleting objects.<br />
A new TextContent object is created using the createInstance method of the<br />
document object.<br />
An object is inserted using the insertTextContent method of the text object.<br />
TextContent objects are deleted using the removeTextContent method.<br />
You will find a range of examples which use these methods in the following sections.<br />
Tables<br />
The following example creates a table with the help of the createInstance method<br />
described previously.<br />
Dim Doc As Object<br />
Dim Table As Object<br />
Dim Cursor As Object<br />
Doc = StarDesktop.CurrentComponent<br />
Cursor = Doc.Text.createTextCursor()<br />
Chapter 6 · Text Documents 123
Tables<br />
Table = Doc.createInstance("com.sun.star.text.TextTable")<br />
Table.initialize(5, 4)<br />
Doc.Text.insertTextContent(Cursor, Table, False)<br />
Once created, the table is set to the number of rows and columns requested using an<br />
initialize call and then inserted in the text document using insertTextContent.<br />
As can be seen in the example, the insertTextContent method expects not only the<br />
Content object to be inserted, but two other parameters:<br />
a Cursor object which determines the insert position<br />
a Boolean variable which specifies whether the Content object is to replace the<br />
current selection of the cursor (True value) or is to be inserted before the current<br />
selection in the text (False)<br />
Note – When creating and inserting tables in a text document, objects similar to<br />
those available in VBA are used in <strong>OpenOffice</strong>.<strong>org</strong> Basic: The document object and a<br />
TextCursor object in <strong>OpenOffice</strong>.<strong>org</strong> Basic, or the Range object as the VBA<br />
counterpart. Whereas the Document.Tables.Add method takes on the task of creating<br />
and setting the table in VBA, this is created in <strong>OpenOffice</strong>.<strong>org</strong> Basic in accordance<br />
with the previous example using createInstance, initialized, and inserted in the<br />
document through insertTextContent.<br />
The tables inserted in a text document can be determined using a simple loop. The<br />
method getTextTables() of the text document object is used for this purpose:<br />
Dim Doc As Object<br />
Dim TextTables As Object<br />
Dim Table As Object<br />
Dim I As Integer<br />
Doc = StarDesktop.CurrentComponent<br />
TextTables = Doc.getTextTables()<br />
For I = 0 to TextTables.count - 1<br />
Table = TextTables(I)<br />
' Editing table<br />
Next I<br />
Note – Text tables are available in <strong>OpenOffice</strong>.<strong>org</strong> through the TextTables list of the<br />
document object. The previous example shows how a text table can be created. The<br />
options for accessing text tables are described in the following section.<br />
Editing Tables<br />
A table consists of individual rows. These in turn contain the various cells. Strictly<br />
speaking, there are no table columns in <strong>OpenOffice</strong>.<strong>org</strong>. These are produced<br />
124 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
implicitly by arranging the rows (one under another) next to one another. To simplify<br />
access to the tables, <strong>OpenOffice</strong>.<strong>org</strong>, however, provides some methods which<br />
operate using columns. These are useful if no cells have been merged in the table.<br />
Tables<br />
Let us first take the properties of the table itself. These are defined in the<br />
com.sun.star.text.TextTable service. Here is an list of the most important properties of<br />
the table object:<br />
BackColor (Long)<br />
background color of table.<br />
BottomMargin (Long)<br />
bottom margin in 100ths of a millimeter.<br />
LeftMargin (Long)<br />
left margin in 100ths of a millimeter.<br />
RightMargin (Long)<br />
right margin in 100ths of a millimeter.<br />
TopMargin (Long)<br />
top margin in 100ths of a millimeter.<br />
RepeatHeadline (Boolean)<br />
table header is repeated on every page.<br />
Width (Long)<br />
Rows<br />
absolute width of the table in 100ths of a millimeter.<br />
A table consists of a list containing rows. The following example shows how the rows<br />
of a table can be retrieved and formatted.<br />
Dim Doc As Object<br />
Dim Table As Object<br />
Dim Cursor As Object<br />
Dim Rows As Object<br />
Dim Row As Object<br />
Dim I As Integer<br />
Doc = StarDesktop.CurrentComponent<br />
Cursor = Doc.Text.createTextCursor()<br />
Table = Doc.createInstance("com.sun.star.text.TextTable")<br />
Table.initialize(5, 4)<br />
Chapter 6 · Text Documents 125
Tables<br />
Doc.Text.insertTextContent(Cursor, Table, False)<br />
Rows = Table.getRows<br />
For I = 0 To Rows.getCount() - 1<br />
Row = Rows.getByIndex(I)<br />
Row.BackColor = &HFF00FF<br />
Next<br />
The example first creates a list containing all rows using a Table.getRows call. The<br />
getCount and getByIndex methods allow the list to be further processed and belongs<br />
to the com.sun.star.table.XtableRows interface. The getByIndex method returns a<br />
row object, which supports the com.sun.star.text.TextTableRow service.<br />
Here are the central methods of the com.sun.star.table.XtableRows interface:<br />
getByIndex(Integer)<br />
returns a row object for the specified index.<br />
getCount()<br />
returns the number of row objects.<br />
insertByIndex(Index, Count)<br />
inserts Count rows in the table as of the Index position.<br />
removeByIndex(Index, Count)<br />
deletes Count rows from the table as of the Index position.<br />
Whereas the getByIndex and getCount methods are available in all tables, the<br />
insertByIndex and removeByIndex methods can only be used in tables that do not<br />
contain merged cells.<br />
The com.sun.star.text.TextTableRow service provides the following properties:<br />
BackColor (Long)<br />
background color of row.<br />
Height (Long)<br />
height of line in 100ths of a millimeter.<br />
IsAutoHeight (Boolean)<br />
table height is dynamically adapted to the content.<br />
VertOrient (const)<br />
vertical orientation of the text frame — details on vertical orientation of the text<br />
within the table (values in accordance with com.sun.star.text.VertOrientation)<br />
126 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Columns<br />
Tables<br />
Columns are accessed in the same way as rows, using the getByIndex, getCount,<br />
insertByIndex, and removeByIndex methods on the Column object, which is reached<br />
through getColumns. They can, however, only be used in tables that do not contain<br />
merged table cells. Cells cannot be formatted by column in <strong>OpenOffice</strong>.<strong>org</strong> Basic. To<br />
do so, the method of formatting individual table cells must be used.<br />
Cells<br />
Each cell of a <strong>OpenOffice</strong>.<strong>org</strong> document has a unique name. If the cursor of<br />
<strong>OpenOffice</strong>.<strong>org</strong> is in a cell, then the name of that cell can be seen in the status bar.<br />
The top left cell is usually called A1 and the bottom right row is usually called Xn,<br />
where X stands for the letters of the top column and n for the numbers of the last row.<br />
The cell objects are available through the getCellByName() method of the table<br />
object. The following example shows a loop that passes through all the cells of a<br />
table and enters the corresponding row and column numbers into the cells.<br />
Dim Doc As Object<br />
Dim Table As Object<br />
Dim Cursor As Object<br />
Dim Rows As Object<br />
Dim RowIndex As Integer<br />
Dim Cols As Object<br />
Dim ColIndex As Integer<br />
Dim CellName As String<br />
Dim Cell As Object<br />
Doc = StarDesktop.CurrentComponent<br />
Cursor = Doc.Text.createTextCursor()<br />
Table = Doc.createInstance("com.sun.star.text.TextTable")<br />
Table.initialize(5, 4)<br />
Doc.Text.insertTextContent(Cursor, Table, False)<br />
Rows = Table.getRows<br />
Cols = Table.getColumns<br />
For RowIndex = 1 To Rows.getCount()<br />
For ColIndex = 1 To Cols.getCount()<br />
CellName = Chr(Asc("A") - 1 + ColIndex) & RowIndex<br />
Cell = Table.getCellByName(CellName)<br />
Cell.String = "row: " & CStr(RowIndex) + ", column: " & CStr(ColIndex)<br />
Next<br />
Next<br />
A table cell is comparable with a standard text. It supports the createTextCursor<br />
interface for creating an associated TextCursor object.<br />
Chapter 6 · Text Documents 127
Tables<br />
CellCursor = Cell.createTextCursor()<br />
All formatting options for individual characters and paragraphs are therefore<br />
automatically available.<br />
The following example searches through all tables of a text document and applies the<br />
right-align format to all cells with numerical values by means of the corresponding<br />
paragraph property.<br />
Dim Doc As Object<br />
Dim TextTables As Object<br />
Dim Table As Object<br />
Dim CellNames<br />
Dim Cell As Object<br />
Dim CellCursor As Object<br />
Dim I As Integer<br />
Dim J As Integer<br />
Doc = StarDesktop.CurrentComponent<br />
TextTables = Doc.getTextTables()<br />
For I = 0 to TextTables.count - 1<br />
Table = TextTables(I)<br />
CellNames = Table.getCellNames()<br />
For J = 0 to UBound(CellNames)<br />
Cell = Table.getCellByName(CellNames(J))<br />
If IsNumeric(Cell.String) Then<br />
CellCursor = Cell.createTextCursor()<br />
CellCursor.paraAdjust = com.sun.star.style.ParagraphAdjust.RIGHT<br />
End If<br />
Next<br />
Next<br />
The example creates a TextTables list containing all tables of a text that are<br />
traversed in a loop. <strong>OpenOffice</strong>.<strong>org</strong> then creates a list of the associated cell names<br />
for each of these tables. There are passed through in turn in a loop. If a cell contains<br />
a numerical value, then the example changes the formatting correspondingly. To do<br />
this, it first creates a TextCursor object which makes reference to the content of the<br />
table cell and then adapts the paragraph properties of the table cell.<br />
Text Frames<br />
Text frames are considered to be TextContent objects, just like tables and graphs.<br />
They may essentially consist of standard text, but can be placed at any position on a<br />
page and are not included in the text flow.<br />
As with all TextContent objects, a distinction is also made with text frames between<br />
128 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
the actual creation and insertion in the document.<br />
Dim Doc As Object<br />
Dim TextTables As Object<br />
Dim Cursor As Object<br />
Dim Frame As Object<br />
Doc = StarDesktop.CurrentComponent<br />
Cursor = Doc.Text.createTextCursor()<br />
Frame = Doc.createInstance("com.sun.star.text.TextFrame")<br />
Doc.Text.insertTextContent(Cursor, Frame, False)<br />
Text Frames<br />
The text frame is created using the createInstance method of the document object.<br />
The text frame created in this way can then be inserted in the document using the<br />
insertTextContent method of the Text object. In so doing, the name of the proper<br />
com.sun.star.text.TextFrame service should be specified.<br />
The text frame's insert position is determined by a Cursor object, which is also<br />
executed when inserted.<br />
Note – Text frames are <strong>OpenOffice</strong>.<strong>org</strong>'s counterpart to the position frame used in<br />
Word. Whereas VBA uses the Document.Frames.Add method for this purpose,<br />
creation in <strong>OpenOffice</strong>.<strong>org</strong> Basic is performed using the previous procedure with the<br />
aid of a TextCursor as well as the createInstance method of the document object.<br />
Text frame objects provide a range of properties with which the position and behavior<br />
of the frame can be influenced. The majority of these properties are defined in the<br />
com.sun.star.text.BaseFrameProperties service, which is also supported by each<br />
TextFrame service. The central properties are:<br />
BackColor (Long)<br />
background color of the text frame.<br />
BottomMargin (Long)<br />
bottom margin in 100ths of a millimeter.<br />
LeftMargin (Long)<br />
left margin in 100ths of a millimeter.<br />
RightMargin (Long)<br />
right margin in 100ths of a millimeter.<br />
TopMargin (Long)<br />
top margin in 100ths of a millimeter.<br />
Height (Long)<br />
height of text frame in 100ths of a millimeter.<br />
Chapter 6 · Text Documents 129
Text Frames<br />
Width (Long)<br />
width of text frame in 100ths of a millimeter.<br />
HoriOrient (const)<br />
horizontal orientation of text frame (in accordance with<br />
com.sun.star.text.HoriOrientation).<br />
VertOrient (const)<br />
vertical orientation of text frame (in accordance with<br />
com.sun.star.text.VertOrientation).<br />
The following example creates a text frame using the properties described previously:<br />
Dim Doc As Object<br />
Dim TextTables As Object<br />
Dim Cursor As Object<br />
Dim Frame As Object<br />
Doc = StarDesktop.CurrentComponent<br />
Cursor = Doc.Text.createTextCursor()<br />
Cursor.gotoNextWord(False)<br />
Frame = Doc.createInstance("com.sun.star.text.TextFrame")<br />
Frame.Width = 3000<br />
Frame.Height = 1000<br />
Frame.AnchorType = com.sun.star.text.TextContentAnchorType.AS_CHARACTER<br />
Frame.TopMargin = 0<br />
Frame.BottomMargin = 0<br />
Frame.LeftMargin = 0<br />
Frame.RightMargin = 0<br />
Frame.BorderDistance = 0<br />
Frame.HoriOrient = com.sun.star.text.HoriOrientation.NONE<br />
Frame.VertOrient = com.sun.star.text.VertOrientation.LINE_TOP<br />
Doc.Text.insertTextContent(Cursor, Frame, False)<br />
The example creates a TextCursor as the insertion mark for the text frame. This is<br />
positioned between the first and second word of the text. The text frame is created<br />
using Doc.createInstance. The properties of the text frame objects are set to the<br />
starting values required.<br />
The interaction between the AnchorType (from the TextContent Service) and<br />
VertOrient (from the BaseFrameProperties Service) properties should be noted here.<br />
AnchorType receives the AS_CHARACTER value. The text frame is therefore inserted<br />
directly in the text flow and behaves like a character. It can, for example, be moved<br />
into the next line if a line break occurs. The LINE_TOP value of the VertOrient<br />
property ensures that the upper edge of the text frame is at the same height as the<br />
upper edge of the character.<br />
Once initialization is complete, the text frame is finally inserted in the text document<br />
130 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
using a call from insertTextContent.<br />
Text Frames<br />
To edit the content of a text frame, the user uses the TextCursor, which has already<br />
been mentioned numerous times and is also available for text frames.<br />
Dim Doc As Object<br />
Dim TextTables As Object<br />
Dim Cursor As Object<br />
Dim Frame As Object<br />
Dim FrameCursor As Object<br />
Doc = StarDesktop.CurrentComponent<br />
Cursor = Doc.Text.createTextCursor()<br />
Frame = Doc.createInstance("com.sun.star.text.TextFrame")<br />
Frame.Width = 3000<br />
Frame.Height = 1000<br />
Doc.Text.insertTextContent(Cursor, Frame, False)<br />
FrameCursor = Frame.createTextCursor()<br />
FrameCursor.charWeight = com.sun.star.awt.FontWeight.BOLD<br />
FrameCursor.paraAdjust = com.sun.star.style.ParagraphAdjust.CENTER<br />
FrameCursor.String = "This is a small Test!"<br />
The example creates a text frame, inserts this in the current document and opens a<br />
TextCursor for the text frame. This cursor is used to set the frame font to bold type<br />
and to set the paragraph orientation to centered. The text frame is finally assigned<br />
the “This is a small test!” string.<br />
Text Fields<br />
Text fields are TextContent objects because they provide additional logic extending<br />
beyond pure text. Text fields can be inserted in a text document using the same<br />
methods as those used for other TextContent objects:<br />
Dim Doc As Object<br />
Dim DateTimeField As Object<br />
Dim Cursor As Object<br />
Doc = StarDesktop.CurrentComponent<br />
Cursor = Doc.Text.createTextCursor()<br />
DateTimeField = Doc.createInstance("com.sun.star.text.textfield.DateTime")<br />
DateTimeField.IsFixed = False<br />
DateTimeField.IsDate = True<br />
Doc.Text.insertTextContent(Cursor, DateTimeField, False)<br />
The example inserts a text field with the current date at the start of the current text<br />
document. The True value of the IsDate property results in only the date and not time<br />
Chapter 6 · Text Documents 131
Text Fields<br />
being displayed. The False value for IsFixed ensures that the date is automatically<br />
updated when the document is opened.<br />
Note – While the type of a field in VBA is specified by a parameter of the<br />
Document.Fields.Add method, the name of the service that is responsible for the field<br />
type in question defines it in <strong>OpenOffice</strong>.<strong>org</strong> Basic.<br />
In the past, text fields were accessed using a whole range of methods that<br />
<strong>OpenOffice</strong>.<strong>org</strong> made available in the old Selection object (for example InsertField,<br />
DeleteUserField, SetCurField).<br />
In <strong>OpenOffice</strong>.<strong>org</strong> 2.x, the fields are administered using an object-oriented concept.<br />
To create a text field, a text field of the type required should first be created and<br />
initialized using the properties required. The text field is then inserted in the document<br />
using the insertTextContent method. A corresponding source text can be seen in<br />
the previous example. The most important field types and their properties are<br />
described in the following sections.<br />
In addition to inserting text fields, searching a document for the fields can also be an<br />
important task. The following example shows how all text fields of a text document<br />
can be traversed in a loop and checked for their relevant type.<br />
Dim Doc As Object<br />
Dim TextFieldEnum As Object<br />
Dim TextField As Object<br />
Dim I As Integer<br />
Doc = StarDesktop.CurrentComponent<br />
TextFieldEnum = Doc.getTextFields.createEnumeration<br />
While TextFieldEnum.hasMoreElements()<br />
TextField = TextFieldEnum.nextElement()<br />
If TextField.supportsService("com.sun.star.text.textfield.DateTime") Then<br />
MsgBox "Date/time"<br />
ElseIf TextField.supportsService("com.sun.star.text.textfield.Annotation")<br />
Then<br />
MsgBox "Annotation"<br />
Else<br />
MsgBox "unknown"<br />
End If<br />
Wend<br />
The starting point for establishing the text fields present is the TextFields list of the<br />
document object. The example creates an Enumeration object on the basis of this list,<br />
with which all text fields can be queried in turn in a loop. The text fields found are<br />
checked for the service supported using the supportsService method. If the field<br />
132 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Text Fields<br />
proves to be a date/time field or an annotation, then the corresponding field type is<br />
displayed in an information box. If on the other hand, the example encounters<br />
another field, then it displays the information “unknown”.<br />
Below, you will find a list of the most important text fields and their associated<br />
properties. A complete list of all text fields is provided in the API reference in the<br />
com.sun.star.text.textfield module. (When listing the service name of a text field,<br />
uppercase and lowercase characters should be used in <strong>OpenOffice</strong>.<strong>org</strong> Basic, as in<br />
the previous example.)<br />
Number of Pages, Words and Characters<br />
The text fields<br />
com.sun.star.text.textfield.PageCount<br />
com.sun.star.text.textfield.WordCount<br />
com.sun.star.text.textfield.CharacterCount<br />
return the number of pages, words, or characters of a text. They support the following<br />
property:<br />
NumberingType (const)<br />
numbering format (guidelines in accordance with constants from<br />
com.sun.star.style.NumberingType).<br />
Current Page<br />
The number of the current page can be inserted in a document using the<br />
com.sun.star.text.textfield.PageNumber text field. The following properties can be<br />
specified:<br />
NumberingType (const)<br />
number format (guidelines in accordance with constants from<br />
com.sun.star.style.NumberingType).<br />
Offset (short)<br />
offset added to the number of pages (negative specification also possible).<br />
The following example shows how the number of pages can be inserted into the<br />
footer of a document.<br />
Dim Doc As Object<br />
Dim DateTimeField As Object<br />
Chapter 6 · Text Documents 133
Text Fields<br />
Dim PageStyles As Object<br />
Dim StdPage As Object<br />
Dim FooterCursor As Object<br />
Dim PageNumber As Object<br />
Doc = StarDesktop.CurrentComponent<br />
PageNumber = Doc.createInstance("com.sun.star.text.textfield.PageNumber")<br />
PageNumber.NumberingType = com.sun.star.style.NumberingType.ARABIC<br />
PageStyles = Doc.StyleFamilies.getByName("PageStyles")<br />
StdPage = PageStyles("Default")<br />
StdPage.FooterIsOn = True<br />
FooterCursor = StdPage.FooterTextLeft.Text.createTextCursor()<br />
StdPage.FooterTextLeft.Text.insertTextContent(FooterCursor, PageNumber, False)<br />
The example first creates a text field which supports the<br />
com.sun.star.text.textfield.PageNumber service. Since the header and footer lines are<br />
defined as part of the page templates of <strong>OpenOffice</strong>.<strong>org</strong>, this is initially established<br />
using the list of all PageStyles.<br />
To ensure that the footer line is visible, the FooterIsOn property is set to True. The<br />
text field is then inserted in the document using the associated text object of the lefthand<br />
footer line.<br />
Annotations<br />
Annotation fields (com.sun.star.text.textfield.Annotation) can be seen by means of a<br />
small yellow symbol in the text. Clicking on this symbol opens a text field, in which a<br />
comment on the current point in the text can be recorded. An annotation field has the<br />
following properties.<br />
Author (String)<br />
name of author.<br />
Content (String)<br />
comment text.<br />
Date (Date)<br />
date on which annotation is written.<br />
134 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Date / Time<br />
Text Fields<br />
A date / time field (com.sun.star.text.textfield.DateTime) represents the current date<br />
or the current time. It supports the following properties:<br />
IsFixed (Boolean)<br />
if True, the time details of the insertion remain unchanged, if False, these are<br />
updated each time the document is opened.<br />
IsDate (Boolean)<br />
if True, the field displays the current date, otherwise the current time.<br />
DateTimeValue (struct)<br />
current content of field (com.sun.star.util.DateTime structure)<br />
NumberFormat (const)<br />
format in which the time or date is depicted.<br />
Chapter Name / Number<br />
The name of the current chapter is available through a text field of the<br />
com.sun.star.text.textfield.Chapter type. The form can be defined using two<br />
properties.<br />
ChapterFormat (const)<br />
determines whether the chapter name or the chapter number is depicted (in<br />
accordance with com.sun.star.text.ChapterFormat)<br />
Level (Integer)<br />
determines the chapter level whose name and/or chapter number is to be<br />
displayed. The value 0 stands for highest level available.<br />
Bookmarks<br />
Bookmarks (Service com.sun.star.text.Bookmark) are TextContent objects.<br />
Bookmarks are created and inserted using the concept already described previously:<br />
Dim Doc As Object<br />
Dim Bookmark As Object<br />
Dim Cursor As Object<br />
Chapter 6 · Text Documents 135
Bookmarks<br />
Doc = StarDesktop.CurrentComponent<br />
Cursor = Doc.Text.createTextCursor()<br />
Bookmark = Doc.createInstance("com.sun.star.text.Bookmark")<br />
Bookmark.Name = "My bookmarks"<br />
Doc.Text.insertTextContent(Cursor, Bookmark, True)<br />
The example creates a Cursor, which marks the insert position of the bookmark and<br />
then the actual bookmark object (Bookmark). The bookmark is then assigned a name<br />
and is inserted in the document through insertTextContent at the cursor position.<br />
The bookmarks of a text are accessed through a list called Bookmarks. The<br />
bookmarks can either be accessed by their number or their name.<br />
The following example shows how a bookmark can be found within a text, and a text<br />
inserted at its position.<br />
Dim Doc As Object<br />
Dim Bookmark As Object<br />
Dim Cursor As Object<br />
Doc = StarDesktop.CurrentComponent<br />
Bookmark = Doc.Bookmarks.getByName("My bookmarks")<br />
Cursor = Doc.Text.createTextCursorByRange(Bookmark.Anchor)<br />
Cursor.String = "Here is the bookmark"<br />
In this example, the getByName method is used to find the bookmark required by<br />
means of its name. The createTextCursorByRange call then creates a Cursor, which<br />
is positioned at the anchor position of the bookmark. The cursor then inserts the text<br />
required at this point.<br />
136 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
7<br />
C H A P T E R 7<br />
7 Spreadsheet Documents<br />
<strong>OpenOffice</strong>.<strong>org</strong> Basic provides an extensive interface for program-controlled creation<br />
and editing of spreadsheets. This chapter describes how to control the relevant<br />
services, methods and properties of spreadsheet documents:<br />
The Structure of Spreadsheets<br />
Editing Spreadsheet Documents<br />
The first section addresses the basic structure of spreadsheet documents and shows<br />
you how to access and to edit the contents of individual cells.<br />
The second section concentrates on how to edit spreadsheets efficiently by focusing<br />
on cell areas and the options for searching and replacing cell contents.<br />
Note – The Range object allows you to address any table area and has been<br />
extended in the new API.<br />
The Structure of Spreadsheets<br />
The document object of a spreadsheet is based on the<br />
com.sun.star.sheet.SpreadsheetDocument service. Each of these documents may<br />
contain several spreadsheets. In this guide, a table-based document or spreadsheet<br />
137
Spreadsheet Documents<br />
document is the entire document, whereas a spreadsheet (or sheet for short) is a<br />
sheet (table) in the document.<br />
Note – Different terminology for spreadsheets and their content is used in VBA and<br />
<strong>OpenOffice</strong>.<strong>org</strong> Basic. Whereas the document object in VBA is called a Workbook<br />
and its individual pages Worksheets, they are called SpreadsheetDocument and<br />
Sheet in <strong>OpenOffice</strong>.<strong>org</strong> Basic.<br />
Spreadsheets<br />
You can access the individual sheets of a spreadsheet document through the Sheets<br />
list.<br />
The following examples show you how to access a sheet either through its number or<br />
its name.<br />
Example 1: access by means of the number (numbering begins with 0)<br />
Dim Doc As Object<br />
Dim Sheet As Object<br />
Doc = StarDesktop.CurrentComponent<br />
Sheet = Doc.Sheets (0)<br />
Example 2: access by means of the name<br />
Dim Doc As Object<br />
Dim Sheet As Object<br />
Doc = StarDesktop.CurrentComponent<br />
Sheet = Doc.Sheets.getByName("Sheet 1")<br />
In the first example, the sheet is accessed by its number (counting begins at 0). In the<br />
second example, the sheet is accessed by its name and the getByName method.<br />
The Sheet object that is obtained by the getByName method supports the<br />
com.sun.star.sheet.Spreadsheet service. In addition to providing several interfaces<br />
for editing the content, this service provides the following properties:<br />
IsVisible (Boolean)<br />
the spreadsheet is visible.<br />
PageStyle (String)<br />
name of the page template for the spreadsheet.<br />
138 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Creating, Deleting and Renaming Sheets<br />
Spreadsheets<br />
The Sheets list for a spreadsheet document is also used to create, delete, and<br />
rename individual sheets. The following example uses the hasByName method to<br />
check if a sheet called MySheet exists. If it does, the method determines a<br />
corresponding object reference by using the getByName method and then saves the<br />
reference in a variable in Sheet. If the corresponding sheet does not exist, it is<br />
created by the createInstance call and inserted in the spreadsheet document by the<br />
insertByName method.<br />
Dim Doc As Object<br />
Dim Sheet As Object<br />
Doc = StarDesktop.CurrentComponent<br />
Sheet = Doc.Sheets(0)<br />
If Doc.Sheets.hasByName("MySheet") Then<br />
Sheet = Doc.Sheets.getByName("MySheet")<br />
Else<br />
Sheet = Doc.createInstance("com.sun.star.sheet.Spreadsheet")<br />
Doc.Sheets.insertByName("MySheet", Sheet)<br />
End If<br />
The getByName and insertByName methods are from the<br />
com.sun.star.container.XNameContainer interface as described in Introduction to the<br />
API.<br />
Rows and Columns<br />
Each sheet contains a list of its rows and columns. These are available through the<br />
Rows and Columns properties of the spreadsheet object and support the<br />
com.sun.star.table.TableColumns and/or com.sun.star.table.TableRows services.<br />
The following example creates two objects that reference the first row and the first<br />
column of a sheet and stores the references in the FirstCol and FirstRow object<br />
variables.<br />
Dim Doc As Object<br />
Dim Sheet As Object<br />
Dim FirstRow As Object<br />
Dim FirstCol As Object<br />
Doc = StarDesktop.CurrentComponent<br />
Sheet = Doc.Sheets(0)<br />
FirstCol = Sheet.Columns(0)<br />
FirstRow = Sheet.Rows(0)<br />
Chapter 7 · Spreadsheet Documents 139
Rows and Columns<br />
The column objects support the com.sun.star.table.TableColumn service that has the<br />
following properties:<br />
Width (long)<br />
width of a column in hundredths of a millimeter.<br />
OptimalWidth (Boolean)<br />
sets a column to its optimum width.<br />
IsVisible (Boolean)<br />
displays a column.<br />
IsStartOfNewPage (Boolean)<br />
when printing, creates a page break before a column.<br />
The width of a column is only optimized when the OptimalWidth property is set to<br />
True. If the width of an individual cell is changed, the width of the column that<br />
contains the cell is not changed. In terms of functionality, OptimalWidth is more of a<br />
method than a property.<br />
The row objects are based on the com.sun.star.table.RowColumn service that has<br />
the following properties:<br />
Height (long)<br />
height of the row in 100ths of a millimeter.<br />
OptimalHeight (Boolean)<br />
sets the row to its optimum height.<br />
IsVisible (Boolean)<br />
displays the row.<br />
IsStartOfNewPage (Boolean)<br />
when printing, creates a page break before the row.<br />
If the OptimalHeight property of a row is set to the True, the row height changes<br />
automatically when the height of a cell in the row is changed. Automatic optimization<br />
continues until the row is assigned an absolute height through the Height property.<br />
The following example activates the automatic height optimization for the first five<br />
rows in the sheet and makes the second column invisible.<br />
Dim Doc As Object<br />
Dim Sheet As Object<br />
Dim Row As Object<br />
Dim Col As Object<br />
Dim I As Integer<br />
140 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Doc = StarDesktop.CurrentComponent<br />
Sheet = Doc.Sheets(0)<br />
For I = 0 To 4<br />
Row = Sheet.Rows(I)<br />
Row.OptimalHeight = True<br />
Next I<br />
Col = Sheet.Columns(1)<br />
Col.IsVisible = False<br />
Rows and Columns<br />
Note – The Rows and Columns lists can be accessed through an index in<br />
<strong>OpenOffice</strong>.<strong>org</strong> Basic. Unlike in VBA, the first column has the index 0 and not the<br />
index 1.<br />
Inserting and Deleting Rows and Columns<br />
The Rows and Columns objects of a sheet can access existing rows and columns as<br />
well as insert and delete them.<br />
Dim Doc As Object<br />
Dim Sheet As Object<br />
Dim NewColumn As Object<br />
Doc = StarDesktop.CurrentComponent<br />
Sheet = Doc.Sheets(0)<br />
Sheet.Columns.insertByIndex(3, 1)<br />
Sheet.Columns.removeByIndex(5, 1)<br />
This example uses the insertByIndex method to insert a new column into the fourth<br />
column position in the sheet (index 3 - numbering starts at 0). The second parameter<br />
specifies the number of columns to be inserted (in this example: one).<br />
The removeByIndex method deletes the sixth column (index 5). Again, the second<br />
parameter specifies the number of columns that you want to delete.<br />
The methods for inserting and deleting rows use the Rows object function in the same<br />
way as the methods shown for editing columns using the Columns object.<br />
Cells and Ranges<br />
A spreadsheet consists of a two-dimensional list containing cells. Each cell is defined<br />
Chapter 7 · Spreadsheet Documents 141
Cells and Ranges<br />
by its X and Y-position with respect to the top left cell which has the position (0,0).<br />
Addressing and Editing Individual Cells<br />
The following example creates an object that references the top left cell and inserts a<br />
text in the cell:<br />
Dim Doc As Object<br />
Dim Sheet As Object<br />
Dim Cell As Object<br />
Doc = StarDesktop.CurrentComponent<br />
Sheet = Doc.Sheets(0)<br />
Cell = Sheet.getCellByPosition(0, 0)<br />
Cell.String = "Test"<br />
Note – StarDesktop.CurrentComponent returns the current component. If you are<br />
working in the <strong>BASIC</strong> IDE when you run the macro, then the <strong>BASIC</strong> IDE is returned.<br />
A RunTime error is generated because the <strong>BASIC</strong> IDE does not have a spreadsheet<br />
component.<br />
Save the example code and run the macro from a spreadsheet document. See<br />
StarDesktop for more information.<br />
In addition to numerical coordinates, each cell in a sheet has a name, for example,<br />
the top left cell (0,0) of a spreadsheet is called A1. The letter A stands for the column<br />
and the number 1 for the row. It is important that the name and position of a cell are<br />
not confused because row counting for names begins with 1 but the counting for<br />
position begins with 0.<br />
In <strong>OpenOffice</strong>.<strong>org</strong>, a table cell can be empty or contain text, numbers, or formulas.<br />
The cell type is not determined by the content that is saved in the cell, but rather the<br />
object property which was used for its entry. Numbers can be inserted and called up<br />
with the Value property, text with the String property, and formulas with the Formula<br />
property.<br />
Dim Doc As Object<br />
Dim Sheet As Object<br />
Dim Cell As Object<br />
Doc = StarDesktop.CurrentComponent<br />
Sheet = Doc.Sheets(0)<br />
Cell = Sheet.getCellByPosition(0, 0)<br />
Cell.Value = 100<br />
Cell = Sheet.getCellByPosition(0, 1)<br />
Cell.String = "Test"<br />
142 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Cell = Sheet.getCellByPosition(0, 2)<br />
Cell.Formula = "=A1"<br />
Cells and Ranges<br />
The example inserts one number, one text, and one formula in the fields A1 to A3.<br />
Note – The Value, String, and Formula properties supersede the PutCell method<br />
for setting the values of a table cell.<br />
<strong>OpenOffice</strong>.<strong>org</strong> treats cell content that is entered using the String property as text,<br />
even if the content is a number. Numbers are left-aligned in the cell instead of rightaligned.<br />
You should also note the difference between text and numbers when you use<br />
formulas:<br />
Dim Doc As Object<br />
Dim Sheet As Object<br />
Dim Cell As Object<br />
Doc = StarDesktop.CurrentComponent<br />
Sheet = Doc.Sheets(0)<br />
Cell = Sheet.getCellByPosition(0, 0)<br />
Cell.Value = 100<br />
Cell = Sheet.getCellByPosition(0, 1)<br />
Cell.String = 1000<br />
Cell = Sheet.getCellByPosition(0, 2)<br />
Cell.Formula = "=A1+A2"<br />
MsgBox Cell.Value<br />
Although cell A1 contains the value 100 and cell A2 contains the value 1000, the<br />
A1+A2 formula returns the value 100. This is because the contents of cell A2 were<br />
entered as a string and not as a number.<br />
To check if the contents of a cell contains a number or a string, use the Type property:<br />
Dim Doc As Object<br />
Dim Sheet As Object<br />
Dim Cell As Object<br />
Doc = StarDesktop.CurrentComponent<br />
Sheet = Doc.Sheets(0)<br />
Cell = Sheet.getCellByPosition(1,1)<br />
Cell.Value = 1000<br />
Select Case Cell.Type<br />
Case com.sun.star.table.CellContentType.EMPTY<br />
MsgBox "Content: Empty"<br />
Case com.sun.star.table.CellContentType.VALUE<br />
MsgBox "Content: Value"<br />
Case com.sun.star.table.CellContentType.TEXT<br />
MsgBox "Content: Text"<br />
Chapter 7 · Spreadsheet Documents 143
Cells and Ranges<br />
Case com.sun.star.table.CellContentType.FORMULA<br />
MsgBox "Content: Formula"<br />
End Select<br />
The Cell.Type property returns a value for the com.sun.star.table.CellContentType<br />
enumeration which identifies the contents type of a cell. The possible values are:<br />
EMPTY<br />
VALUE<br />
TEXT<br />
FORMULA<br />
no value<br />
number<br />
strings<br />
formula<br />
Inserting, Deleting, Copying and Moving Cells<br />
In addition to directly modifying cell content, <strong>OpenOffice</strong>.<strong>org</strong> Calc also provides an<br />
interface that allows you to insert, delete, copy, or merge cells. The interface<br />
(com.sun.star.sheet.XRangeMovement) is available through the spreadsheet object<br />
and provides four methods for modifying cell content.<br />
The insertCell method is used to insert cells into a sheet.<br />
Dim Doc As Object<br />
Dim Sheet As Object<br />
Dim CellRangeAddress As New com.sun.star.table.CellRangeAddress<br />
Doc = StarDesktop.CurrentComponent<br />
Sheet = Doc.Sheets(0)<br />
CellRangeAddress.Sheet = 0<br />
CellRangeAddress.StartColumn = 1<br />
CellRangeAddress.StartRow = 1<br />
CellRangeAddress.EndColumn = 2<br />
CellRangeAddress.EndRow = 2<br />
Sheet.insertCells(CellRangeAddress, com.sun.star.sheet.CellInsertMode.DOWN)<br />
This example inserts a cells range that is two rows by two columns in size into the<br />
second column and row (each bear the number 1) of the first sheet (number 0) in the<br />
spreadsheet. Any existing values in the specified cell range are moved below the<br />
range.<br />
144 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Cells and Ranges<br />
To define the cell range that you want to insert, use the<br />
com.sun.star.table.CellRangeAddress structure. The following values are included in<br />
this structure:<br />
Sheet (short)<br />
number of the sheet (numbering begins with 0).<br />
StartColumn (long)<br />
first column in the cell range (numbering begins with 0).<br />
StartRow (long)<br />
first row in the cell range (numbering begins with 0).<br />
EndColumn (long)<br />
final column in the cell range (numbering begins with 0).<br />
EndRow (long)<br />
final row in the cell range (numbering begins with 0).<br />
The completed CellRangeAddress structure must be passed as the first parameter to<br />
the insertCells method. The second parameter of insertCells contains a value of<br />
the com.sun.star.sheet.CellInsertMode enumeration and defines what is to be done<br />
with the values that are located in front of the insert position. The CellInsertMode<br />
enumeration recognizes the following values:<br />
NONE<br />
DOWN<br />
RIGHT<br />
ROWS<br />
COLUMNS<br />
the current values remain in their present position.<br />
the cells at and under the insert position are moved downwards.<br />
the cells at and to the right of the insert position are moved to the right.<br />
the rows after the insert position are moved downwards.<br />
the columns after the insert position are moved to the right.<br />
The removeRange method is the counterpart to the insertCells method. This method<br />
deletes the range that is defined in the CellRangeAddress structure from the sheet.<br />
Dim Doc As Object<br />
Dim Sheet As Object<br />
Dim CellRangeAddress As New com.sun.star.table.CellRangeAddress<br />
Chapter 7 · Spreadsheet Documents 145
Cells and Ranges<br />
Doc = StarDesktop.CurrentComponent<br />
Sheet = Doc.Sheets(0)<br />
CellRangeAddress.Sheet = 0<br />
CellRangeAddress.StartColumn = 1<br />
CellRangeAddress.StartRow = 1<br />
CellRangeAddress.EndColumn = 2<br />
CellRangeAddress.EndRow = 2<br />
Sheet.removeRange(CellRangeAddress, com.sun.star.sheet.CellDeleteMode.UP)<br />
This example removes the B2:C3 cell range from the sheet and then shifts the<br />
underlying cells up by two rows. The type of removal is defined by one of the<br />
following values from the com.sun.star.sheet.CellDeleteMode enumeration:<br />
NONE<br />
UP<br />
LEFT<br />
ROWS<br />
COLUMNS<br />
the current values remain in their current position.<br />
the cells at and below the insert position are moved upwards.<br />
the cells at and to the right of the insert position are moved to the left.<br />
the rows after the insert position are moved upwards.<br />
the columns after the insert position are moved to the left.<br />
The XRangeMovement interface provides two additional methods for moving<br />
(moveRange) or copying (copyRange) cell ranges. The following example moves the<br />
B2:C3 range so that the range starts at position A6:<br />
Dim Doc As Object<br />
Dim Sheet As Object<br />
Dim CellRangeAddress As New com.sun.star.table.CellRangeAddress<br />
Dim CellAddress As New com.sun.star.table.CellAddress<br />
Doc = StarDesktop.CurrentComponent<br />
Sheet = Doc.Sheets(0)<br />
CellRangeAddress.Sheet = 0<br />
CellRangeAddress.StartColumn = 1<br />
CellRangeAddress.StartRow = 1<br />
CellRangeAddress.EndColumn = 2<br />
CellRangeAddress.EndRow = 2<br />
CellAddress.Sheet = 0<br />
CellAddress.Column = 0<br />
CellAddress.Row = 5<br />
146 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Sheet.moveRange(CellAddress, CellRangeAddress)<br />
Cells and Ranges<br />
In addition to the CellRangeAdress structure, the moveRange method expects a<br />
com.sun.star.table.CellAddress structure to define the origin of the move's target<br />
region. The CellAddress method provides the following values:<br />
Sheet (short)<br />
number of the spreadsheet (numbering begins with 0).<br />
Column (long)<br />
number of the addressed column (numbering begins with 0).<br />
Row (long)<br />
number of the addressed row (numbering begins with 0).<br />
The cell contents in the target range are always overwritten by the moveRange<br />
method. Unlike in the InsertCells method , a parameter for performing automatic<br />
moves is not provided in the removeRange method.<br />
The copyRange method functions in the same way as the moveRange method, except<br />
that copyRange inserts a copy of the cell range instead of moving it.<br />
Note – In terms of their function, the <strong>OpenOffice</strong>.<strong>org</strong> Basic insertCell,<br />
removeRange, and copyRange methods are comparable with the VBA Range.Insert,<br />
Range.Delete ,and Range.Copy methods. Whereas in VBA, the methods are applied<br />
to the corresponding Range object, in <strong>OpenOffice</strong>.<strong>org</strong> Basic they are applied to the<br />
associated Sheet object.<br />
Formatting Spreadsheet Documents<br />
A spreadsheet document provides properties and methods for formatting cells and<br />
pages.<br />
Cell Properties<br />
There are numerous options for formatting cells, such as specifying the font type and<br />
size for text. Each cell supports the com.sun.star.style.CharacterProperties and<br />
com.sun.star.style.ParagraphProperties services, the main properties of which are<br />
Chapter 7 · Spreadsheet Documents 147
Formatting Spreadsheet Documents<br />
described in Text Documents. Special cell formatting is handled by the<br />
com.sun.star.table.CellProperties service. The main properties of this service are<br />
described in the following sections.<br />
You can apply all of the named properties to individual cells and to cell ranges.<br />
Note – The CellProperties object in the <strong>OpenOffice</strong>.<strong>org</strong> API is comparable with the<br />
Interior object from VBA which also defines cell-specific properties.<br />
Background Color and Shadows<br />
The com.sun.star.table.CellProperties service provides the following properties for<br />
defining background colors and shadows:<br />
CellBackColor (Long)<br />
background color of the table cell<br />
IsCellBackgroundTransparent (Boolean)<br />
sets the background color to transparent<br />
ShadowFormat (struct)<br />
specifies the shadow for cells (structure in accordance with<br />
com.sun.star.table.ShadowFormat)<br />
The com.sun.star.table.ShadowFormat structure and the detailed specifications for<br />
cell shadows have the following structure:<br />
Location (enum)<br />
position of shadow (value from the com.sun.star.table.ShadowLocation<br />
structure).<br />
ShadowWidth (Short)<br />
size of shadow in hundredths of a millimeter<br />
IsTransparent (Boolean)<br />
sets the shadow to transparent<br />
Color (Long)<br />
color of shadow<br />
The following example writes the number 1000 to the B2 cell, changes the<br />
background color to red using the CellBackColor property, and then creates a light<br />
148 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
gray shadow for the cell that is moved 1 mm to the left and down.<br />
Dim Doc As Object<br />
Dim Sheet As Object<br />
Dim Cell As Object<br />
Dim ShadowFormat As New com.sun.star.table.ShadowFormat<br />
Doc = StarDesktop.CurrentComponent<br />
Sheet = Doc.Sheets(0)<br />
Cell = Sheet.getCellByPosition(1,1)<br />
Cell.Value = 1000<br />
Cell.CellBackColor = RGB(255, 0, 0)<br />
Formatting Spreadsheet Documents<br />
ShadowFormat.Location = com.sun.star.table.ShadowLocation.BOTTOM_RIGHT<br />
ShadowFormat.ShadowWidth = 100<br />
ShadowFormat.Color = RGB(160, 160, 160)<br />
Cell.ShadowFormat = ShadowFormat<br />
Justification<br />
<strong>OpenOffice</strong>.<strong>org</strong> provides various functions that allow you to change the justification of<br />
a text in a table cell.<br />
The following properties define the horizontal and vertical justification of a text:<br />
HoriJustify (enum)<br />
horizontal justification of the text (value from com.sun.star.table.CellHoriJustify)<br />
VertJustify (enum)<br />
vertical justification of the text (value from com.sun.star.table.CellVertJustify)<br />
Orientation (enum)<br />
orientation of text (value in accordance with com.sun.star.table.CellOrientation)<br />
IsTextWrapped (Boolean)<br />
permits automatic line breaks within the cell<br />
RotateAngle (Long)<br />
angle of rotation of text in hundredths of a degree<br />
The following example shows how you can "stack" the contents of a cell so that the<br />
individual characters are printed one under another in the top left corner of the cell.<br />
The characters are not rotated.<br />
Dim Doc As Object<br />
Dim Sheet As Object<br />
Chapter 7 · Spreadsheet Documents 149
Formatting Spreadsheet Documents<br />
Dim Cell As Object<br />
Doc = StarDesktop.CurrentComponent<br />
Sheet = Doc.Sheets(0)<br />
Cell = Sheet.getCellByPosition(1,1)<br />
Cell.Value = 1000<br />
Cell.HoriJustify = com.sun.star.table.CellHoriJustify.LEFT<br />
Cell.VertJustify = com.sun.star.table.CellVertJustify.TOP<br />
Cell.Orientation = com.sun.star.table.CellOrientation.STACKED<br />
Number, Date and Text Format<br />
<strong>OpenOffice</strong>.<strong>org</strong> provides a whole range of predefined date and time formats. Each of<br />
these formats has an internal number that is used to assign the format to cells using<br />
the NumberFormat property. <strong>OpenOffice</strong>.<strong>org</strong> provides the queryKey and addNew<br />
methods so that you can access existing number formats as well as create your own<br />
number formats. The methods are accessed through the following object call:<br />
NumberFormats = Doc.NumberFormats<br />
A format is specified using a format string that is structured in a similar way to the<br />
format function of <strong>OpenOffice</strong>.<strong>org</strong> Basic. However there is one major difference:<br />
whereas the command format expects English abbreviations and decimal points or<br />
characters as thousands separators, the country-specified abbreviations must be<br />
used for the structure of a command format for the NumberFormats object.<br />
The following example formats the B2 cell so that numbers are displayed with three<br />
decimal places and use commas as a thousands separator.<br />
Dim Doc As Object<br />
Dim Sheet As Object<br />
Dim Cell As Object<br />
Dim NumberFormats As Object<br />
Dim NumberFormatString As String<br />
Dim NumberFormatId As Long<br />
Dim LocalSettings As New com.sun.star.lang.Locale<br />
Doc = StarDesktop.CurrentComponent<br />
Sheet = Doc.Sheets(0)<br />
Cell = Sheet.getCellByPosition(1,1)<br />
Cell.Value = 23400.3523565<br />
LocalSettings.Language = "en"<br />
LocalSettings.Country = "us"<br />
NumberFormats = Doc.NumberFormats<br />
NumberFormatString = "#,##0.000"<br />
NumberFormatId = NumberFormats.queryKey(NumberFormatString, LocalSettings,<br />
150 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Formatting Spreadsheet Documents<br />
True)<br />
If NumberFormatId = -1 Then<br />
NumberFormatId = NumberFormats.addNew(NumberFormatString, LocalSettings)<br />
End If<br />
MsgBox NumberFormatId<br />
Cell.NumberFormat = NumberFormatId<br />
The Format Cells dialog in <strong>OpenOffice</strong>.<strong>org</strong> Calc provides an overview of the different<br />
formatting options for cells.<br />
Page Properties<br />
Page properties are the formatting options that position document content on a page<br />
as well as visual elements that are repeated page after page. These include<br />
Paper formats<br />
Page margins<br />
Headers and footers.<br />
The procedure for defining page formats differs from other forms of formatting.<br />
Whereas cell, paragraph, and character elements can be formatted directly, page<br />
formats can also be defined and indirectly applied using page styles. For example,<br />
headers or footers are added to the page style.<br />
The following sections describe the main formatting options for spreadsheet pages.<br />
Many of the styles that are described are also available for text documents. The page<br />
properties that are valid for both types of documents are defined in the<br />
com.sun.star.style.PageProperties service. The page properties that only apply to<br />
spreadsheet documents are defined in the com.sun.star.sheet.TablePageStyle<br />
service.<br />
Note – The page properties (page margins, borders, and so on) for a Microsoft<br />
Office document are defined by means of a PageSetup object at the Worksheet object<br />
(Excel) or Document object (Word) level. In <strong>OpenOffice</strong>.<strong>org</strong>, these properties are<br />
defined using a page style which in turn is linked to the associated document.<br />
Page Background<br />
The com.sun.star.style.PageProperties service defines the following properties of a<br />
pages background:<br />
Chapter 7 · Spreadsheet Documents 151
Formatting Spreadsheet Documents<br />
BackColor (long)<br />
color of background<br />
BackGraphicURL (String)<br />
URL of the background graphics that you want to use<br />
BackGraphicFilter (String)<br />
name of the filter for interpreting the background graphics<br />
BackGraphicLocation (Enum)<br />
position of the background graphics (value according to enumeration)<br />
BackTransparent (Boolean)<br />
makes the background transparent<br />
Page Format<br />
The page format is defined using the following properties of the<br />
com.sun.star.style.PageProperties service:<br />
IsLandscape (Boolean)<br />
landscape format<br />
Width (long)<br />
width of page in hundredths of a millimeter<br />
Height (long)<br />
height of page in hundredths of a millimeter<br />
PrinterPaperTray (String)<br />
name of the printer paper tray that you want to use<br />
The following example sets the page size of the "Default" page style to the DIN A5<br />
landscape format (height 14.8 cm, width 21 cm):<br />
Dim Doc As Object<br />
Dim Sheet As Object<br />
Dim StyleFamilies As Object<br />
Dim PageStyles As Object<br />
Dim DefPage As Object<br />
Doc = StarDesktop.CurrentComponent<br />
StyleFamilies = Doc.StyleFamilies<br />
PageStyles = StyleFamilies.getByName("PageStyles")<br />
DefPage = PageStyles.getByName("Default")<br />
152 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
DefPage.IsLandscape = True<br />
DefPage.Width = 21000<br />
DefPage.Height = 14800<br />
Page Margin, Border, and Shadow<br />
Formatting Spreadsheet Documents<br />
The com.sun.star.style.PageProperties service provides the following properties for<br />
adjusting page margins as well as borders and shadows:<br />
LeftMargin (long)<br />
width of the left hand page margin in hundredths of a millimeter<br />
RightMargin (long)<br />
width of the right hand page margin in hundredths of a millimeter<br />
TopMargin (long)<br />
width of the top page margin in hundredths of a millimeter<br />
BottomMargin (long)<br />
width of the bottom page margin in hundredths of a millimeter<br />
LeftBorder (struct)<br />
specifications for left-hand line of page border (com.sun.star.table.BorderLine<br />
structure)<br />
RightBorder (struct)<br />
specifications for right-hand line of page border (com.sun.star.table.BorderLine<br />
structure)<br />
TopBorder (struct)<br />
specifications for top line of page border (com.sun.star.table.BorderLine<br />
structure)<br />
BottomBorder (struct)<br />
specifications for bottom line of page border (com.sun.star.table.BorderLine<br />
structure)<br />
LeftBorderDistance (long)<br />
distance between left-hand page border and page content in hundredths of a<br />
millimeter<br />
RightBorderDistance (long)<br />
distance between right-hand page border and page content in hundredths of a<br />
millimeter<br />
Chapter 7 · Spreadsheet Documents 153
Formatting Spreadsheet Documents<br />
TopBorderDistance (long)<br />
distance between top page border and page content in hundredths of a<br />
millimeter<br />
BottomBorderDistance (long)<br />
distance between bottom page border and page content in hundredths of a<br />
millimeter<br />
ShadowFormat (struct)<br />
specifications for shadow of content area of page<br />
(com.sun.star.table.ShadowFormat structure)<br />
The following example sets the left and right-hand borders of the "Default" page style<br />
to 1 centimeter.<br />
Dim Doc As Object<br />
Dim Sheet As Object<br />
Dim StyleFamilies As Object<br />
Dim PageStyles As Object<br />
Dim DefPage As Object<br />
Doc = StarDesktop.CurrentComponent<br />
StyleFamilies = Doc.StyleFamilies<br />
PageStyles = StyleFamilies.getByName("PageStyles")<br />
DefPage = PageStyles.getByName("Default")<br />
DefPage.LeftMargin = 1000<br />
DefPage.RightMargin = 1000<br />
Headers and Footers<br />
The headers and footers of a document form part of the page properties and are<br />
defined using the com.sun.star.style.PageProperties service. The properties for<br />
formatting headers are:<br />
HeaderIsOn (Boolean)<br />
header is activated<br />
HeaderLeftMargin (long)<br />
distance between header and left-hand page margin in hundredths of a<br />
millimeter<br />
HeaderRightMargin (long)<br />
distance between header and right-hand page margin in hundredths of a<br />
millimeter<br />
154 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
HeaderBodyDistance (long)<br />
Formatting Spreadsheet Documents<br />
distance between header and main body of document in hundredths of a<br />
millimeter<br />
HeaderHeight (long)<br />
height of header in hundredths of a millimeter<br />
HeaderIsDynamicHeight (Boolean)<br />
height of header is automatically adapted to content<br />
HeaderLeftBorder (struct)<br />
details of the left-hand border of frame around header<br />
(com.sun.star.table.BorderLine structure)<br />
HeaderRightBorder (struct)<br />
details of the right-hand border of frame around header<br />
(com.sun.star.table.BorderLine structure)<br />
HeaderTopBorder (struct)<br />
details of the top line of the border around header<br />
(com.sun.star.table.BorderLine structure)<br />
HeaderBottomBorder (struct)<br />
details of the bottom line of the border around header<br />
(com.sun.star.table.BorderLine structure)<br />
HeaderLeftBorderDistance (long)<br />
distance between left-hand border and content of header in hundredths of a<br />
millimeter<br />
HeaderRightBorderDistance (long)<br />
distance between right-hand border and content of header in hundredths of a<br />
millimeter<br />
HeaderTopBorderDistance (long)<br />
distance between top border and content of header in hundredths of a<br />
millimeter<br />
HeaderBottomBorderDistance (long)<br />
distance between bottom border and content of header in hundredths of a<br />
millimeter<br />
HeaderIsShared (Boolean)<br />
headers on even and odd pages have the same content (refer to HeaderText ,<br />
HeaderTextLeft, and HeaderTextRight )<br />
Chapter 7 · Spreadsheet Documents 155
Formatting Spreadsheet Documents<br />
HeaderBackColor (long)<br />
background color of header<br />
HeaderBackGraphicURL (String)<br />
URL of the background graphics that you want to use<br />
HeaderBackGraphicFilter (String)<br />
name of the filter for interpreting the background graphics for the header<br />
HeaderBackGraphicLocation (Enum)<br />
position of the background graphics for the header (value according to<br />
com.sun.star.style.GraphicLocation enumeration)<br />
HeaderBackTransparent (Boolean)<br />
shows the background of the header as transparent<br />
HeaderShadowFormat (struct)<br />
details of shadow of header (com.sun.star.table.ShadowFormat structure)<br />
The properties for formatting footers are:<br />
FooterIsOn (Boolean)<br />
footer is activated<br />
FooterLeftMargin (long)<br />
distance between footer and left-hand page margin in hundredths of a<br />
millimeter<br />
FooterRightMargin (long)<br />
distance between footer and right-hand page margin in hundredths of a<br />
millimeter<br />
FooterBodyDistance (long)<br />
distance between footer and main body of document in hundredths of a<br />
millimeter<br />
FooterHeight (long)<br />
height of footer in hundredths of a millimeter<br />
FooterIsDynamicHeight (Boolean)<br />
height of footer is adapted automatically to the content<br />
FooterLeftBorder (struct)<br />
details of left-hand line of border around footer (com.sun.star.table.BorderLine<br />
structure)<br />
156 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
FooterRightBorder (struct)<br />
Formatting Spreadsheet Documents<br />
details of right-hand line of border around footer (com.sun.star.table.BorderLine<br />
structure)<br />
FooterTopBorder (struct)<br />
details of top line of border around footer (com.sun.star.table.BorderLine<br />
structure)<br />
FooterBottomBorder (struct)<br />
details of bottom line of border around footer (com.sun.star.table.BorderLine<br />
structure)<br />
FooterLeftBorderDistance (long)<br />
distance between left-hand border and content of footer in hundredths of a<br />
millimeter<br />
FooterRightBorderDistance (long)<br />
distance between right-hand border and content of footer in hundredths of a<br />
millimeter<br />
FooterTopBorderDistance (long)<br />
distance between top border and content of footer in hundredths of a millimeter<br />
FooterBottomBorderDistance (long)<br />
distance between bottom border and content of footer in hundredths of a<br />
millimeter<br />
FooterIsShared (Boolean)<br />
the footers on the even and odd pages have the same content (refer to<br />
FooterText, FooterTextLeft, and FooterTextRight )<br />
FooterBackColor (long)<br />
background color of footer<br />
FooterBackGraphicURL (String)<br />
URL of the background graphics that you want to use<br />
FooterBackGraphicFilter (String)<br />
name of the filter for interpreting the background graphics for the footer<br />
FooterBackGraphicLocation (Enum)<br />
position of background graphics for the footer (value according to<br />
com.sun.star.style.GraphicLocation enumeration)<br />
Chapter 7 · Spreadsheet Documents 157
Formatting Spreadsheet Documents<br />
FooterBackTransparent (Boolean)<br />
shows the background of the footer as transparent<br />
FooterShadowFormat (struct)<br />
details of shadow of footer (com.sun.star.table.ShadowFormat structure)<br />
Changing the Text of Headers and Footers<br />
The content of headers and footers in a spreadsheet is accessed through the<br />
following properties:<br />
LeftPageHeaderContent (Object)<br />
content of headers for even pages (com.sun.star.sheet.HeaderFooterContent<br />
service)<br />
RightPageHeaderContent (Object)<br />
content of headers for odd pages (com.sun.star.sheet.HeaderFooterContent<br />
service)<br />
LeftPageFooterContent (Object)<br />
content of footers for even pages (com.sun.star.sheet.HeaderFooterContent<br />
service)<br />
RightPageFooterContent (Object)<br />
content of footers for odd pages (com.sun.star.sheet.HeaderFooterContent<br />
service)<br />
If you do not need to distinguish between headers or footers for odd and even pages<br />
(the FooterIsShared property is False), then set the properties for headers and<br />
footers on odd pages.<br />
All the named objects return an object that supports the<br />
com.sun.star.sheet.HeaderFooterContent service. By means of the (non-genuine)<br />
properties LeftText, CenterText, and RightText, this service provides three text<br />
elements for the headers and footers of <strong>OpenOffice</strong>.<strong>org</strong> Calc.<br />
The following example writes the "Just a Test." value in the left-hand text field of the<br />
header from the "Default" template.<br />
Dim Doc As Object<br />
Dim Sheet As Object<br />
Dim StyleFamilies As Object<br />
Dim PageStyles As Object<br />
Dim DefPage As Object<br />
Dim HText As Object<br />
158 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Dim HContent As Object<br />
Doc = StarDesktop.CurrentComponent<br />
StyleFamilies = Doc.StyleFamilies<br />
PageStyles = StyleFamilies.getByName("PageStyles")<br />
DefPage = PageStyles.getByName("Default")<br />
DefPage.HeaderIsOn = True<br />
HContent = DefPage.RightPageHeaderContent<br />
HText = HContent.LeftText<br />
HText.String = "Just a Test."<br />
DefPage.RightPageHeaderContent = HContent<br />
Formatting Spreadsheet Documents<br />
Note the last line in the example: Once the text is changed, the TextContent object<br />
must be assigned to the header again so that the change is effective.<br />
Another mechanism for changing the text of headers and footers is available for text<br />
documents (<strong>OpenOffice</strong>.<strong>org</strong> Writer) because these consist of a single block of text.<br />
The following properties are defined in the com.sun.star.style.PageProperties service:<br />
HeaderText (Object)<br />
text object with content of the header (com.sun.star.text.XText service)<br />
HeaderTextLeft (Object)<br />
text object with content of headers on left-hand pages (com.sun.star.text.XText<br />
service)<br />
HeaderTextRight (Object)<br />
text object with content of headers on right-hand pages (com.sun.star.text.XText<br />
service)<br />
FooterText (Object)<br />
text object with content of the footer (com.sun.star.text.XText service)<br />
FooterTextLeft (Object)<br />
text object with content of footers on left-hand pages (com.sun.star.text.XText<br />
service)<br />
FooterTextRight (Object)<br />
text object with content of footers on right-hand pages (com.sun.star.text.XText<br />
service)<br />
The following example creates a header in the "Default" page style for text<br />
documents and adds the text "Just a Test" to the header.<br />
Dim Doc As Object<br />
Dim Sheet As Object<br />
Dim StyleFamilies As Object<br />
Dim PageStyles As Object<br />
Dim DefPage As Object<br />
Dim HText As Object<br />
Chapter 7 · Spreadsheet Documents 159
Formatting Spreadsheet Documents<br />
Doc = StarDesktop.CurrentComponent<br />
StyleFamilies = Doc.StyleFamilies<br />
PageStyles = StyleFamilies.getByName("PageStyles")<br />
DefPage = PageStyles.getByName("Default")<br />
DefPage.HeaderIsOn = True<br />
HText = DefPage.HeaderText<br />
HText.String = "Just a Test."<br />
In this instance, access is provided directly through the HeaderText property of the<br />
page style rather than the HeaderFooterContent object.<br />
Centering (Spreadsheets Only)<br />
The com.sun.star.sheet.TablePageStyle service is only used in <strong>OpenOffice</strong>.<strong>org</strong> Calc<br />
page styles and allows cell ranges that you want to printed to be centered on the<br />
page. This service provides the following properties:<br />
CenterHorizontally (Boolean)<br />
table content is centered horizontally<br />
CenterVertically (Boolean)<br />
table content is centered vertically<br />
Definition of Elements to be Printed (Spreadsheets<br />
Only)<br />
When you format sheets, you can define whether page elements are visible. For this<br />
purpose, the com.sun.star.sheet.TablePageStyle service provides the following<br />
properties:<br />
PrintAnnotations (Boolean)<br />
prints cell comments<br />
PrintGrid (Boolean)<br />
prints the cell gridlines<br />
PrintHeaders (Boolean)<br />
prints the row and column headings<br />
160 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
PrintCharts (Boolean)<br />
prints charts contained in a sheet<br />
PrintObjects (Boolean)<br />
prints embedded objects<br />
PrintDrawing (Boolean)<br />
prints draw objects<br />
PrintDownFirst (Boolean)<br />
Formatting Spreadsheet Documents<br />
if the contents of a sheet extend across several pages, they are first printed in<br />
vertically descending order, and then down the right-hand side.<br />
PrintFormulas (Boolean)<br />
prints the formulas instead of the calculated values<br />
PrintZeroValues (Boolean)<br />
prints the zero values<br />
Editing Spreadsheet Documents<br />
Whereas the previous section described the main structure of spreadsheet<br />
documents, this section describes the services that allow you to easily access<br />
individual cells or cell ranges.<br />
Cell Ranges<br />
In addition to an object for individual cells (com.sun.star.table.Cell service),<br />
<strong>OpenOffice</strong>.<strong>org</strong> also provides objects that represent cell ranges. Such CellRange<br />
objects are created using the getCellRangeByName call of the spreadsheet object:<br />
Dim Doc As Object<br />
Dim Sheet As Object<br />
Dim CellRange As Object<br />
Doc = StarDesktop.CurrentComponent<br />
Sheet = Doc.Sheets.getByName("Sheet 1")<br />
CellRange = Sheet.getCellRangeByName("A1:C15")<br />
A colon (:) is used to specify a cell range in a spreadsheet document. For example,<br />
Chapter 7 · Spreadsheet Documents 161
Cell Ranges<br />
A1:C15 represents all the cells in rows 1 to 15 in columns A, B, and C.<br />
The location of individual cells in a cell range can be determined using the<br />
getCellByPosition method, where the coordinates of the top left cell in the cell range<br />
is (0, 0). The following example uses this method to create an object of cell C3.<br />
Dim Doc As Object<br />
Dim Sheet As Object<br />
Dim CellRange As Object<br />
Dim Cell As Object<br />
Doc = StarDesktop.CurrentComponent<br />
Sheet = Doc.Sheets.getByName("Sheet 1")<br />
CellRange = Sheet.getCellRangeByName("B2:D4")<br />
Cell = CellRange.GetCellByPosition(1, 1)<br />
Formatting Cell Ranges<br />
Just like individual cells, you can apply formatting to cell ranges using the<br />
com.sun.star.table.CellProperties service. For more information and examples of this<br />
service, see Formatting Spreadsheet Documents.<br />
Computing With Cell Ranges<br />
You can use the computeFunction method to perform mathematical operations on cell<br />
ranges. The computeFunction expects a constant as the parameter that describes the<br />
mathematical function that you want to use. The associated constants are defined in<br />
the com.sun.star.sheet.GeneralFunction enumeration. The following values are<br />
available:<br />
SUM<br />
COUNT<br />
COUNTNUMS<br />
AVERAGE<br />
MAX<br />
sum of all numerical values<br />
total number of all values (including non-numerical values)<br />
total number of all numerical values<br />
average of all numerical values<br />
largest numerical value<br />
162 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
MIN<br />
PRODUCT<br />
STDEV<br />
VAR<br />
STDEVP<br />
VARP<br />
smallest numerical value<br />
product of all numerical values<br />
standard deviation<br />
variance<br />
standard deviation based on the total population<br />
variance based on the total population<br />
Cell Ranges<br />
The following example computes the average value of the A1:C3 range and prints the<br />
result in a message box:<br />
Dim Doc As Object<br />
Dim Sheet As Object<br />
Dim CellRange As Object<br />
Doc = StarDesktop.CurrentComponent<br />
Sheet = Doc.Sheets.getByName("Sheet 1")<br />
CellRange = Sheet.getCellRangeByName("A1:C3")<br />
MsgBox CellRange.computeFunction(com.sun.star.sheet.GeneralFunction.AVERAGE)<br />
Deleting Cell Contents<br />
The clearContents method simplifies the process of deleting cell contents and cell<br />
ranges in that it deletes one specific type of content from a cell range.<br />
The following example removes all the strings and the direct formatting information<br />
from the B2:C3 range.<br />
Dim Doc As Object<br />
Dim Sheet As Object<br />
Dim CellRange As Object<br />
Dim Flags As Long<br />
Doc = StarDesktop.CurrentComponent<br />
Sheet = Doc.Sheets(0)<br />
CellRange = Sheet.getCellRangeByName("B2:C3")<br />
Chapter 7 · Spreadsheet Documents 163
Cell Ranges<br />
Flags = com.sun.star.sheet.CellFlags.STRING + _<br />
com.sun.star.sheet.CellFlags.HARDATTR<br />
CellRange.clearContents(Flags)<br />
The flags specified in clearContents come from the com.sun.star.sheet.CellFlags<br />
constants list. This list provides the following elements:<br />
VALUE<br />
DATETIME<br />
STRING<br />
numerical values that are not formatted as date or time<br />
numerical values that are formatted as date or time<br />
strings<br />
ANNOTATION<br />
FORMULA<br />
HARDATTR<br />
STYLES<br />
OBJECTS<br />
EDITATTR<br />
comments that are linked to cells<br />
formulas<br />
direct formatting of cells<br />
indirect formatting<br />
drawing objects that are connected to cells<br />
character formatting that only applies to parts of the cells<br />
You can also add the constants together to delete different information using a call<br />
from clearContents.<br />
Searching and Replacing Cell Contents<br />
Spreadsheet documents, like text documents, provide a function for searching and<br />
replacing.<br />
164 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Searching and Replacing Cell Contents<br />
The descriptor objects for searching and replacing in spreadsheet documents are not<br />
created directly through the document object, but rather through the Sheets list. The<br />
following is an example of a search and replace process:<br />
Dim Doc As Object<br />
Dim Sheet As Object<br />
Dim ReplaceDescriptor As Object<br />
Dim I As Integer<br />
Doc = StarDesktop.CurrentComponent<br />
Sheet = Doc.Sheets(0)<br />
ReplaceDescriptor = Sheet.createReplaceDescriptor()<br />
ReplaceDescriptor.SearchString = "is"<br />
ReplaceDescriptor.ReplaceString = "was"<br />
For I = 0 to Doc.Sheets.Count - 1<br />
Sheet = Doc.Sheets(I)<br />
Sheet.ReplaceAll(ReplaceDescriptor)<br />
Next I<br />
This example uses the first page of the document to create a ReplaceDescriptor and<br />
then applies this to all pages in a loop.<br />
Chapter 7 · Spreadsheet Documents 165
8<br />
C H A P T E R 8<br />
8 Drawings and Presentations<br />
This chapter provides an introduction to the macro-controlled creation and editing of<br />
drawings and presentations.<br />
The first section describes the structure of drawings, including the basic elements<br />
that contain drawings. The second section addresses more complex editing<br />
functions, such as grouping, rotating, and scaling objects. The third section deals with<br />
presentations.<br />
Information about creating, opening, and saving drawings can be found in Working<br />
With Documents.<br />
The Structure of Drawings<br />
<strong>OpenOffice</strong>.<strong>org</strong> does not limit the number of pages in a drawing document. You can<br />
design each page separately. There is also no limit to the number of drawing<br />
elements that you can add to a page.<br />
167
Pages<br />
Pages<br />
The pages of a drawing document are available through the DrawPages list. You can<br />
access individual pages either through their number or their name. If a document has<br />
one page and this is called Slide 1, then the following examples are identical.<br />
Example 1:<br />
Dim Doc As Object<br />
Dim Page As Object<br />
Doc = StarDesktop.CurrentComponent<br />
Page = Doc.drawPages(0)<br />
Example 2:<br />
Dim Doc As Object<br />
Dim Page As Object<br />
Doc = StarDesktop.CurrentComponent<br />
Page = Doc.drawPages.getByName("Slide 1")<br />
In Example 1, the page is addressed by its number (counting begins at 0). In the<br />
second example, the page is accessed by its name and the getByName method.<br />
Dim sUrl As String, sFilter As String<br />
Dim sOptions As String<br />
Dim oSheets As Object, oSheet As Object<br />
oSheets = oDocument.Sheets<br />
If oSheets.hasByName("Link") Then<br />
oSheet = oSheets.getByName("Link")<br />
Else<br />
oSheet = oDocument.createInstance("com.sun.star.sheet.Spreadsheet")<br />
oSheets.insertByName("Link", oSheet)<br />
oSheet.IsVisible = False<br />
End If<br />
The preceding call returns a page object that supports the<br />
com.sun.star.drawing.DrawPage service. The service recognizes the following<br />
properties:<br />
BorderLeft (Long)<br />
left-hand border in hundredths of a millimeter<br />
BorderRight (Long)<br />
right-hand border in hundredths of a millimeter<br />
BorderTop (Long)<br />
top border in hundredths of a millimeter<br />
168 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
BorderBottom (Long)<br />
bottom border in hundredths of a millimeter<br />
Width (Long)<br />
page width in hundredths of a millimeter<br />
Height (Long)<br />
page height in hundredths of a millimeter<br />
Number (Short)<br />
number of pages (numbering begins at 1), read-only<br />
Orientation (Enum)<br />
page orientation (in accordance with com.sun.star.view.PaperOrientation<br />
enumeration)<br />
If these settings are changed, then all of the pages in the document are affected.<br />
Pages<br />
The following example sets the page size of a drawing document which has just been<br />
opened to 20 x 20 centimeters with a page margin of 0.5 centimeters:<br />
Dim Doc As Object<br />
Dim Page As Object<br />
Doc = StarDesktop.CurrentComponent<br />
Page = Doc.drawPages(0)<br />
Page.BorderLeft = 500<br />
Page.BorderRight = 500<br />
Page.BorderTop = 500<br />
Page.BorderBottom = 500<br />
Page.Width = 20000<br />
Page.Height = 20000<br />
Elementary Properties of Drawing<br />
Objects<br />
Drawing objects include shapes (rectangles, circles, and so on), lines, and text<br />
objects. All of these share a number of common features and support the<br />
com.sun.star.drawing.Shape service. This service defines the Size and Position<br />
properties of a drawing object.<br />
<strong>OpenOffice</strong>.<strong>org</strong> Basic also offers several other services through which you can<br />
Chapter 8 · Drawings and Presentations 169
Elementary Properties of Drawing Objects<br />
modify such properties, as formatting or apply fills. The formatting options that are<br />
available depend on the type of drawing object.<br />
The following example creates and inserts a rectangle in a drawing document:<br />
Dim Doc As Object<br />
Dim Page As Object<br />
Dim RectangleShape As Object<br />
Dim Point As New com.sun.star.awt.Point<br />
Dim Size As New com.sun.star.awt.Size<br />
Doc = StarDesktop.CurrentComponent<br />
Page = Doc.drawPages(0)<br />
Point.x = 1000<br />
Point.y = 1000<br />
Size.Width = 10000<br />
Size.Height = 10000<br />
RectangleShape = Doc.createInstance("com.sun.star.drawing.RectangleShape")<br />
RectangleShape.Size = Size<br />
RectangleShape.Position = Point<br />
Page.add(RectangleShape)<br />
This example uses the StarDesktop.CurrentComponent call to determine which<br />
document is open. The document object determined this way returns the first page of<br />
the drawing through the drawPages(0) call.<br />
The Point and Size structures with the point of origin (left hand corner) and the size<br />
of the drawing object are then initialized. The lengths are specified in hundredths of a<br />
millimeter.<br />
The program code then uses the Doc.createInstance call to create the rectangle<br />
drawing object as specified by the com.sun.star.drawing.RectangleShape service. At<br />
the end, the drawing object is assigned to a page using a Page.add call.<br />
Fill Properties<br />
This section describes four services and in each instance the sample program code<br />
uses a rectangle shape element that combines several types of formatting. Fill<br />
properties are combined in the com.sun.star.drawing.FillProperties service.<br />
<strong>OpenOffice</strong>.<strong>org</strong> recognizes four main types of formatting for a fill area. The simplest<br />
variant is a single-color fill. The options for defining color gradients and hatches let<br />
you create other colors into play. The fourth variant is the option of projecting existing<br />
graphics into the fill area.<br />
170 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Elementary Properties of Drawing Objects<br />
The fill mode of a drawing object is defined using the FillStyle property. The<br />
permissible values are defined in com.sun.star.drawing.FillStyle.<br />
Single Color Fills<br />
The main property for single-color fills is:<br />
FillColor (Long)<br />
fill color of area<br />
To use the fill mode, you must the FillStyle property to the SOLID fill mode.<br />
The following example creates a rectangle shape and fills it with red (RGB value 255,<br />
0, 0):<br />
Dim Doc As Object<br />
Dim Page As Object<br />
Dim RectangleShape As Object<br />
Dim Point As New com.sun.star.awt.Point<br />
Dim Size As New com.sun.star.awt.Size<br />
Point.x = 1000<br />
Point.y = 1000<br />
Size.Width = 10000<br />
Size.Height = 10000<br />
Doc = StarDesktop.CurrentComponent<br />
Page = Doc.drawPages(0)<br />
RectangleShape = Doc.createInstance("com.sun.star.drawing.RectangleShape")<br />
RectangleShape.Size = Size<br />
RectangleShape.Position = Point<br />
RectangleShape.FillStyle = com.sun.star.drawing.FillStyle.SOLID<br />
RectangleShape.FillColor = RGB(255,0,0)<br />
Page.add(RectangleShape)<br />
Color Gradient<br />
If you set the FillStyle property to GRADIENT, you can apply a color gradient to any<br />
fill area of a <strong>OpenOffice</strong>.<strong>org</strong> document.<br />
If you want to apply a predefined color gradient, you can assign the associated name<br />
of the FillTransparenceGradientName property. To define your own color gradient,<br />
you need to complete a com.sun.star.awt.Gradient structure to assign the<br />
FillGradient property. This property provides the following options:<br />
Chapter 8 · Drawings and Presentations 171
Elementary Properties of Drawing Objects<br />
Style (Enum)<br />
type of gradient, for example, linear or radial (default values in accordance with<br />
com.sun.star.awt.GradientStyle)<br />
StartColor (Long)<br />
start color of color gradient<br />
EndColor (Long)<br />
end color of color gradient<br />
Angle (Short)<br />
angle of color gradient in tenths of a degree<br />
XOffset (Short)<br />
X-coordinate at which the color gradient starts, specified in hundredths of a<br />
millimeter<br />
YOffset (Short)<br />
Y-coordinate at which the color gradient begins, specified in hundredths of a<br />
millimeter<br />
StartIntensity (Short)<br />
intensity of StartColor as a percentage (in <strong>OpenOffice</strong>.<strong>org</strong> Basic, you can also<br />
specify values higher than 100 percent)<br />
EndIntensity (Short)<br />
intensity of EndColor as a percentage (in <strong>OpenOffice</strong>.<strong>org</strong> Basic, you can also<br />
specify values higher than 100 percent)<br />
StepCount (Short)<br />
number of color graduations which <strong>OpenOffice</strong>.<strong>org</strong> is to calculate for the<br />
gradients<br />
The following example demonstrates the use of color gradients with the aid of the<br />
com.sun.star.awt.Gradient structure:<br />
Dim Doc As Object<br />
Dim Page As Object<br />
Dim RectangleShape As Object<br />
Dim Point As New com.sun.star.awt.Point<br />
Dim Size As New com.sun.star.awt.Size<br />
Dim Gradient As New com.sun.star.awt.Gradient<br />
Point.x = 1000<br />
Point.y = 1000<br />
Size.Width = 10000<br />
Size.Height = 10000<br />
172 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Doc = StarDesktop.CurrentComponent<br />
Page = Doc.drawPages(0)<br />
Elementary Properties of Drawing Objects<br />
RectangleShape = Doc.createInstance("com.sun.star.drawing.RectangleShape")<br />
RectangleShape.Size = Size<br />
RectangleShape.Position = Point<br />
Gradient.Style = com.sun.star.awt.GradientStyle.LINEAR<br />
Gradient.StartColor = RGB(255,0,0)<br />
Gradient.EndColor = RGB(0,255,0)<br />
Gradient.StartIntensity = 150<br />
Gradient.EndIntensity = 150<br />
Gradient.Angle = 450<br />
Gradient.StepCount = 100<br />
RectangleShape.FillStyle = com.sun.star.drawing.FillStyle.GRADIENT<br />
RectangleShape.FillGradient = Gradient<br />
Page.add(RectangleShape)<br />
This example creates a linear color gradient (Style = LINEAR). The gradient starts<br />
with red (StartColor) in the top left corner, and extends at a 45 degree angle (Angle)<br />
to green (EndColor) in the bottom right corner. The color intensity of the start and end<br />
colors is 150 percent (StartIntensity and EndIntensity) which results in the colors<br />
seeming brighter than the values specified in the StartColor and EndColor<br />
properties. The color gradient is depicted using a hundred graduated individual colors<br />
(StepCount).<br />
Hatches<br />
To create a hatch fill, the FillStyle property must be set to HATCH. The program code<br />
for defining the hatch is very similar to the code for color gradients. Again an auxiliary<br />
structure, in this case com.sun.star.drawing.Hatch, is used to define the appearance<br />
of hatches. The structure for hatches has the following properties:<br />
Style (Enum)<br />
type of hatch: simple, squared, or squared with diagonals (default values in<br />
accordance with com.sun.star.awt.HatchStyle)<br />
Color (Long)<br />
color of lines<br />
Distance (Long)<br />
distance between lines in hundredths of a millimeter<br />
Angle (Short)<br />
angle of hatch in tenths of a degree<br />
Chapter 8 · Drawings and Presentations 173
Elementary Properties of Drawing Objects<br />
The following example demonstrates the use of a hatch structure:<br />
Dim Doc As Object<br />
Dim Page As Object<br />
Dim RectangleShape As Object<br />
Dim Point As New com.sun.star.awt.Point<br />
Dim Size As New com.sun.star.awt.Size<br />
Dim Hatch As New com.sun.star.drawing.Hatch<br />
Point.x = 1000<br />
Point.y = 1000<br />
Size.Width = 10000<br />
Size.Height = 10000<br />
Doc = StarDesktop.CurrentComponent<br />
Page = Doc.drawPages(0)<br />
RectangleShape = Doc.createInstance("com.sun.star.drawing.RectangleShape")<br />
RectangleShape.Size = Size<br />
RectangleShape.Position = Point<br />
RectangleShape.FillStyle = com.sun.star.drawing.FillStyle.HATCH<br />
Hatch.Style = com.sun.star.drawing.HatchStyle.SINGLE<br />
Hatch.Color = RGB(64,64,64)<br />
Hatch.Distance = 20<br />
Hatch.Angle = 450<br />
RectangleShape.FillHatch = Hatch<br />
Page.add(RectangleShape)<br />
This code creates a simple hatch structure (HatchStyle = SINGLE) whose lines are<br />
rotated 45 degrees (Angle). The lines are dark gray (Color) and are spaced is 0.2<br />
millimeters (Distance) apart.<br />
Bitmaps<br />
To use bitmap projection as a fill, you must set the FillStyle property to BITMAP. If<br />
the bitmap is already available in <strong>OpenOffice</strong>.<strong>org</strong>, you just need to specify its name in<br />
the FillBitMapName property and its display style (simple, tiled, or elongated) in the<br />
FillBitmapMode property (default values in accordance with<br />
com.sun.star.drawing.BitmapMode).<br />
If you want to use an external bitmap file, you can specify its URL in the<br />
FillBitmapURL property.<br />
The following example creates a rectangle and tiles the Sky bitmap that is available in<br />
<strong>OpenOffice</strong>.<strong>org</strong> to fill the area of the rectangle:<br />
Dim Doc As Object<br />
174 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Dim Page As Object<br />
Dim RectangleShape As Object<br />
Dim Point As New com.sun.star.awt.Point<br />
Dim Size As New com.sun.star.awt.Size<br />
Point.x = 1000<br />
Point.y = 1000<br />
Size.Width = 10000<br />
Size.Height = 10000<br />
Doc = StarDesktop.CurrentComponent<br />
Page = Doc.drawPages(0)<br />
Elementary Properties of Drawing Objects<br />
RectangleShape = Doc.createInstance("com.sun.star.drawing.RectangleShape")<br />
RectangleShape.Size = Size<br />
RectangleShape.Position = Point<br />
RectangleShape.FillStyle = com.sun.star.drawing.FillStyle.BITMAP<br />
RectangleShape.FillBitmapName = "Sky"<br />
RectangleShape.FillBitmapMode = com.sun.star.drawing.BitmapMode.REPEAT<br />
Page.add(RectangleShape)<br />
Transparency<br />
You can adjust the transparency of any fill that you apply. The simplest way to change<br />
the transparency of a drawing element is to use the FillTransparence property.<br />
The following example creates a red rectangle with a transparency of 50 percent.<br />
Dim Doc As Object<br />
Dim Page As Object<br />
Dim RectangleShape As Object<br />
Dim Point As New com.sun.star.awt.Point<br />
Dim Size As New com.sun.star.awt.Size<br />
Point.x = 1000<br />
Point.y = 1000<br />
Size.Width = 10000<br />
Size.Height = 10000<br />
Doc = StarDesktop.CurrentComponent<br />
Page = Doc.drawPages(0)<br />
RectangleShape = Doc.createInstance("com.sun.star.drawing.RectangleShape")<br />
RectangleShape.Size = Size<br />
RectangleShape.Position = Point<br />
RectangleShape.FillStyle = com.sun.star.drawing.FillStyle.SOLID<br />
RectangleShape.FillTransparence = 50<br />
RectangleShape.FillColor = RGB(255,0,0)<br />
Page.add(RectangleShape)<br />
Chapter 8 · Drawings and Presentations 175
Elementary Properties of Drawing Objects<br />
To make the fill transparent, set the FillTransparence property to 100.<br />
In addition to the FillTransparence property, the com.sun.star.drawing.FillProperties<br />
service also provides the FillTransparenceGradient property. This is used to define<br />
a gradient that specifies the transparency of a fill area.<br />
Line Properties<br />
All drawing objects that can have a border line support the<br />
com.sun.star.drawing.LineStyle service. Some of the properties that this service<br />
provides are:<br />
LineStyle (Enum)<br />
line type (default values in accordance with com.sun.star.drawing.LineStyle)<br />
LineColor (Long)<br />
line color<br />
LineTransparence (Short)<br />
line transparency<br />
LineWidth (Long)<br />
line thickness in hundredths of a millimeter<br />
LineJoint (Enum)<br />
transitions to connection points (default values in accordance with<br />
com.sun.star.drawing.LineJoint)<br />
The following example creates a rectangle with a solid border (LineStyle = SOLID)<br />
that is 5 millimeters thick (LineWidth) and 50 percent transparent. The right and lefthand<br />
edges of the line extend to their points of intersect with each other (LineJoint =<br />
MITER) to form a right-angle.<br />
Dim Doc As Object<br />
Dim Page As Object<br />
Dim RectangleShape As Object<br />
Dim Point As New com.sun.star.awt.Point<br />
Dim Size As New com.sun.star.awt.Size<br />
Point.x = 1000<br />
Point.y = 1000<br />
Size.Width = 10000<br />
Size.Height = 10000<br />
Doc = StarDesktop.CurrentComponent<br />
Page = Doc.drawPages(0)<br />
176 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Elementary Properties of Drawing Objects<br />
RectangleShape = Doc.createInstance("com.sun.star.drawing.RectangleShape")<br />
RectangleShape.Size = Size<br />
RectangleShape.Position = Point<br />
RectangleShape.LineColor = RGB(128,128,128)<br />
RectangleShape.LineTransparence = 50<br />
RectangleShape.LineWidth = 500<br />
RectangleShape.LineJoint = com.sun.star.drawing.LineJoint.MITER<br />
RectangleShape.LineStyle = com.sun.star.drawing.LineStyle.SOLID<br />
Page.add(RectangleShape)<br />
In addition to the listed properties, the com.sun.star.drawing.LineStyle service<br />
provides options for drawing dotted and dashed lines. For more information, see the<br />
<strong>OpenOffice</strong>.<strong>org</strong> API reference.<br />
Text Properties (Drawing Objects)<br />
The com.sun.star.style.CharacterProperties and<br />
com.sun.star.style.ParagraphProperties services can format text in drawing objects.<br />
These services relate to individual characters and paragraphs and are described in<br />
detail in Text Documents.<br />
The following example inserts text in a rectangle and formats the font<br />
com.sun.star.style.CharacterProperties service.<br />
Dim Doc As Object<br />
Dim Page As Object<br />
Dim RectangleShape As Object<br />
Dim Point As New com.sun.star.awt.Point<br />
Dim Size As New com.sun.star.awt.Size<br />
Point.x = 1000<br />
Point.y = 1000<br />
Size.Width = 10000<br />
Size.Height = 10000<br />
Doc = StarDesktop.CurrentComponent<br />
Page = Doc.drawPages(0)<br />
RectangleShape = Doc.createInstance("com.sun.star.drawing.RectangleShape")<br />
RectangleShape.Size = Size<br />
RectangleShape.Position = Point<br />
Page.add(RectangleShape)<br />
RectangleShape.String = "This is a test"<br />
RectangleShape.CharWeight = com.sun.star.awt.FontWeight.BOLD<br />
RectangleShape.CharFontName = "Arial"<br />
This code uses the String-property of the rectangle to insert the text and the<br />
CharWeight and CharFontName properties from the<br />
com.sun.star.style.CharacterProperties service to format the text font.<br />
Chapter 8 · Drawings and Presentations 177
Elementary Properties of Drawing Objects<br />
The text can only be inserted after the drawing object has been added to the drawing<br />
page. You can also use the com.sun.star.drawing.Text service to position and format<br />
text in drawing object. The following are some of the important properties of this<br />
service:<br />
TextAutoGrowHeight (Boolean)<br />
adapts the height of the drawing element to the text it contains<br />
TextAutoGrowWidth (Boolean)<br />
adapts the width of the drawing element to the text it contains<br />
TextHorizontalAdjust (Enum)<br />
horizontal position of text within the drawing element (default values in<br />
accordance with com.sun.star.drawing.TextHorizontalAdjust)<br />
TextVerticalAdjust (Enum)<br />
vertical position of text within the drawing element (default values in accordance<br />
with com.sun.star.drawing.TextVerticalAdjust)<br />
TextLeftDistance (Long)<br />
left-hand distance between drawing element and text in hundredths of a<br />
millimeter<br />
TextRightDistance (Long)<br />
right-hand distance between drawing element and text in hundredths of a<br />
millimeter<br />
TextUpperDistance (Long)<br />
upper distance between drawing element and text in hundredths of a millimeter<br />
TextLowerDistance (Long)<br />
lower distance between drawing element and text in hundredths of a millimeter<br />
The following example demonstrates use of the named properties.<br />
Dim Doc As Object<br />
Dim Page As Object<br />
Dim RectangleShape As Object<br />
Dim Point As New com.sun.star.awt.Point<br />
Dim Size As New com.sun.star.awt.Size<br />
Point.x = 1000<br />
Point.y = 1000<br />
Size.Width = 10000<br />
Size.Height = 10000<br />
Doc = StarDesktop.CurrentComponent<br />
Page = Doc.drawPages(0)<br />
178 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Elementary Properties of Drawing Objects<br />
RectangleShape = Doc.createInstance("com.sun.star.drawing.RectangleShape")<br />
RectangleShape.Size = Size<br />
RectangleShape.Position = Point<br />
Page.add(RectangleShape)<br />
RectangleShape.String = "This is a test" ' May only take place after<br />
Page.add!<br />
RectangleShape.TextVerticalAdjust =<br />
com.sun.star.drawing.TextVerticalAdjust.TOP<br />
RectangleShape.TextHorizontalAdjust =<br />
com.sun.star.drawing.TextHorizontalAdjust.LEFT<br />
RectangleShape.TextLeftDistance = 300<br />
RectangleShape.TextRightDistance = 300<br />
RectangleShape.TextUpperDistance = 300<br />
RectangleShape.TextLowerDistance = 300<br />
This code inserts a drawing element in a page and then adds text to the top left<br />
corner of the drawing object using the TextVerticalAdjust and<br />
TextHorizontalAdjust properties. The minimum distance between the text edge of<br />
the drawing object is set to three millimeters.<br />
Shadow Properties<br />
You can add a shadow to most drawing objects with the<br />
com.sun.star.drawing.ShadowProperties service. The properties of this service are:<br />
Shadow (Boolean)<br />
activates the shadow<br />
ShadowColor (Long)<br />
shadow color<br />
ShadowTransparence (Short)<br />
transparency of the shadow<br />
ShadowXDistance (Long)<br />
vertical distance of the shadow from the drawing object in hundredths of a<br />
millimeter<br />
ShadowYDistance (Long)<br />
horizontal distance of the shadow from the drawing object in hundredths of a<br />
millimeter<br />
The following example creates a rectangle with a shadow that is vertically and<br />
Chapter 8 · Drawings and Presentations 179
Elementary Properties of Drawing Objects<br />
horizontally offset from the rectangle by 2 millimeters. The shadow is rendered in<br />
dark gray with 50 percent transparency.<br />
Dim Doc As Object<br />
Dim Page As Object<br />
Dim RectangleShape As Object<br />
Dim Point As New com.sun.star.awt.Point<br />
Dim Size As New com.sun.star.awt.Size<br />
Point.x = 1000<br />
Point.y = 1000<br />
Size.Width = 10000<br />
Size.Height = 10000<br />
Doc = StarDesktop.CurrentComponent<br />
Page = Doc.drawPages(0)<br />
RectangleShape = Doc.createInstance("com.sun.star.drawing.RectangleShape")<br />
RectangleShape.Size = Size<br />
RectangleShape.Position = Point<br />
RectangleShape.Shadow = True<br />
RectangleShape.ShadowColor = RGB(192,192,192)<br />
RectangleShape.ShadowTransparence = 50<br />
RectangleShape.ShadowXDistance = 200<br />
RectangleShape.ShadowYDistance = 200<br />
Page.add(RectangleShape)<br />
An Overview of Various Drawing<br />
Objects<br />
Rectangle Shapes<br />
Rectangle shape objects (com.sun.star.drawing.RectangleShape) support the<br />
following services for formatting objects:<br />
Fill properties<br />
com.sun.star.drawing.FillProperties<br />
Line properties<br />
com.sun.star.drawing.LineProperties<br />
Text properties<br />
com.sun.star.drawing.Text (with com.sun.star.style.CharacterProperties and<br />
180 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
com.sun.star.style.ParagraphProperties)<br />
Shadow properties<br />
com.sun.star.drawing.ShadowProperties<br />
CornerRadius (Long)<br />
radius for rounding corners in hundredths of a millimeter<br />
Circles and Ellipses<br />
An Overview of Various Drawing Objects<br />
The Service com.sun.star.drawing.EllipseShape service is responsible for circles and<br />
ellipses and supports the following services:<br />
Fill properties<br />
com.sun.star.drawing.FillProperties<br />
Line properties<br />
com.sun.star.drawing.LineProperties<br />
Text properties<br />
com.sun.star.drawing.Text (with com.sun.star.style.CharacterProperties and<br />
com.sun.star.style.ParagraphProperties)<br />
Shadow properties<br />
com.sun.star.drawing.ShadowProperties<br />
In addition to these services, circles and ellipses also provide these properties:<br />
CircleKind (Enum)<br />
type of circle or ellipse (default values in accordance with<br />
com.sun.star.drawing.CircleKind)<br />
CircleStartAngle (Long)<br />
start angle in tenths of a degree (only for circle or ellipse segments)<br />
CircleEndAngle (Long)<br />
end angle in tenths of a degree (only for circle or ellipse segments)<br />
The CircleKind property determines if an object is a complete circle, a circular slice,<br />
or a section of a circle. The following values are available:<br />
com.sun.star.drawing.CircleKind.FULL<br />
full circle or full ellipse<br />
Chapter 8 · Drawings and Presentations 181
An Overview of Various Drawing Objects<br />
com.sun.star.drawing.CircleKind.CUT<br />
section of circle (partial circle whose interfaces are linked directly to one<br />
another)<br />
com.sun.star.drawing.CircleKind.SECTION<br />
circle slice<br />
com.sun.star.drawing.CircleKind.ARC<br />
angle (not including circle line)<br />
The following example creates a circular slice with a 70 degree angle (produced from<br />
difference between start angle of 20 degrees and end angle of 90 degrees)<br />
Dim Doc As Object<br />
Dim Page As Object<br />
Dim EllipseShape As Object<br />
Dim Point As New com.sun.star.awt.Point<br />
Dim Size As New com.sun.star.awt.Size<br />
Point.x = 1000<br />
Point.y = 1000<br />
Size.Width = 10000<br />
Size.Height = 10000<br />
Doc = StarDesktop.CurrentComponent<br />
Page = Doc.drawPages(0)<br />
EllipseShape = Doc.createInstance("com.sun.star.drawing.EllipseShape")<br />
EllipseShape.Size = Size<br />
EllipseShape.Position = Point<br />
EllipseShape.CircleStartAngle = 2000<br />
EllipseShape.CircleEndAngle = 9000<br />
EllipseShape.CircleKind = com.sun.star.drawing.CircleKind.SECTION<br />
Page.add(EllipseShape)<br />
Lines<br />
<strong>OpenOffice</strong>.<strong>org</strong> provides the com.sun.star.drawing.LineShape service for line objects.<br />
Line objects support all of the general formatting services with the exception of areas.<br />
The following are all of the properties that are associated with the LineShape service:<br />
Line properties<br />
com.sun.star.drawing.LineProperties<br />
Text properties<br />
com.sun.star.drawing.Text (with com.sun.star.style.CharacterProperties and<br />
com.sun.star.style.ParagraphProperties)<br />
182 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Shadow properties<br />
com.sun.star.drawing.ShadowProperties<br />
An Overview of Various Drawing Objects<br />
The following example creates and formats a line with the help of the named<br />
properties. The origin of the line is specified in the Location property, whereas the<br />
coordinates listed in the Size property specify the end point of the line.<br />
Dim Doc As Object<br />
Dim Page As Object<br />
Dim LineShape As Object<br />
Dim Point As New com.sun.star.awt.Point<br />
Dim Size As New com.sun.star.awt.Size<br />
Point.x = 1000<br />
Point.y = 1000<br />
Size.Width = 10000<br />
Size.Height = 10000<br />
Doc = StarDesktop.CurrentComponent<br />
Page = Doc.drawPages(0)<br />
LineShape = Doc.createInstance("com.sun.star.drawing.LineShape")<br />
LineShape.Size = Size<br />
LineShape.Position = Point<br />
Page.add(LineShape)<br />
Polypolygon Shapes<br />
<strong>OpenOffice</strong>.<strong>org</strong> also supports complex polygonal shapes through the<br />
com.sun.star.drawing.PolyPolygonShape service. Strictly speaking, a PolyPolygon is<br />
not a simple polygon but a multiple polygon. Several independent lists containing<br />
corner points can therefore be specified and combined to form a complete object.<br />
As with rectangle shapes, all the formatting properties of drawing objects are also<br />
provided for polypolygons:<br />
Fill properties<br />
com.sun.star.drawing.FillProperties<br />
Line properties<br />
com.sun.star.drawing.LineProperties<br />
Text properties<br />
com.sun.star.drawing.Text (with com.sun.star.style.CharacterProperties and<br />
com.sun.star.style.ParagraphProperties)<br />
Chapter 8 · Drawings and Presentations 183
An Overview of Various Drawing Objects<br />
Shadow properties<br />
com.sun.star.drawing.ShadowProperties<br />
The PolyPolygonShape service also has a property that lets you define the<br />
coordinates of a polygon:<br />
PolyPolygon (Array) – field containing the coordinates of the polygon (double<br />
array with points of the com.sun.star.awt.Point type)<br />
The following example shows how you can define a triangle with the<br />
PolyPolygonShape service.<br />
Dim Doc As Object<br />
Dim Page As Object<br />
Dim PolyPolygonShape As Object<br />
Dim PolyPolygon As Variant<br />
Dim Coordinates(2) As New com.sun.star.awt.Point<br />
Doc = StarDesktop.CurrentComponent<br />
Page = Doc.drawPages(0)<br />
PolyPolygonShape = Doc.createInstance("com.sun.star.drawing.PolyPolygonShape")<br />
Page.add(PolyPolygonShape) ' Page.add must take place before the coordinates<br />
are set<br />
Coordinates(0).x = 1000<br />
Coordinates(1).x = 7500<br />
Coordinates(2).x = 10000<br />
Coordinates(0).y = 1000<br />
Coordinates(1).y = 7500<br />
Coordinates(2).y = 5000<br />
PolyPolygonShape.PolyPolygon = Array(Coordinates())<br />
Since the points of a polygon are defined as absolute values, you do not need to<br />
specify the size or the start position of a polygon. Instead, you need to create an<br />
array of the points, package this array in a second array (using the<br />
Array(Coordinates()) call), and then assign this array to the polygon. Before the<br />
corresponding call can be made, the polygon must be inserted into the document.<br />
The double array in the definition allows you to create complex shapes by merging<br />
several polygons. For example, you can create a rectangle and then insert another<br />
rectangle inside it to create a hole in the original rectangle:<br />
Dim Doc As Object<br />
Dim Page As Object<br />
Dim PolyPolygonShape As Object<br />
Dim PolyPolygon As Variant<br />
Dim Square1(3) As New com.sun.star.awt.Point<br />
Dim Square2(3) As New com.sun.star.awt.Point<br />
Dim Square3(3) As New com.sun.star.awt.Point<br />
Doc = StarDesktop.CurrentComponent<br />
Page = Doc.drawPages(0)<br />
184 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
An Overview of Various Drawing Objects<br />
PolyPolygonShape = Doc.createInstance("com.sun.star.drawing.PolyPolygonShape")<br />
Page.add(PolyPolygonShape) ' Page.add must take place before the coordinates<br />
are set<br />
Square1(0).x = 5000<br />
Square1(1).x = 10000<br />
Square1(2).x = 10000<br />
Square1(3).x = 5000<br />
Square1(0).y = 5000<br />
Square1(1).y = 5000<br />
Square1(2).y = 10000<br />
Square1(3).y = 10000<br />
Square2(0).x = 6500<br />
Square2(1).x = 8500<br />
Square2(2).x = 8500<br />
Square2(3).x = 6500<br />
Square2(0).y = 6500<br />
Square2(1).y = 6500<br />
Square2(2).y = 8500<br />
Square2(3).y = 8500<br />
Square3(0).x = 6500<br />
Square3(1).x = 8500<br />
Square3(2).x = 8500<br />
Square3(3).x = 6500<br />
Square3(0).y = 9000<br />
Square3(1).y = 9000<br />
Square3(2).y = 9500<br />
Square3(3).y = 9500<br />
PolyPolygonShape.PolyPolygon = Array(Square1(), Square2(), Square3())<br />
With respect as to which areas are filled and which areas are holes, <strong>OpenOffice</strong>.<strong>org</strong><br />
applies a simple rule: the edge of the outer shape is always the outer border of the<br />
polypolygon. The next line inwards is the inner border of the shape and marks the<br />
transition to the first hole. If there is another line inwards, it marks the transition to a<br />
filled area.<br />
Graphics<br />
The last of the drawing elements presented here are graphic objects that are based<br />
on the com.sun.star.drawing.GraphicObjectShape service. These can be used with<br />
any graphic within <strong>OpenOffice</strong>.<strong>org</strong> whose appearance can be adapted using a whole<br />
range of properties.<br />
Graphic objects support two of the general formatting properties:<br />
Chapter 8 · Drawings and Presentations 185
An Overview of Various Drawing Objects<br />
Text properties<br />
com.sun.star.drawing.Text (with com.sun.star.style.CharacterProperties and<br />
com.sun.star.style.ParagraphProperties)<br />
Shadow properties<br />
com.sun.star.drawing.ShadowProperties<br />
Additional properties that are supported by graphic objects are:<br />
GraphicURL (String)<br />
URL of the graphic<br />
AdjustLuminance (Short)<br />
luminance of the colors, as a percentage (negative values are also permitted)<br />
AdjustContrast (Short)<br />
contrast as a percentage (negative values are also permitted)<br />
AdjustRed (Short)<br />
red value as a percentage (negative values are also permitted)<br />
AdjustGreen (Short)<br />
green value as a percentage (negative values are also permitted)<br />
AdjustBlue (Short)<br />
blue value as a percentage (negative values are also permitted)<br />
Gamma (Short)<br />
gamma value of a graphic<br />
Transparency (Short)<br />
transparency of a graphic as a percentage<br />
GraphicColorMode (enum)<br />
color mode, for example, standard, gray stages, black and white (default value<br />
in accordance with com.sun.star.drawing.ColorMode)<br />
The following example shows how to insert a page into a graphics object.Dim Doc As<br />
Object<br />
Dim Page As Object<br />
Dim GraphicObjectShape As Object<br />
Dim Point As New com.sun.star.awt.Point<br />
Dim Size As New com.sun.star.awt.Size<br />
Point.x = 1000 ' specifications, insignificant because latter<br />
coordinates are binding<br />
186 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Point.y = 1000<br />
Size.Width = 10000<br />
Size.Height = 10000<br />
Doc = StarDesktop.CurrentComponent<br />
Page = Doc.drawPages(0)<br />
GraphicObjectShape =<br />
Doc.createInstance("com.sun.star.drawing.GraphicObjectShape")<br />
GraphicObjectShape.Size = Size<br />
GraphicObjectShape.Position = Point<br />
An Overview of Various Drawing Objects<br />
GraphicObjectShape.GraphicURL = "file:///c:/test.jpg"<br />
GraphicObjectShape.AdjustBlue = -50<br />
GraphicObjectShape.AdjustGreen = 5<br />
GraphicObjectShape.AdjustBlue = 10<br />
GraphicObjectShape.AdjustContrast = 20<br />
GraphicObjectShape.AdjustLuminance = 50<br />
GraphicObjectShape.Transparency = 40<br />
GraphicObjectShape.GraphicColorMode = com.sun.star.drawing.ColorMode.STANDARD<br />
Page.add(GraphicObjectShape)<br />
This code inserts the test.jpg graphic and adapts its appearance using the Adjust<br />
properties. In this example, the graphics are depicted as 40 percent transparent with<br />
no other color conversions do not take place (GraphicColorMode = STANDARD).<br />
Editing Drawing Objects<br />
Grouping Objects<br />
In many situations, it is useful to group several individual drawing objects together so<br />
that they behave as a single large object.<br />
The following example combines two drawing objects:<br />
Dim Doc As Object<br />
Dim Page As Object<br />
Dim Square As Object<br />
Dim Circle As Object<br />
Dim Shapes As Object<br />
Dim Group As Object<br />
Dim Point As New com.sun.star.awt.Point<br />
Dim Size As New com.sun.star.awt.Size<br />
Dim NewPos As New com.sun.star.awt.Point<br />
Chapter 8 · Drawings and Presentations 187
Grouping Objects<br />
Dim Height As Long<br />
Dim Width As Long<br />
Doc = StarDesktop.CurrentComponent<br />
Page = Doc.drawPages(0)<br />
Point.x = 3000<br />
Point.y = 3000<br />
Size.Width = 3000<br />
Size.Height = 3000<br />
' create square drawing element<br />
Square = Doc.createInstance("com.sun.star.drawing.RectangleShape")<br />
Square.Size = Size<br />
Square.Position = Point<br />
Square.FillColor = RGB(255,128,128)<br />
Page.add(Square)<br />
' create circle drawing element<br />
Circle = Doc.createInstance("com.sun.star.drawing.EllipseShape")<br />
Circle.Size = Size<br />
Circle.Position = Point<br />
Circle.FillColor = RGB(255,128,128)<br />
Circle.FillColor = RGB(0,255,0)<br />
Page.add(Circle)<br />
' combine square and circle drawing elements<br />
Shapes = createUnoService("com.sun.star.drawing.ShapeCollection")<br />
Shapes.add(Square)<br />
Shapes.add(Circle)<br />
Group = Page.group(Shapes)<br />
' centre combined drawing elements<br />
Height = Page.Height<br />
Width = Page.Width<br />
NewPos.X = Width / 2<br />
NewPos.Y = Height / 2<br />
Height = Group.Size.Height<br />
Width = Group.Size.Width<br />
NewPos.X = NewPos.X - Width / 2<br />
NewPos.Y = NewPos.Y - Height / 2<br />
Group.Position = NewPos<br />
This code creates a rectangle and a circle and inserts them into a page. It then<br />
creates an object that supports the com.sun.star.drawing.ShapeCollection service<br />
and uses the Add method to add the rectangle and the circle to this object. The<br />
ShapeCollection is added to the page using the Group method and returns the actual<br />
Group object that can be edited like an individual Shape.<br />
If you want to format the individual objects of a group, apply the formatting before you<br />
add them to the group. You cannot modify the objects once they are in the group.<br />
188 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Rotating and Shearing Drawing<br />
Objects<br />
Rotating and Shearing Drawing Objects<br />
All of the drawing objects that are described in the previous sections can also be<br />
rotated and sheared using the com.sun.star.drawing.RotationDescriptor service.<br />
The service provides the following properties:<br />
RotateAngle (Long)<br />
rotary angle in hundredths of a degree<br />
ShearAngle (Long)<br />
shear angle in hundredths of a degree<br />
The following example creates a rectangle and rotates it by 30 degrees using the<br />
RotateAngle property:<br />
Dim Doc As Object<br />
Dim Page As Object<br />
Dim RectangleShape As Object<br />
Dim Point As New com.sun.star.awt.Point<br />
Dim Size As New com.sun.star.awt.Size<br />
Point.x = 1000<br />
Point.y = 1000<br />
Size.Width = 10000<br />
Size.Height = 10000<br />
Doc = StarDesktop.CurrentComponent<br />
Page = Doc.drawPages(0)<br />
RectangleShape = Doc.createInstance("com.sun.star.drawing.RectangleShape")<br />
RectangleShape.Size = Size<br />
RectangleShape.Position = Point<br />
RectangleShape.RotateAngle = 3000<br />
Page.add(RectangleShape)<br />
The next example creates the same rectangle as in the previous example, but<br />
instead shears it through 30 degrees using the ShearAngle property.<br />
Dim Doc As Object<br />
Dim Page As Object<br />
Dim RectangleShape As Object<br />
Dim Point As New com.sun.star.awt.Point<br />
Dim Size As New com.sun.star.awt.Size<br />
Point.x = 1000<br />
Point.y = 1000<br />
Size.Width = 10000<br />
Chapter 8 · Drawings and Presentations 189
Rotating and Shearing Drawing Objects<br />
Size.Height = 10000<br />
Doc = StarDesktop.CurrentComponent<br />
Page = Doc.drawPages(0)<br />
RectangleShape = Doc.createInstance("com.sun.star.drawing.RectangleShape")<br />
RectangleShape.Size = Size<br />
RectangleShape.Position = Point<br />
RectangleShape.ShearAngle = 3000<br />
Page.add(RectangleShape)<br />
Presentations<br />
Searching and Replacing<br />
As in text documents, drawing documents provide a function for searching and<br />
replace. This function is similar to the one that is used in text documents as described<br />
in Text Documents. However, in drawing documents the descriptor objects for<br />
searching and replacing are not created directly through the document object, but<br />
rather through the associated character level. The following example outlines the<br />
replacement process within a drawing:<br />
Dim Doc As Object<br />
Dim Page As Object<br />
Dim ReplaceDescriptor As Object<br />
Dim I As Integer<br />
Doc = StarDesktop.CurrentComponent<br />
Page = Doc.drawPages(0)<br />
ReplaceDescriptor = Page.createReplaceDescriptor()<br />
ReplaceDescriptor.SearchString = "is"<br />
ReplaceDescriptor.ReplaceString = "was"<br />
For I = 0 to Doc.drawPages.Count - 1<br />
Page = Doc.drawPages(I)<br />
Page.ReplaceAll(ReplaceDescriptor)<br />
Next I<br />
This code uses the first DrawPage of the document to create a ReplaceDescriptor and<br />
then applies this descriptor in a loop to all of the pages in the drawing document.<br />
<strong>OpenOffice</strong>.<strong>org</strong> presentations are based on drawing documents. Each page in the<br />
presentation is a slide. You can access slides in the same way as a standard drawing<br />
190 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
is accessed through the DrawPages list of the document object. The<br />
com.sun.star.presentation.PresentationDocument service, responsible for<br />
presentation documents, also provides the complete<br />
com.sun.star.drawing.DrawingDocument service.<br />
Working With Presentations<br />
Searching and Replacing<br />
In addition to the drawing functions that are provided by the Presentation property,<br />
the presentation document has a presentation object that provides access to the<br />
main properties and control mechanisms for presentations. For example, this object<br />
provides a start method that can start presentations.<br />
Dim Doc As Object<br />
Dim Presentation As Object<br />
Doc = StarDesktop.CurrentComponent<br />
Presentation = Doc.Presentation<br />
Presentation.start()<br />
The code used in this example creates a Doc object that references the current<br />
presentation document and establishes the associated presentation object. The<br />
start() method of the object is used to start the example and run the screen<br />
presentation.<br />
The following methods are provided as presentation objects:<br />
start<br />
end<br />
starts the presentation<br />
ends the presentation<br />
rehearseTimings<br />
starts the presentation from the beginning and establishes its runtime<br />
The following properties are also available:<br />
AllowAnimations (Boolean)<br />
runs animations in the presentation<br />
CustomShow (String)<br />
allows you to specify the name of the presentation so that you can reference<br />
the name in the presentation<br />
Chapter 8 · Drawings and Presentations 191
Working With Presentations<br />
FirstPage (String)<br />
name of slide that you want to start the presentation with<br />
IsAlwaysOnTop (Boolean)<br />
always displays the presentation window as the first window on the screen<br />
IsAutomatic (Boolean)<br />
automatically runs through the presentation<br />
IsEndless (Boolean)<br />
restarts the presentation from the beginning once it ends<br />
IsFullScreen (Boolean)<br />
automatically starts the presentation in full screen mode<br />
IsMouseVisible (Boolean)<br />
displays the mouse during the presentation<br />
Pause (long)<br />
the amount of time that a blank screen is displayed at the end of the<br />
presentation<br />
StartWithNavigator (Boolean)<br />
displays the navigator window when the presentation starts<br />
UsePn (Boolean)<br />
displays the pointer during the presentation<br />
192 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
9<br />
C H A P T E R 9<br />
9 Charts (Diagrams)<br />
<strong>OpenOffice</strong>.<strong>org</strong> can display data as a chart, which creates graphical representations<br />
of numerical data in the form of bars, pie charts, lines or other elements. Data can<br />
either be displayed as 2D or 3D graphics, and the appearance of the chart elements<br />
can be individually adapted in a way similar to the process used for drawing<br />
elements.<br />
Charts are not treated as independent documents in <strong>OpenOffice</strong>.<strong>org</strong>, but as objects<br />
that are embedded in an existing document.<br />
A chart may contain its own data or may display data from the container document.<br />
For example charts in spreadsheets can display data obtained from the cell ranges<br />
and charts in text documents can display data obtained from writer tables.<br />
Using Charts in Spreadsheets<br />
Charts within spreadsheets can display the data from an assigned cell range within<br />
the spreadsheet. Any modifications made to the data within the spreadsheet will also<br />
be reflected in the assigned chart. The following example shows how to create a<br />
chart assigned to some cell ranges within a spreadsheet document:<br />
Dim Doc As Object<br />
Dim Charts As Object<br />
193
Charts (Diagrams)<br />
Dim Chart as Object<br />
Dim Rect As New com.sun.star.awt.Rectangle<br />
Dim RangeAddress(0) As New com.sun.star.table.CellRangeAddress<br />
Doc = StarDesktop.CurrentComponent<br />
Charts = Doc.Sheets(0).Charts<br />
Rect.X = 8000<br />
Rect.Y = 1000<br />
Rect.Width = 10000<br />
Rect.Height = 7000<br />
RangeAddress(0).Sheet = 0<br />
RangeAddress(0).StartColumn = 0<br />
RangeAddress(0).StartRow = 0<br />
RangeAddress(0).EndColumn = 2<br />
RangeAddress(0).EndRow = 12<br />
Charts.addNewByName("MyChart", Rect, RangeAddress(), True, True)<br />
Although the code used in the example may appear to be complex, the central<br />
processes are limited to three lines. The first central line creates the Doc document<br />
variable, which references the current spreadsheet document (Doc line =<br />
StarDesktop.CurrentComponent). The code used in the example then creates a list<br />
containing all charts of the first spreadsheet (Charts line = Doc.Sheets(0).Charts).<br />
Finally, in the last line, a new chart is added to this list using the addNewByName<br />
method. This new chart is then visible to the user. The variable RangeAddress<br />
determines the assigned cell range whose data will be displayed within the chart. The<br />
variable Rect determines the position and size of the chart within the first sheet in the<br />
spreadsheet document.<br />
The previous example creates a bar chart. If a different chart type is needed, then the<br />
bar chart must be explicitly replaced:<br />
Chart = Charts.getByName("MyChart").embeddedObject<br />
Chart.Diagram = Chart.createInstance("com.sun.star.chart.LineDiagram")<br />
The first line defines the corresponding chart object. The second line replaces the<br />
current chart with a new one — in this example, a line chart.<br />
Note – In Microsoft Excel, a distinction is made between charts which have been<br />
inserted as a separate page in a Microsoft Excel document and charts which are<br />
embedded in a table page. Correspondingly, two different access methods are<br />
defined there for charts. This distinction is not made in <strong>OpenOffice</strong>.<strong>org</strong> Basic,<br />
because charts in <strong>OpenOffice</strong>.<strong>org</strong> Calc are always created as embedded objects of a<br />
table page. The charts are always accessed using the Charts list of the associated<br />
Sheet object.<br />
194 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
The Structure of Charts<br />
Charts (Diagrams)<br />
The structure of a chart, and therefore the list of services and interfaces supported by<br />
it, depends on the chart type. For example, the methods and properties of the Z-axis,<br />
are available in 3D charts, but not in 2D charts, and in pie charts, there are no<br />
interfaces for working with axes.<br />
Title, Subtitle and Legend<br />
Title, subtitle and legend are basic elements provided for every chart. The Chart<br />
object provides the following properties for administrating these elements:<br />
HasMainTitle (Boolean)<br />
activates the title<br />
Title (Object)<br />
object with detailed information about the chart title (supports the<br />
com.sun.star.chart.ChartTitle service)<br />
HasSubTitle(Boolean)<br />
activates the subtitle<br />
Subtitle (Object)<br />
object with detailed information about the chart subtitle (supports the<br />
com.sun.star.chart.ChartTitle service)<br />
HasLegend (Boolean)<br />
activates the legend<br />
Legend (Object)<br />
object with detailed information about the legend (supports the<br />
com.sun.star.chart.ChartLegend service)<br />
Both services com.sun.star.chart.ChartTitle and<br />
com.sun.star.chart.ChartLegend do support the service<br />
com.sun.star.drawing.Shape. This allows to determine the position and size of the<br />
elements using the Position and Size properties. As the size of the legend and the<br />
titles is calculated automatically based on the current content and the character<br />
height for example, the size property provides read access only.<br />
Chapter 9 · Charts (Diagrams) 195
Title, Subtitle and Legend<br />
Fill and line properties (com.sun.star.drawing.FillProperties and<br />
com.sun.star.drawing.LineProperties services) as well as the character properties<br />
(com.sun.star.style.CharacterProperties service) are provided for further formatting of<br />
the elements.<br />
com.sun.star.chart.ChartTitle contains not only the listed formatting properties, but<br />
also two other properties:<br />
String (String)<br />
text which to be displayed as the title or subtitle<br />
TextRotation (Long)<br />
angle of rotation of text in 100ths of a degree<br />
The legend (com.sun.star.chart.ChartLegend) contains the following additional<br />
property:<br />
Alignment (Enum)<br />
position at which the legend appears (value of type<br />
com.sun.star.chart.ChartLegendPosition)<br />
The following example creates a chart with a title "Main Title String", a subtitle<br />
"Subtitle String" and a legend. The legend has a gray background color, is placed at<br />
the bottom of the chart, and has a character size of 7 points.<br />
Dim Doc As Object<br />
Dim Charts As Object<br />
Dim Chart as Object<br />
Dim Rect As New com.sun.star.awt.Rectangle<br />
Dim RangeAddress(0) As New com.sun.star.table.CellRangeAddress<br />
Rect.X = 8000<br />
Rect.Y = 1000<br />
Rect.Width = 10000<br />
Rect.Height = 7000<br />
RangeAddress(0).Sheet = 0<br />
RangeAddress(0).StartColumn = 0<br />
RangeAddress(0).StartRow = 0<br />
RangeAddress(0).EndColumn = 2<br />
RangeAddress(0).EndRow = 12<br />
Doc = StarDesktop.CurrentComponent<br />
Charts = Doc.Sheets(0).Charts<br />
Charts.addNewByName("MyChart", Rect, RangeAddress(), True, True)<br />
Chart = Charts.getByName("MyChart").EmbeddedObject<br />
Chart.HasMainTitle = True<br />
Chart.Title.String = "Main Title String"<br />
Chart.HasSubTitle = True<br />
Chart.Subtitle.String = "Subtitle String"<br />
Chart.HasLegend = True<br />
Chart.Legend.Alignment = com.sun.star.chart.ChartLegendPosition.BOTTOM<br />
196 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Chart.Legend.FillStyle = com.sun.star.drawing.FillStyle.SOLID<br />
Chart.Legend.FillColor = RGB(210, 210, 210)<br />
Chart.Legend.CharHeight = 7<br />
Background<br />
Title, Subtitle and Legend<br />
Every chart has a background area. The Chart object provides the property Area to<br />
format the background:<br />
Area (Object)<br />
background area of the chart (supports com.sun.star.chart.ChartArea service)<br />
The background of a chart covers its complete area, including the area under the title,<br />
subtitle and legend. The associated com.sun.star.chart.ChartArea service supports<br />
line and fill properties.<br />
Diagram<br />
The Chart object provides the property Diagram which forms the coordinate system<br />
with axes and grids, where the data finally is displayed:<br />
Diagram (Object)<br />
object forming the coordinate system where the data is plotted. It supports<br />
com.sun.star.chart.Diagram service and:<br />
com.sun.star.chart.StackableDiagram<br />
com.sun.star.chart.ChartAxisXSupplier<br />
com.sun.star.chart.ChartAxisYSupplier<br />
com.sun.star.chart.ChartAxisZSupplier<br />
com.sun.star.chart.ChartTwoAxisXSupplier<br />
com.sun.star.chart.ChartTwoAxisYSupplier<br />
Different services are supported depending on the chart type (see Chart Types).<br />
Chapter 9 · Charts (Diagrams) 197
Wall and Floor<br />
Wall and Floor<br />
The chart wall is the background of the coordinate system where the data is plotted.<br />
Two chart walls usually exist for 3D charts: one behind the plotted data and one as<br />
the left-hand or right-hand demarcation. This depends on the rotation of the chart. 3D<br />
charts usually also have a floor.<br />
The Diagram object provides the properties Wall and Floor:<br />
Wall (Object)<br />
background wall of the coordinate system (supports<br />
com.sun.star.chart.ChartArea service)<br />
Floor (Object)<br />
floor panel of coordinate system (only for 3D charts, supports<br />
com.sun.star.chart.ChartArea service)<br />
The specified objects support the com.sun.star.chart.ChartArea service, which<br />
provides the usual fill and line properties (com.sun.star.drawing.FillProperties and<br />
com.sun.star.drawing.LineProperties services, refer to Drawings and Presentations).<br />
The following example shows how graphics (named Sky) already contained in<br />
<strong>OpenOffice</strong>.<strong>org</strong> can be used as a background for a chart. The wall is set to be blue.<br />
Dim Doc As Object<br />
Dim Charts As Object<br />
Dim Chart as Object<br />
Dim Rect As New com.sun.star.awt.Rectangle<br />
Dim RangeAddress(0) As New com.sun.star.table.CellRangeAddress<br />
Rect.X = 8000<br />
Rect.Y = 1000<br />
Rect.Width = 10000<br />
Rect.Height = 7000<br />
RangeAddress(0).Sheet = 0<br />
RangeAddress(0).StartColumn = 0<br />
RangeAddress(0).StartRow = 0<br />
RangeAddress(0).EndColumn = 2<br />
RangeAddress(0).EndRow = 12<br />
Doc = StarDesktop.CurrentComponent<br />
Charts = Doc.Sheets(0).Charts<br />
Charts.addNewByName("MyChart", Rect, RangeAddress(), True, True)<br />
Chart = Charts.getByName("MyChart").EmbeddedObject<br />
Chart.Area.FillStyle = com.sun.star.drawing.FillStyle.BITMAP<br />
Chart.Area.FillBitmapName = "Sky"<br />
Chart.Area.FillBitmapMode = com.sun.star.drawing.BitmapMode.REPEAT<br />
Chart.Diagram.Wall.FillStyle = com.sun.star.drawing.FillStyle.SOLID<br />
Chart.Diagram.Wall.FillColor = RGB(00,132,209)<br />
198 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Axes<br />
Axes<br />
<strong>OpenOffice</strong>.<strong>org</strong> recognizes five different axes that can be used in a chart. In the<br />
simplest scenario, these are the X and Y-axes. When working with 3D charts, a Zaxis<br />
is also sometimes provided. For charts in which the values of the various rows of<br />
data deviate significantly from one another, <strong>OpenOffice</strong>.<strong>org</strong> provides a second X and<br />
Y-axis for second scaling operations.<br />
The Diagram object provides the following properties to access the axes:<br />
HasXAxis (Boolean)<br />
activates the X-axis<br />
XAxis (Object)<br />
object with detailed information about the X-axis (supports<br />
com.sun.star.chart.ChartAxis service)<br />
HasXAxisDescription (Boolean)<br />
activates the labels for the interval marks for the X-axis<br />
HasYAxis (Boolean)<br />
activates the Y-axis<br />
YAxis (Object)<br />
object with detailed information about the Y-axis (supports<br />
com.sun.star.chart.ChartAxis service)<br />
HasYAxisDescription (Boolean)<br />
activates the labels for the interval marks for the Y-axis<br />
HasZAxis (Boolean)<br />
activates the Z-axis<br />
ZAxis (Object)<br />
object with detailed information about the Z-axis (supports<br />
com.sun.star.chart.ChartAxis service)<br />
HasZAxisDescription (Boolean)<br />
activates the labels for the interval marks for the Z-axis<br />
HasSecondaryXAxis (Boolean)<br />
activates the secondary X-axis<br />
Chapter 9 · Charts (Diagrams) 199
Axes<br />
SecondaryXAxis (Object)<br />
object with detailed information about the secondary X-axis (supports<br />
com.sun.star.chart.ChartAxis service)<br />
HasSecondaryXAxisDescription (Boolean)<br />
activates the labels for the interval marks for the secondary X-axis<br />
HasSecondaryYAxis (Boolean)<br />
activates the secondary Y-axis<br />
SecondaryYAxis (Object)<br />
object with detailed information about the secondary Y-axis (supports<br />
com.sun.star.chart.ChartAxis service)<br />
HasSecondaryYAxisDescription (Boolean)<br />
activates the labels for the interval marks for the secondary Y-axis<br />
Properties of Axes<br />
The axis objects of a <strong>OpenOffice</strong>.<strong>org</strong> chart support the com.sun.star.chart.ChartAxis<br />
service. In addition to the properties for characters<br />
(com.sun.star.style.CharacterProperties service, refer to Text Documents) and lines<br />
(com.sun.star.drawing.LineStyle service, refer to Drawings and Presentations), it<br />
provides the following properties:<br />
Scaling properties:<br />
Max (Double)<br />
maximum value for axis<br />
Min (Double)<br />
minimum value for axis<br />
Origin (Double)<br />
point of intersect for crossing axes<br />
StepMain (Double)<br />
distance between the major interval marks<br />
200 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
StepHelp (Double)<br />
Properties of Axes<br />
distance between the minor interval marks (deprecated since <strong>OpenOffice</strong>.<strong>org</strong><br />
3.0; Use property StepHelpCount instead)<br />
StepHelpCount (Long)<br />
Contains the number of minor intervals within a major interval. E.g. a<br />
StepHelpCount of 5 divides the major interval into 5 pieces and thus produces 4<br />
minor tick marks. (available since <strong>OpenOffice</strong>.<strong>org</strong> 3.0)<br />
AutoMax (Boolean)<br />
the maximum value for the axis is calculated automatically when set to true<br />
AutoMin (Boolean)<br />
the minimum value for the axis is calculated automatically when set to true<br />
AutoOrigin (Boolean)<br />
the origin is determines automatically when set to true<br />
AutoStepMain (Boolean)<br />
StepMain is determines automatically when set to true<br />
AutoStepHelp (Boolean)<br />
StepHelpCount is determines automatically when set to true<br />
Logarithmic (Boolean)<br />
scales the axes in logarithmic manner (rather than linear)<br />
ReverseDirection (Boolean)<br />
determines if the axis orientation is mathematical or reversed. (available since<br />
<strong>OpenOffice</strong>.<strong>org</strong> 2.4)<br />
Label properties:<br />
DisplayLabels (Boolean)<br />
activates the text label at the interval marks<br />
TextRotation (Long)<br />
angle of rotation of text label in 100ths of a degree<br />
ArrangeOrder (enum)<br />
the label may be staggered, thus they are positioned alternately over two lines<br />
(values according to com.sun.star.chart.ChartAxisArrangeOrderType)<br />
Chapter 9 · Charts (Diagrams) 201
Properties of Axes<br />
TextBreak (Boolean)<br />
permits line breaks within the axes labels<br />
TextCanOverlap (Boolean)<br />
permits an overlap of the axes labels<br />
NumberFormat (Long)<br />
number format to be used with the axes labels<br />
LinkNumberFormatToSource (Boolean)<br />
determines whether to use the number format given by the container document,<br />
or from the property NumberFormat. (since <strong>OpenOffice</strong>.<strong>org</strong> 2.3)<br />
Interval mark properties:<br />
Marks (Const)<br />
determines the position of the major interval marks (values in accordance with<br />
com.sun.star.chart.ChartAxisMarks)<br />
HelpMarks (Const)<br />
determines the position of the minor interval marks (values in accordance with<br />
com.sun.star.chart.ChartAxisMarks)<br />
Only for bar charts:<br />
Overlap (Long)<br />
percentage which specifies the extent to which the bars of different sets of data<br />
may overlap (at 100%, the bars are shown as completely overlapping, at -100%,<br />
there is a distance of the width of one bar between them)<br />
GapWidth (long)<br />
percentage which specifies the distance there may be between the different<br />
groups of bars of a chart (at 100%, there is a distance corresponding to the<br />
width of one bar)<br />
202 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Grids<br />
Grids<br />
For the primary axes grids and sub grids can be displayed, matching to the major and<br />
minor intervals. The Diagram object provides the following properties to access the<br />
grids:<br />
HasXAxisGrid (Boolean)<br />
activates major grid for X-axis<br />
XMainGrid (Object)<br />
object with detailed information about the major grid for X-axis (supports<br />
com.sun.star.chart.ChartGrid service)<br />
HasXAxisHelpGrid (Boolean)<br />
activates minor grid for X-axis<br />
XHelpGrid (Object)<br />
object with detailed information about the minor grid for X-axis (supports<br />
com.sun.star.chart.ChartGrid service)<br />
the same for y and z:<br />
HasYAxisGrid (Boolean)<br />
activates major grid for Y-axis<br />
YMainGrid (Object)<br />
object with detailed information about the major grid for Y-axis (supports<br />
com.sun.star.chart.ChartGrid service)<br />
HasYAxisHelpGrid (Boolean)<br />
activates minor grid for Y-axis<br />
YHelpGrid (Object)<br />
object with detailed information about the minor grid for Y-axis (supports<br />
com.sun.star.chart.ChartGrid service)<br />
HasZAxisGrid (Boolean)<br />
activates major grid for Z-axis<br />
ZMainGrid (Object)<br />
object with detailed information about the major grid for Z-axis (supports<br />
com.sun.star.chart.ChartGrid service)<br />
Chapter 9 · Charts (Diagrams) 203
Grids<br />
HasZAxisHelpGrid (Boolean)<br />
activates minor grid for Z-axis<br />
ZHelpGrid (Object)<br />
object with detailed information about the minor grid for Z-axis (supports<br />
com.sun.star.chart.ChartGrid service)<br />
The grid object is based on the com.sun.star.chart.ChartGrid service, which in turn<br />
supports the line properties of the com.sun.star.drawing.LineStyle support service<br />
(refer to Drawings and Presentations).<br />
Axes Title<br />
For all axes an additional title can be displayed. The Diagram object provides the<br />
following properties to access the axes title:<br />
HasXAxisTitle (Boolean)<br />
activates title of X-axis<br />
XAxisTitle (Object)<br />
object with detailed information about title of the X-axis (supports<br />
com.sun.star.chart.ChartTitle service)<br />
same y and z:<br />
HasYAxisTitle (Boolean)<br />
activates title of Y-axis<br />
YAxisTitle (Object)<br />
object with detailed information about title of the Y-axis (supports<br />
com.sun.star.chart.ChartTitle service)<br />
HasZAxisTitle (Boolean)<br />
activates title of Z-axis<br />
ZAxisTitle (Object)<br />
object with detailed information about title of the Z-axis (supports<br />
com.sun.star.chart.ChartTitle service)<br />
and for the secondary axes (available since <strong>OpenOffice</strong>.<strong>org</strong> 3.0):<br />
204 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
HasSecondaryXAxisTitle (Boolean)<br />
activates title of the secondary X-axis.<br />
SecondXAxisTitle (Object)<br />
Axes Title<br />
object with detailed information about title of the secondary X-axis (supports<br />
com.sun.star.chart.ChartTitle service)<br />
HasSecondaryYAxisTitle (Boolean)<br />
activates title of the secondary Y-axis.<br />
SecondYAxisTitle (Object)<br />
object with detailed information about title of the secondary Y-axis (supports<br />
com.sun.star.chart.ChartTitle service)<br />
The objects for formatting the axes title are based on the<br />
com.sun.star.chart.ChartTitle service, which is also used for chart titles.<br />
Example<br />
The following example creates a line chart. The color for the rear wall of the chart is<br />
set to white. Both the X and Y-axes have a gray grid for visual orientation. The<br />
minimum value of the Y-axis is fixed to 0 and the maximum value is fixed to 100 so<br />
that the resolution of the chart is retained even if the values are changed. The X-axis<br />
points in reverse direction from right to left. And a title for the X-axis was added.<br />
Dim Doc As Object<br />
Dim Charts As Object<br />
Dim Chart as Object<br />
Dim Rect As New com.sun.star.awt.Rectangle<br />
Dim RangeAddress(0) As New com.sun.star.table.CellRangeAddress<br />
Doc = StarDesktop.CurrentComponent<br />
Charts = Doc.Sheets(0).Charts<br />
Rect.X = 8000<br />
Rect.Y = 1000<br />
Rect.Width = 10000<br />
Rect.Height = 7000<br />
RangeAddress(0).Sheet = 0<br />
RangeAddress(0).StartColumn = 0<br />
RangeAddress(0).StartRow = 0<br />
RangeAddress(0).EndColumn = 2<br />
RangeAddress(0).EndRow = 12<br />
Charts.addNewByName("MyChart", Rect, RangeAddress(), True, True)<br />
Chart = Charts.getByName("MyChart").embeddedObject<br />
Chart.Diagram = Chart.createInstance("com.sun.star.chart.LineDiagram")<br />
Chart.Diagram.Wall.FillColor = RGB(255, 255, 255)<br />
Chart.Diagram.HasXAxisGrid = True<br />
Chapter 9 · Charts (Diagrams) 205
Axes Title<br />
Chart.Diagram.XMainGrid.LineColor = RGB(192, 192, 192)<br />
Chart.Diagram.HasYAxisGrid = True<br />
Chart.Diagram.YMainGrid.LineColor = RGB(192, 192, 192)<br />
Chart.Diagram.YAxis.Min = 0<br />
Chart.Diagram.YAxis.Max = 100<br />
Chart.Diagram.XAxis.ReverseDirection = true 'needs <strong>OpenOffice</strong>.<strong>org</strong> 2.4 or newer<br />
Chart.Diagram.HasXAxisTitle = true<br />
Chart.Diagram.XAxisTitle.String = "Reversed X Axis Example"<br />
3D Charts<br />
Most charts in <strong>OpenOffice</strong>.<strong>org</strong> can also be displayed with 3D graphics. The following<br />
properties are provided for 3D charts at the Diagram object:<br />
Dim3D (Boolean)<br />
activates 3D display<br />
Deep (Boolean)<br />
the series will be arranged behind each other in z-direction<br />
RightAngledAxes (Boolean)<br />
activates a 3D display mode where X- and Y-axes form a right angle within the<br />
projection. (available since <strong>OpenOffice</strong>.<strong>org</strong> 2.3)<br />
D3DScenePerspective (Enum)<br />
defines whether the 3D objects are to be drawn in perspective or parallel<br />
projection.(values according to com.sun.star.drawing.ProjectionMode)<br />
Perspective (Long)<br />
Perspective of 3D charts ( [0,100] ) (available since <strong>OpenOffice</strong>.<strong>org</strong> 2.4.1)<br />
RotationHorizontal (Long)<br />
Horizontal rotation of 3D charts in degrees ( [-180,180] ) (available since<br />
<strong>OpenOffice</strong>.<strong>org</strong> 2.4.1)<br />
RotationVertical (Long)<br />
Vertical rotation of 3D charts in degrees ( [-180,180] ) (available since<br />
<strong>OpenOffice</strong>.<strong>org</strong> 2.4.1)<br />
The following example creates a 3D area chart.<br />
Dim Doc As Object<br />
Dim Charts As Object<br />
Dim Chart as Object<br />
206 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Dim Rect As New com.sun.star.awt.Rectangle<br />
Dim RangeAddress(0) As New com.sun.star.table.CellRangeAddress<br />
Doc = StarDesktop.CurrentComponent<br />
Charts = Doc.Sheets(0).Charts<br />
Rect.X = 8000<br />
Rect.Y = 1000<br />
Rect.Width = 10000<br />
Rect.Height = 7000<br />
RangeAddress(0).Sheet = 0<br />
RangeAddress(0).StartColumn = 0<br />
RangeAddress(0).StartRow = 0<br />
RangeAddress(0).EndColumn = 2<br />
RangeAddress(0).EndRow = 12<br />
Charts.addNewByName("MyChart", Rect, RangeAddress(), True, True)<br />
Chart = Charts.getByName("MyChart").embeddedObject<br />
Chart.Diagram = Chart.createInstance("com.sun.star.chart.AreaDiagram")<br />
Chart.Diagram.Dim3D = true<br />
Chart.Diagram.Deep = true<br />
Chart.Diagram.RightAngledAxes = true 'needs <strong>OpenOffice</strong>.<strong>org</strong> 2.3 or newer<br />
Chart.Diagram.D3DScenePerspective =<br />
com.sun.star.drawing.ProjectionMode.PERSPECTIVE<br />
Chart.Diagram.Perspective = 100 'needs <strong>OpenOffice</strong>.<strong>org</strong> 2.4.1 or newer<br />
Chart.Diagram.RotationHorizontal = 60 'needs <strong>OpenOffice</strong>.<strong>org</strong> 2.4.1 or newer<br />
Chart.Diagram.RotationVertical = 30 'needs <strong>OpenOffice</strong>.<strong>org</strong> 2.4.1 or newer<br />
Stacked Charts<br />
3D Charts<br />
Stacked charts are charts that are arranged with several individual values on top of<br />
one another to produce a total value. This view shows not only the individual values,<br />
but also an overview of all the values.<br />
In <strong>OpenOffice</strong>.<strong>org</strong>, various types of charts can be displayed in a stacked form. All of<br />
these charts support the com.sun.star.chart.StackableDiagram service, which in turn<br />
provides the following properties:<br />
Stacked (Boolean)<br />
activates the stacked viewing mode<br />
Percent (Boolean)<br />
rather than absolute values, displays their percentage distribution<br />
Chapter 9 · Charts (Diagrams) 207
Stacked Charts<br />
Chart Types<br />
Line Charts<br />
Line charts (com.sun.star.chart.LineDiagram) support two X-axes, two Y-axes and<br />
one Z-axis. They can be displayed as 2D or 3D graphics<br />
(com.sun.star.chart.Dim3Ddiagram service). The lines can be stacked<br />
(com.sun.star.chart.StackableDiagram).<br />
Line charts provide the following properties:<br />
SymbolType (const)<br />
symbol for displaying the data points (constant in accordance with<br />
com.sun.star.chart.ChartSymbolType)<br />
SymbolSize (Long)<br />
size of symbol for displaying the data points in 100ths of a millimeter<br />
SymbolBitmapURL (String)<br />
file name of graphics for displaying the data points<br />
Lines (Boolean)<br />
links the data points by means of lines<br />
SplineType (Long)<br />
spline function for smoothing the lines (0: no spline function, 1: cubic splines, 2:<br />
B splines)<br />
SplineOrder (Long)<br />
polynomial weight for splines (only for B splines)<br />
SplineResolution (Long)<br />
number of support points for spline calculation<br />
Area Charts<br />
Area charts (com.sun.star.chart.AreaDiagram service) support two X-axes, two Y-<br />
208 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
axes and one Z-axis. They can be displayed as 2D or 3D graphics<br />
(com.sun.star.chart.Dim3Ddiagram service). The areas can be stacked<br />
(com.sun.star.chart.StackableDiagram).<br />
Bar Charts<br />
Area Charts<br />
Bar charts (com.sun.star.chart.BarDiagram) support two X-axes, two Y-axes and one<br />
Z-axis. They can be displayed as 2D or 3D graphics<br />
(com.sun.star.chart.Dim3Ddiagram service). The bars can be stacked<br />
(com.sun.star.chart.StackableDiagram).<br />
They provide the following properties:<br />
Vertical (Boolean)<br />
displays the bars vertically, otherwise they are depicted horizontally<br />
Deep (Boolean)<br />
in 3D viewing mode, positions the bars behind one another rather than next to<br />
one another<br />
StackedBarsConnected (Boolean)<br />
links the associated bars in a stacked chart by means of lines (only available<br />
with horizontal charts)<br />
NumberOfLines (Long)<br />
number of lines to be displayed in a stacked chart as lines rather than bars<br />
GroupBarsPerAxis (Boolean)<br />
displays bars attached to different axes behind or next to each other (available<br />
since <strong>OpenOffice</strong>.<strong>org</strong> 2.4)<br />
Pie Charts<br />
Pie charts (com.sun.star.chart.PieDiagram) do not contain any axes and cannot be<br />
stacked. They can be displayed as 2D or 3D graphics<br />
(com.sun.star.chart.Dim3DDiagram service).<br />
The following properties are provided for pie and donut charts with the Diagram<br />
Chapter 9 · Charts (Diagrams) 209
Pie Charts<br />
object:<br />
StartingAngle (Long)<br />
angle of the first piece of a pie in degrees (available since <strong>OpenOffice</strong>.<strong>org</strong> 3.0)<br />
210 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
10<br />
C H A P T E R 1 0<br />
10 Databases<br />
<strong>OpenOffice</strong>.<strong>org</strong> has an integrated database interface (independent of any systems)<br />
called Star Database Connectivity (SDBC). The objective of developing this interface<br />
was to provide access to as many different data sources as possible.<br />
To make this possible, data sources are accessed by drivers. The sources from which<br />
the drivers take their data is irrelevant to a SDBC user. Some drivers access filebased<br />
databases and take the data directly from them. Others use standard<br />
interfaces such as JDBC or ODBC. There are, however, also special drivers which<br />
access the MAPI address book, LDAP directories or <strong>OpenOffice</strong>.<strong>org</strong> spreadsheets as<br />
data sources.<br />
Since the drivers are based on UNO components, other drivers can be developed<br />
and therefore open up new data sources. You will find details about this in the<br />
<strong>OpenOffice</strong>.<strong>org</strong> Developer's <strong>Guide</strong>.<br />
Note – In terms of its concept, SDBC is comparable with the ADO and DAO libraries<br />
available in VBA. It permits high level access to databases, regardless of the<br />
underlying database backends.<br />
211
Databases<br />
SQL: a Query Language<br />
The SQL language is provided as a query language for users of SDBC. To compare<br />
the differences between different SQL dialects, the SDBC components from<br />
<strong>OpenOffice</strong>.<strong>org</strong> have their own SQL parser. This uses the query window to check the<br />
SQL commands typed and corrects simple syntax errors, such as those associated<br />
with uppercase and lowercase characters.<br />
If a driver permits access to a data source that does not support SQL, then it must<br />
independently convert the transferred SQL commands to the native access needed.<br />
Types of Database Access<br />
The database interface from <strong>OpenOffice</strong>.<strong>org</strong> is available in the <strong>OpenOffice</strong>.<strong>org</strong> Writer<br />
and <strong>OpenOffice</strong>.<strong>org</strong> Calc applications, as well as in the database forms.<br />
In <strong>OpenOffice</strong>.<strong>org</strong> Writer, standard letters can be created with the assistance of<br />
SDBC data sources and these can then be printed out. You can also move data from<br />
the database window into text documents using the drag-and-drop function.<br />
If you move a database table into a spreadsheet, <strong>OpenOffice</strong>.<strong>org</strong> creates a table area<br />
which can be updated at the click of the mouse if the original data has been modified.<br />
Conversely, spreadsheet data can be moved to a database table and a database<br />
import performed.<br />
Finally, <strong>OpenOffice</strong>.<strong>org</strong> provides a mechanism for forms based on databases. To do<br />
this, you first create a standard <strong>OpenOffice</strong>.<strong>org</strong> Writer or <strong>OpenOffice</strong>.<strong>org</strong> Calc form<br />
and then link the fields to a database.<br />
All the options specified here are based on the user interface from <strong>OpenOffice</strong>.<strong>org</strong>.<br />
No programming knowledge is needed to use the corresponding functions.<br />
This section, however, provides little information about the functions specified, but<br />
instead concentrates on the programming interface from SDBC, which allows for<br />
automated database querying and therefore permits a much greater range of<br />
applications to be used.<br />
Basic knowledge of the way in which databases function and the SQL query<br />
language is however needed to fully understand the following sections.<br />
212 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Data Sources<br />
Databases<br />
A database is incorporated into <strong>OpenOffice</strong>.<strong>org</strong> by creating what is commonly<br />
referred to as a data source. The user interface provides a corresponding option for<br />
creating data sources in the Extras menu. You can also create data sources and work<br />
with them using <strong>OpenOffice</strong>.<strong>org</strong> Basic.<br />
A database context object that is created using the createUnoService function serves<br />
as the starting point for accessing a data source. This based on the<br />
com.sun.star.sdb.DatabaseContext service and is the root object for all database<br />
operations.<br />
The following example shows how a database context can be created and then used<br />
to determine the names of all data sources available. It displays the names in a<br />
message box.<br />
Dim DatabaseContext As Object<br />
Dim Names<br />
Dim I As Integer<br />
DatabaseContext = createUnoService("com.sun.star.sdb.DatabaseContext")<br />
Names = DatabaseContext.getElementNames()<br />
For I = 0 To UBound(Names())<br />
MsgBox Names(I)<br />
Next I<br />
The individual data sources are based on the com.sun.star.sdb.DataSource service<br />
and can be determined from the database context using the getByName method:<br />
Dim DatabaseContext As Object<br />
Dim DataSource As Object<br />
DatabaseContext = createUnoService("com.sun.star.sdb.DatabaseContext")<br />
DataSource = DatabaseContext.getByName("Customers")<br />
The example creates a DataSource object for a data source called Customers.<br />
Data sources provide a range of properties, which in turn provide general information<br />
about the origin of the data and information about access methods. The properties<br />
are:<br />
Name (String)<br />
name of data source<br />
URL (String)<br />
URL of data source in the form of jdbc: subprotocol : subname or sdbc:<br />
subprotocol : subname<br />
Chapter 10 · Databases 213
Databases<br />
Settings (Array)<br />
array containing PropertyValue-pairs with connection parameters (usually at<br />
least user name and password)<br />
User (String)<br />
user name<br />
Password (String)<br />
user password (is not saved)<br />
IsPasswordRequired (Boolean)<br />
the password is needed and is interactively requested from user.<br />
IsReadOnly (Boolean)<br />
permits read-only access to the database<br />
NumberFormatsSupplier (Object)<br />
object containing the number formats available for the database (supports the<br />
com.sun.star.util.XNumberFormatsSupplier interface)<br />
TableFilter (Array)<br />
list of table names to be displayed<br />
TableTypeFilter (Array)<br />
list of table types to be displayed. Values available are TABLE, VIEW and SYSTEM<br />
TABLE<br />
SuppressVersionColumns (Boolean)<br />
suppresses the display of columns that are used for version administration<br />
Note – The data sources from <strong>OpenOffice</strong>.<strong>org</strong> are not 1:1 comparable with the data<br />
sources in ODBC. Whereas an ODBC data source only covers information about the<br />
origin of the data, a data source in <strong>OpenOffice</strong>.<strong>org</strong> also includes a range of<br />
information about how the data is displayed within the database windows of<br />
<strong>OpenOffice</strong>.<strong>org</strong>.<br />
Queries<br />
Predefined queries can be assigned to a data source. <strong>OpenOffice</strong>.<strong>org</strong> notes the SQL<br />
commands of queries so that they are available at all times. Queries are used to<br />
214 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Queries<br />
simplify working with databases because they can be opened with a simple mouse<br />
click and also provide users without any knowledge of SQL with the option of issuing<br />
SQL commands.<br />
An object which supports the com.sun.star.sdb.QueryDefinition service is concealed<br />
behind a query. The queries are accessed by means of the QueryDefinitions<br />
method of the data source.<br />
The following example lists the names of data source queries can be established in a<br />
message box.<br />
Dim DatabaseContext As Object<br />
Dim DataSource As Object<br />
Dim QueryDefinitions As Object<br />
Dim QueryDefinition As Object<br />
Dim I As Integer<br />
DatabaseContext = createUnoService("com.sun.star.sdb.DatabaseContext")<br />
DataSource = DatabaseContext.getByName("Customers")<br />
QueryDefinitions = DataSource.getQueryDefinitions()<br />
For I = 0 To QueryDefinitions.Count() - 1<br />
QueryDefinition = QueryDefinitions(I)<br />
MsgBox QueryDefinition.Name<br />
Next I<br />
In addition to the Name property used in the example, the<br />
com.sun.star.sdb.QueryDefinition provides a whole range of other properties. These<br />
are:<br />
Name (String)<br />
query name<br />
Command (String)<br />
SQL command (typically a SELECT command)<br />
The following example shows how a query object can be created in a programcontrolled<br />
manner and can be assigned to a data source.<br />
Dim DatabaseContext As Object<br />
Dim DataSource As Object<br />
Dim QueryDefinitions As Object<br />
Dim QueryDefinition As Object<br />
Dim I As Integer<br />
DatabaseContext = createUnoService("com.sun.star.sdb.DatabaseContext")<br />
DataSource = DatabaseContext.getByName("Customers")<br />
QueryDefinitions = DataSource.getQueryDefinitions()<br />
QueryDefinition = createUnoService("com.sun.star.sdb.QueryDefinition")<br />
QueryDefinition.Command = "SELECT * FROM Customer"<br />
QueryDefinitions.insertByName("NewQuery", QueryDefinition)<br />
Chapter 10 · Databases 215
Queries<br />
The query object is first created using the createUnoService call, then initialized, and<br />
then inserted into the QueryDefinitions object by means of insertByName.<br />
Database Access<br />
A database connection is needed for access to a database. This is a transfer channel<br />
which permits direct communication with the database. Unlike the data sources<br />
presented in the previous section, the database connection must therefore be reestablished<br />
every time the program is restarted.<br />
<strong>OpenOffice</strong>.<strong>org</strong> provides various ways of establishing database connections. This<br />
example shows how to connect to an existing data source.<br />
Dim DatabaseContext As Object<br />
Dim DataSource As Object<br />
Dim Connection As Object<br />
Dim InteractionHandler as Object<br />
DatabaseContext = createUnoService("com.sun.star.sdb.DatabaseContext")<br />
DataSource = DatabaseContext.getByName("Customers")<br />
If Not DataSource.IsPasswordRequired Then<br />
Connection = DataSource.GetConnection("","")<br />
Else<br />
InteractionHandler = createUnoService("com.sun.star.sdb.InteractionHandler")<br />
Connection = DataSource.ConnectWithCompletion(InteractionHandler)<br />
End If<br />
The code used in the example first checks whether the database is password<br />
protected. If not, it creates the database connection required using the GetConnection<br />
call. The two empty strings in the command line stand for the user name and<br />
password.<br />
If the database is password protected, the example creates an InteractionHandler<br />
and opens the database connection using the ConnectWithCompletion method. The<br />
InteractionHandler ensures that <strong>OpenOffice</strong>.<strong>org</strong> asks the user for the required login<br />
data.<br />
216 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Iteration of Tables<br />
Iteration of Tables<br />
A table is usually accessed in <strong>OpenOffice</strong>.<strong>org</strong> through the ResultSet object. A<br />
ResultSet is a type of marker that indicates a current set of data within a volume of<br />
results obtained using the SELECT command.<br />
This example shows how a ResultSet can be used to query values from a database<br />
table.<br />
Dim DatabaseContext As Object<br />
Dim DataSource As Object<br />
Dim Connection As Object<br />
Dim InteractionHandler as Object<br />
Dim Statement As Object<br />
Dim ResultSet As Object<br />
DatabaseContext = createUnoService("com.sun.star.sdb.DatabaseContext")<br />
DataSource = DatabaseContext.getByName("Customers")<br />
If Not DataSource.IsPasswordRequired Then<br />
Connection = DataSource.GetConnection("","")<br />
Else<br />
InteractionHandler = createUnoService("com.sun.star.sdb.InteractionHandler")<br />
Connection = DataSource.ConnectWithCompletion(InteractionHandler)<br />
End If<br />
Statement = Connection.createStatement()<br />
ResultSet = Statement.executeQuery("SELECT ""CustomerNumber"" FROM<br />
""Customer""")<br />
If Not IsNull(ResultSet) Then<br />
While ResultSet.next<br />
MsgBox ResultSet.getString(1)<br />
Wend<br />
End If<br />
Once the database connection has been established, the code used in the example<br />
first uses the Connection.createObject call to create a Statement object. This<br />
Statement object then uses the executeQuery call to return the actual ResultSet. The<br />
program now checks whether the ResultSet actually exists and traverses the data<br />
records using a loop. The values required (in the example, those from the<br />
CustomerNumber field) returns the ResultSet using the getString method, whereby<br />
the parameter 1 determines that the call relates to the values of the first column.<br />
Note – The ResultSet object from SDBC is comparable with the Recordset object<br />
from DAO and ADO, since this also provides iterative access to a database.<br />
Chapter 10 · Databases 217
Iteration of Tables<br />
Note – The database is actually accessed in <strong>OpenOffice</strong>.<strong>org</strong> through a ResultSet<br />
object. This reflects the content of a table or the result of a SQL-SELECT command.<br />
In the past, the ResultSet object provided the resident methods in the Application<br />
object for navigation within the data, for example, DataNextRecord ).<br />
Type-Specific Methods for Retrieving<br />
Values<br />
As can be seen in the example from the previous section, <strong>OpenOffice</strong>.<strong>org</strong> provides a<br />
getString method for accessing table contents. The method provides the result in<br />
the form of a string. The following get methods are available:<br />
getByte()<br />
supports the SQL data types for numbers, characters and strings<br />
getShort()<br />
getInt()<br />
getLong()<br />
supports the SQL data types for numbers, characters and strings<br />
supports the SQL data types for numbers, characters and strings<br />
supports the SQL data types for numbers, characters and strings<br />
getFloat()<br />
supports the SQL data types for numbers, characters and strings<br />
getDouble()<br />
supports the SQL data types for numbers, characters and strings<br />
getBoolean()<br />
supports the SQL data types for numbers, characters and strings<br />
getString()<br />
supports all SQL data types<br />
getBytes()<br />
supports the SQL data types for binary values<br />
218 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
getDate()<br />
getTime()<br />
Type-Specific Methods for Retrieving Values<br />
supports the SQL data types for numbers, strings, date and time stamp<br />
supports the SQL data types for numbers, strings, date and time stamp<br />
getTimestamp()<br />
supports the SQL data types for numbers, strings, date and time stamp<br />
getCharacterStream()<br />
supports the SQL data types for numbers, strings and binary values<br />
getUnicodeStream()<br />
supports the SQL data types for numbers, strings and binary values<br />
getBinaryStream()<br />
binary values<br />
getObject()<br />
supports all SQL data types<br />
In all instances, the number of columns should be listed as a parameter whose<br />
values should be queried.<br />
The ResultSet Variants<br />
Accessing databases is often a matter of critical speed. <strong>OpenOffice</strong>.<strong>org</strong> provides<br />
several ways of optimizing ResultSets and thereby controlling the speed of access.<br />
The more functions a ResultSet provides, the more complex its implementation<br />
usually is and therefore the slower the functions are.<br />
A simple ResultSet, provides the minimum scope of functions available. It only<br />
allows iteration to be applied forward, and for values to be interrogated. More<br />
extensive navigation options, such as the possibility of modifying values, are<br />
therefore not included.<br />
The Statement object used to create the ResultSet provides some properties which<br />
allow the functions of the ResultSet to be influenced:<br />
ResultSetConcurrency (const)<br />
specifications as to whether the data can be modified (specifications in<br />
Chapter 10 · Databases 219
The ResultSet Variants<br />
accordance with com.sun.star.sdbc.ResultSetConcurrency).<br />
ResultSetType (const)<br />
specifications regarding type of ResultSets ( specifications in accordance with<br />
com.sun.star.sdbc.ResultSetType).<br />
The values defined in com.sun.star.sdbc.ResultSetConcurrency are:<br />
UPDATABLE<br />
READ_ONLY<br />
ResultSet permits values to be modified<br />
ResultSet does not permit modifications<br />
The com.sun.star.sdbc.ResultSetConcurrency group of constants provides the<br />
following specifications:<br />
FORWARD_ONLY<br />
ResultSet only permits forward navigation<br />
SCROLL_INSENSITIVE<br />
ResultSet permits any type of navigation, changes to the original data are,<br />
however, not noted<br />
SCROLL_SENSITIVE<br />
ResultSet permits any type of navigation, changes to the original data impact<br />
on the ResultSet<br />
Note – A ResultSet containing the READ_ONLY and SCROLL_INSENSITIVE properties<br />
corresponds to a record set of the Snapshot type in ADO and DAO.<br />
When using the ResultSet's UPDATEABLE and SCROLL_SENSITIVE properties, the<br />
scope of function of a ResultSet is comparable with a Dynaset type Recordset from<br />
ADO and DAO.<br />
Methods for Navigation in ResultSets<br />
If a ResultSet is a SCROLL_INSENSITIVE or SCROLL_SENSITIVE type, it supports a<br />
whole range of methods for navigation in the stock of data. The central methods are:<br />
220 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
next()<br />
navigation to the next data record<br />
previous()<br />
first()<br />
last()<br />
navigation to the previous data record<br />
navigation to the first data record<br />
navigation to the last data record<br />
beforeFirst()<br />
navigation to before the first data record<br />
afterLast()<br />
navigation to after the last data record<br />
Methods for Navigation in ResultSets<br />
All methods return a Boolean parameter which specifies whether the navigation was<br />
successful.<br />
To determine the current cursor position, the following test methods are provided and<br />
all return a Boolean value:<br />
isBeforeFirst()<br />
ResultSet is before the first data record<br />
isAfterLast()<br />
isFirst()<br />
isLast()<br />
ResultSet is after the last data record<br />
ResultSet is the first data record<br />
ResultSet is the last data record<br />
Modifying Data Records<br />
If a ResultSet has been created with the ResultSetConcurrency = UPDATEABLE value,<br />
then its content can be edited. This only applies for as long as the SQL command<br />
allows the data to be re-written to the database (depends on principle). This is not, for<br />
Chapter 10 · Databases 221
Modifying Data Records<br />
example, possible with complex SQL commands with linked columns or accumulated<br />
values.<br />
The ResultSet object provides Update methods for modifying values, which are<br />
structured in the same way as the get methods for retrieving values. The<br />
updateString method, for example, allows a string to be written.<br />
After modification, the values must be transferred into the database using the<br />
updateRow()method. The call must take place before the next navigation command,<br />
otherwise the values will be lost.<br />
If an error is made during the modifications, this can be undone using the<br />
cancelRowUpdates()method. This call is only available provided that the data has not<br />
be re-written into the database using updateRow().<br />
222 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
11<br />
C H A P T E R 1 1<br />
11 Dialogs<br />
You can add custom dialog windows and forms to <strong>OpenOffice</strong>.<strong>org</strong> documents. These<br />
in turn can be linked to <strong>OpenOffice</strong>.<strong>org</strong> Basic macros to considerably extend the<br />
usage range of <strong>OpenOffice</strong>.<strong>org</strong> Basic. Dialogs can, for example, display database<br />
information or guide users through a step-by-step process of creating a new<br />
document in the form of a Wizard.<br />
Working With Dialogs<br />
<strong>OpenOffice</strong>.<strong>org</strong> Basic dialogs consist of a dialog window that can contain text fields,<br />
list boxes, radio buttons, and other control elements.<br />
Creating Dialogs<br />
You can create and structure dialogs using the <strong>OpenOffice</strong>.<strong>org</strong> dialog editor:<br />
223
Creating Dialogs<br />
You can drag the control elements from the design pallet (right) into the dialog area,<br />
and define their position and size.<br />
The example shows a dialog that contains a label and a list box.<br />
224 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
You can open a dialog with the following code:<br />
Dim Dlg As Object<br />
DialogLibraries.LoadLibrary("Standard")<br />
Dlg = CreateUnoDialog(DialogLibraries.Standard.DlgDef)<br />
Dlg.Execute()<br />
Dlg.dispose()<br />
Creating Dialogs<br />
CreateUnoDialog creates an object called Dlg that references the associated dialog.<br />
Before you can create the dialog, you must ensure that the library it uses (in this<br />
Chapter 11 · Dialogs 225
Creating Dialogs<br />
example, the Standard library) is loaded. The LoadLibrary method performs this task.<br />
Once the Dlg dialog object has been initialized, you can use the Execute method to<br />
display the dialog. Dialogs such as this one are described as modal because they do<br />
not permit any other program action until they are closed. While this dialog is open,<br />
the program remains in the Execute call.<br />
The dispose method at the end of the code approves the resources used by the<br />
dialog once the program ends.<br />
Closing Dialogs<br />
Closing With OK or Cancel<br />
If a dialog contains an OK or a Cancel button, the dialog is automatically closed<br />
when you click one of these buttons. More information about working with these<br />
buttons is discussed in Dialog Control Elements in Detail.<br />
If you close a dialog by clicking the OK button, the Execute-method returns a return<br />
value of 1, otherwise a value of 0 is returned.<br />
Dim Dlg As Object<br />
DialogLibraries.LoadLibrary("Standard")<br />
Dlg = CreateUnoDialog(DialogLibraries.Standard.MyDialog)<br />
Select Case Dlg.Execute()<br />
Case 1<br />
MsgBox "Ok pressed"<br />
Case 0<br />
MsgBox "Cancel pressed"<br />
End Select<br />
Closing With the Close Button in the Title Bar<br />
You can close a dialog by clicking the close button on the title bar of the dialog<br />
window. The Execute method of the dialog returns the value 0, which is the same as<br />
when you click Cancel.<br />
226 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Closing With an Explicit Program Call<br />
You can also close an open dialog window with the endExecute method:<br />
Dlg.endExecute()<br />
Closing Dialogs<br />
Access to Individual Control Elements<br />
A dialog can contain any number of control elements. You can access these elements<br />
through the getControl method that returns the control element by name.<br />
Dim Ctl As Object<br />
Ctl = Dlg.getControl("MyButton")<br />
Ctl.Label = "New Label"<br />
This code determines the object for the MyButton control element and then initializes<br />
the Ctl object variable with a reference to the element. Finally the code sets the<br />
Label property of the control element to the New Label value.<br />
Note – Unlike <strong>OpenOffice</strong>.<strong>org</strong> Basic identifiers, the names of control elements are<br />
case sensitive.<br />
Working With the Model of Dialogs and<br />
Control Elements<br />
The division between visible program elements (View) and the data or documents<br />
behind them (Model) occurs at many places in <strong>OpenOffice</strong>.<strong>org</strong> API. In addition to the<br />
methods and properties of control elements, both dialog and control element objects<br />
have a subordinate Model object. This object allows you to directly access the content<br />
of a dialog or control element.<br />
In dialogs, the distinction between data and depiction is not always as clear as in<br />
other API areas of <strong>OpenOffice</strong>.<strong>org</strong>. Elements of the API are available through both<br />
the View and the Model.<br />
The Model property provides program-controlled access to the model of dialog and<br />
control element objects.<br />
Chapter 11 · Dialogs 227
Working With the Model of Dialogs and Control Elements<br />
Properties<br />
Dim cmdNext As Object<br />
cmdNext = Dlg.getControl("cmdNext")<br />
cmdNext.Model.Enabled = False<br />
This example deactivates the cmdNtext button in the Dlg dialog with the aid of the<br />
model object from cmdNtext.<br />
Name and Title<br />
Every control element has its own name that can be queried using the following<br />
model property:<br />
Model.Name (String)<br />
control element name<br />
You can specify the title that appears in the title bar of a dialog with the following<br />
model property:<br />
Model.Title (String)<br />
dialog title (only applies to dialogs)<br />
Position and Size<br />
You can query the size and position of a control element using the following<br />
properties of the model object:<br />
Model.Height (long)<br />
height of control element (in ma units)<br />
Model.Width (long)<br />
width of control element (in ma units)<br />
228 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Model.PositionX (long)<br />
Position and Size<br />
X-position of control element, measured from the left inner edge of the dialog<br />
(in ma units)<br />
Model.PositionY (long)<br />
Y-position of control element, measured from top inner edge of the dialog (in<br />
ma units)<br />
To ensure platform independence for the appearance of dialogs, <strong>OpenOffice</strong>.<strong>org</strong> uses<br />
the Map AppFont (ma) internal unit to specify the position and size within dialogs. An<br />
ma unit is defined as being one eighth of the average height of a character from the<br />
system font defined in the operating system and one quarter of its width. By using ma<br />
units, <strong>OpenOffice</strong>.<strong>org</strong> ensures that a dialog looks the same on different systems<br />
under different system settings.<br />
If you want to change the size or position of control elements for runtime, determine<br />
the total size of the dialog and adjust the values for the control elements to the<br />
corresponding part ratios.<br />
Note – The Map AppFont (ma) replaces the Twips unit to achieve better platform<br />
independence.<br />
Focus and Tabulator Sequence<br />
You can navigate through the control elements in any dialog by pressing the Tab key.<br />
The following properties are available in this context in the control elements model:<br />
Model.Enabled (Boolean)<br />
activates the control element<br />
Model.Tabstop (Boolean)<br />
allows the control element to be reached through the Tab key<br />
Model.TabIndex (Long)<br />
position of control element in the order of activation<br />
Finally, the control element provides a getFocus method that ensures that the<br />
underlying control element receives the focus:<br />
Chapter 11 · Dialogs 229
Focus and Tabulator Sequence<br />
getFocus<br />
control element receives the focus (only for dialogs)<br />
Multi-Page Dialogs<br />
A dialog in <strong>OpenOffice</strong>.<strong>org</strong> can have more than one tab page. The Step property of a<br />
dialog defines the current tab page of the dialog whereas the Step property for a<br />
control element specifies the tab page where the control element is to be displayed.<br />
The Step-value of 0 is a special case. If you set this value to zero in a dialog, all of<br />
the control elements are visible regardless of their Step value. Similarly, if you set this<br />
value to zero for a control element, the element is displayed on all of the tab pages in<br />
a dialog.<br />
230 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Multi-Page Dialogs<br />
In the preceding example, you can also assign the Step value of 0 to the dividing line<br />
as well as the Cancel, Prev, Next, and Done buttons to display these elements on all<br />
pages. You can also assign the elements to an individual tab page (for example page<br />
1).<br />
The following program code shows how the Step value in event handlers of the Next<br />
and Prev buttons can be increased or reduced and changes the status of the buttons.<br />
Sub cmdNext_Initiated<br />
Chapter 11 · Dialogs 231
Multi-Page Dialogs<br />
Dim cmdNext As Object<br />
Dim cmdPrev As Object<br />
cmdPrev = Dlg.getControl("cmdPrev")<br />
cmdNext = Dlg.getControl("cmdNext")<br />
cmdPrev.Model.Enabled = Not cmdPrev.Model.Enabled<br />
cmdNext.Model.Enabled = False<br />
Dlg.Model.Step = Dlg.Model.Step + 1<br />
End Sub<br />
Sub cmdPrev_Initiated<br />
Dim cmdNext As Object<br />
Dim cmdPrev As Object<br />
cmdPrev = Dlg.getControl("cmdPrev")<br />
cmdNext = Dlg.getControl("cmdNext")<br />
cmdPrev.Model.Enabled = False<br />
cmdNext.Model.Enabled = True<br />
Dlg.Model.Step = Dlg.Model.Step - 1<br />
End Sub<br />
A global Dlg variable that references an open dialog must be included to make this<br />
example possible. The dialog then changes its appearance as follows:<br />
232 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Events<br />
Multi-Page Dialogs<br />
<strong>OpenOffice</strong>.<strong>org</strong> dialogs and forms are based on an event-oriented programming<br />
model where you can assign event handlers to the control elements. An event<br />
handler runs a predefined procedure when a particular action occurs. You can also<br />
edit documents or open databases with event handling as well as access other<br />
control elements.<br />
<strong>OpenOffice</strong>.<strong>org</strong> control elements recognize different types of events that can be<br />
triggered in different situations. These event types can be divided into four groups:<br />
Mouse control: Events that correspond to mouse actions (for example, simple<br />
mouse movements or a click on a particular screen location).<br />
Keyboard control: Events that are triggered by keyboard strokes.<br />
Focus modification: Events that <strong>OpenOffice</strong>.<strong>org</strong> performs when control elements<br />
are activated or deactivated.<br />
Control element-specific events: Events that only occur in relation to certain<br />
control elements.<br />
Chapter 11 · Dialogs 233
Multi-Page Dialogs<br />
When you work with events, make sure that you create the associated dialog in the<br />
<strong>OpenOffice</strong>.<strong>org</strong> development environment and that it contains the required control<br />
elements or documents (if you apply the events to a form).<br />
The figure above shows the <strong>OpenOffice</strong>.<strong>org</strong> Basic development environment with a<br />
dialog window that contains two list boxes. You can move the data from one list to the<br />
other using the buttons between the two list boxes.<br />
If you want to display the layout on screen, then you should create the associated<br />
<strong>OpenOffice</strong>.<strong>org</strong> Basic procedures so that they can be called up by the event<br />
234 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Multi-Page Dialogs<br />
handlers. Even though you can use these procedures in any module, it is best to limit<br />
their use to two modules. To make your code easier to read, you should assign<br />
meaningful names to these procedures. Jumping directly to a general program<br />
procedure from a macro can result in unclear code. Instead, to simplify code<br />
maintenance and troubleshooting, you should create another procedure to serve as<br />
an entry point for event handling - even if it only executes a single call to the target<br />
procedure.<br />
The code in the following example moves an entry from the left to the right list box of<br />
a dialog.<br />
Sub cmdSelect_Initiated<br />
Dim objList As Object<br />
lstEntries = Dlg.getControl("lstEntries")<br />
lstSelection = Dlg.getControl("lstSelection")<br />
If lstEntries.SelectedItem > 0 Then<br />
lstSelection.AddItem(lstEntries.SelectedItem, 0)<br />
lstEntries.removeItems(lstEntries.SelectItemPos, 1)<br />
Else<br />
Beep<br />
End If<br />
End Sub<br />
If this procedure was created in <strong>OpenOffice</strong>.<strong>org</strong> Basic, you can assign it to an event<br />
required using the property window of the dialog editor.<br />
Chapter 11 · Dialogs 235
Multi-Page Dialogs<br />
The Assign Action dialog lists all of the available Events. To assign a macro to an<br />
event:<br />
1 Select the event<br />
2 Click Macro...<br />
3 Browse to and select the macro you want to assign<br />
4 Click OK<br />
Parameters<br />
The occurrence of a particular event is not always enough for an appropriate<br />
response. Additional information may be required. For example, to process a mouse<br />
click, you may need the screen position where the mouse button was pressed.<br />
In <strong>OpenOffice</strong>.<strong>org</strong> Basic, you can use object parameters to provide more information<br />
about an event to a procedure, for example:<br />
Sub ProcessEvent(Event As Object)<br />
236 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
End Sub<br />
Parameters<br />
The structure and properties of the Event object depend on the type of event that<br />
triggers the procedure call.<br />
Regardless of the type of event, all objects provide access to the relevant control<br />
element and its model. The control element can be reached using Event.Source and<br />
its model using Event.Source.Model.<br />
You can use these properties to trigger an event within an event handler.<br />
Mouse Events<br />
<strong>OpenOffice</strong>.<strong>org</strong> Basic recognizes the following mouse events:<br />
Mouse moved<br />
user moves mouse<br />
Mouse moved while key pressed<br />
user drags mouse while holding down a key<br />
Mouse button pressed<br />
user presses a mouse button<br />
Mouse button released<br />
user releases a mouse button<br />
Mouse outside<br />
user moves mouse outside of the current window<br />
The structure of the associated event objects is defined in the<br />
com.sun.star.awt.MouseEvent structure which provides the following information:<br />
Buttons (short)<br />
button pressed (one or more constants in accordance with<br />
com.sun.star.awt.MouseButton)<br />
X (long)<br />
X-coordinate of mouse, measured in pixels from the top left corner of the<br />
control element<br />
Chapter 11 · Dialogs 237
Mouse Events<br />
Y (long)<br />
Y-coordinate of mouse, measured in pixels from the top left corner of the control<br />
element<br />
ClickCount (long)<br />
number of clicks associated with the mouse event (if <strong>OpenOffice</strong>.<strong>org</strong> can<br />
respond fast enough, ClickCount is also 1 for a double-click because only an<br />
individual event is initiated)<br />
The constants defined in com.sun.star.awt.MouseButton for the mouse buttons are:<br />
LEFT<br />
RIGHT<br />
MIDDLE<br />
left mouse button<br />
right mouse button<br />
middle mouse button<br />
The following example outputs the mouse position as well as the mouse button that<br />
was pressed:<br />
Sub MouseUp(Event As Object)<br />
Dim Msg As String<br />
Msg = "Keys: "<br />
If Event.Buttons AND com.sun.star.awt.MouseButton.LEFT Then<br />
Msg = Msg & "LEFT "<br />
End If<br />
If Event.Buttons AND com.sun.star.awt.MouseButton.RIGHT Then<br />
Msg = Msg & "RIGHT "<br />
End If<br />
If Event.Buttons AND com.sun.star.awt.MouseButton.MIDDLE Then<br />
Msg = Msg & "MIDDLE "<br />
End If<br />
Msg = Msg & Chr(13) & "Position: "<br />
Msg = Msg & Event.X & "/" & Event.Y<br />
MsgBox Msg<br />
End Sub<br />
Note – The VBA Click and Doubleclick events are not available in <strong>OpenOffice</strong>.<strong>org</strong><br />
Basic. Instead use the <strong>OpenOffice</strong>.<strong>org</strong> Basic MouseUp event for the click event and<br />
imitate the Doubleclick event by changing the application logic.<br />
238 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Keyboard Events<br />
The following keyboard events are available in <strong>OpenOffice</strong>.<strong>org</strong> Basic:<br />
Key pressed<br />
user presses a key.<br />
Key released<br />
user releases a key<br />
Keyboard Events<br />
Both events relate to logical key actions and not to physical actions. If the user<br />
presses several keys to output a single character (for example, to add an accent to a<br />
character), then <strong>OpenOffice</strong>.<strong>org</strong> Basic only creates one event.<br />
A single key action on a modification key, such as the Shift key or the Alt key does not<br />
create an independent event.<br />
Information about a pressed key is provided by the event object that <strong>OpenOffice</strong>.<strong>org</strong><br />
Basic supplies to the procedure for event handling. It contains the following<br />
properties:<br />
KeyCode (short)<br />
code of the pressed key (default values in accordance with<br />
com.sun.star.awt.Key)<br />
KeyChar (String)<br />
character that is entered (taking the modification keys into consideration)<br />
The following example uses the KeyCode property to establish if the Enter key, the Tab<br />
key, or one of the other control keys has been pressed. If one of these keys has been<br />
pressed, the name of the key is returned, otherwise the character that was typed is<br />
returned:<br />
Sub KeyPressed(Event As Object)<br />
Dim Msg As String<br />
Select Case Event.KeyCode<br />
Case com.sun.star.awt.Key.RETURN<br />
Msg = "Return pressed"<br />
Case com.sun.star.awt.Key.TAB<br />
Msg = "Tab pressed"<br />
Case com.sun.star.awt.Key.DELETE<br />
Msg = "Delete pressed"<br />
Case com.sun.star.awt.Key.ESCAPE<br />
Msg = "Escape pressed"<br />
Case com.sun.star.awt.Key.DOWN<br />
Msg = "Down pressed"<br />
Chapter 11 · Dialogs 239
Keyboard Events<br />
Case com.sun.star.awt.Key.UP<br />
Msg = "Up pressed"<br />
Case com.sun.star.awt.Key.LEFT<br />
Msg = "Left pressed"<br />
Case com.sun.star.awt.Key.RIGHT<br />
Msg = "Right pressed"<br />
Case Else<br />
Msg = "Character " & Event.KeyChar & " entered"<br />
End Select<br />
MsgBox Msg<br />
End Sub<br />
Information about other keyboard constants can be found in the API Reference under<br />
the com.sun.star.awt.Key group of constants.<br />
Focus Events<br />
Focus events indicate if a control element receives or loses focus. You can use these<br />
events to, for example, determine if a user has finished processing a control element<br />
so that you can update other elements of a dialog. The following focus events are<br />
available:<br />
When receiving focus<br />
element receives focus<br />
When losing focus<br />
element loses focus<br />
The Event objects for the focus events are structured as follows:<br />
FocusFlags (short)<br />
cause of focus change (default value in accordance with<br />
com.sun.star.awt.FocusChangeReason)<br />
NextFocus (Object)<br />
object that receives focus (only for the When losing focus event)<br />
Temporary (Boolean)<br />
the focus is temporarily lost<br />
240 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Control Element-Specific Events<br />
Control Element-Specific Events<br />
In addition to the preceding events, which are supported by all control elements,<br />
there are also some control element-specific events that are only defined for certain<br />
control elements. The most important of these events are:<br />
When Item Changed<br />
the value of a control element changes<br />
Item Status Changed<br />
the status of a control element changes<br />
Text modified<br />
the text of a control element changes<br />
When initiating<br />
an action that can be performed when the control element is triggered (for<br />
example, a button is pressed)<br />
When you work with events, note that some events, such as the When initiating<br />
event, can be initiated each time you click the mouse on some control elements (for<br />
example, on radio buttons). No action is performed to check if the status of the<br />
control element has actually changed. To avoid such “blind events”, save the old<br />
control element value in a global variable, and then check to see if the value has<br />
changed when an event is executing.<br />
The When initiating event is also noteworthy for the following reasons:<br />
This event is initiated by either a key-press or a mouse button. Thus, it provides a<br />
consistent interface for users who navigate by mouse or by keyboard.<br />
When the Repeat property of a command button is set to True, this event is the<br />
one which is repeatedly sent, as long as the triggering action (key down or mousebutton<br />
down) remains in effect.<br />
The properties for the Item Status Changed event are:<br />
Selected (long)<br />
currently selected entry<br />
Highlighted (long)<br />
currently highlighted entry<br />
ItemId (long)<br />
ID of entry<br />
Chapter 11 · Dialogs 241
Control Element-Specific Events<br />
Dialog Control Elements<br />
<strong>OpenOffice</strong>.<strong>org</strong> Basic recognizes a range of control elements which can be divided<br />
into the following groups:<br />
Entry fields Buttons Selection<br />
lists<br />
Text fields Standard buttons List boxes<br />
Date fields Checkboxes Combo-boxes<br />
Time fields<br />
Numerical fields<br />
Currency fields<br />
Fields adopting<br />
any format<br />
Radio Buttons<br />
Buttons<br />
A button performs an action when you click it.<br />
Other<br />
Scrollbars (horizontal and<br />
vertical)<br />
Fields of groups<br />
Progress bars<br />
Dividing lines (horizontal<br />
and vertical)<br />
Graphics<br />
File selection fields<br />
The simplest scenario is for the button to trigger a When Initiating event when it is<br />
clicked by a user. You can also link another action to the button to close a dialog<br />
using the PushButtonType property. When you click a button that has this property set<br />
to the value of 0, the dialog remains unaffected. If you click a button that has this<br />
property set to the value of 1, the dialog is closed, and the Execute method of the<br />
dialog returns the value 1 (dialog sequence has been ended correctly). If the<br />
PushButtonType has the value of 2, the dialog is closed and the Execute method of<br />
the dialog returns the value 0 (dialog closed). In the Dialog Editor, the property values<br />
are shown symbolically, as Default (0), Okay (1), and Cancel (2).<br />
The following are some of the properties that are available through the button model:<br />
Model.BackgroundColor (long)<br />
color of background<br />
Model.DefaultButton (Boolean)<br />
The button is used as the default value and responds to the Enter key if it has<br />
no focus<br />
242 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Model.FontDescriptor (struct)<br />
structure that specifies the details of the font to be used (in accordance with<br />
com.sun.star.awt.FontDescriptor structure)<br />
Model.Label (String)<br />
label that is displayed on the button<br />
Model.Printable (Boolean)<br />
the control element can be printed<br />
Model.TextColor (Long)<br />
text color of the control element<br />
Model.HelpText (String)<br />
help text that is displayed when you move the mouse cursor over the control<br />
element<br />
Model.HelpURL (String)<br />
URL of the online help for the corresponding control element<br />
PushButtonType (short)<br />
action that is linked to the button (0: no action, 1: OK, 2: Cancel)<br />
Option Buttons<br />
Buttons<br />
These buttons are generally used in groups and allow you to select from one of<br />
several options. When you select an option, all of the other options in the group are<br />
deactivated. This ensures that at any one time, only one option button is set.<br />
An option button control element provides two properties:<br />
State (Boolean)<br />
activates the button<br />
Label (String)<br />
label that is displayed on the button<br />
You can also use the following properties from the model of the option buttons:<br />
Model.FontDescriptor (struct)<br />
structure with details of the font to be used (in accordance with<br />
Chapter 11 · Dialogs 243
Option Buttons<br />
com.sun.star.awt.FontDescriptor)<br />
Model.Label (String)<br />
label that is displayed on the control element<br />
Model.Printable (Boolean)<br />
control element can be printed<br />
Model.State (Short)<br />
if this property is equal to 1, the option is activated, otherwise it is deactivated<br />
Model.TextColor (Long)<br />
text color of control element<br />
Model.HelpText (String)<br />
help text that is displayed when the mouse cursor rests over the control<br />
element<br />
Model.HelpURL (String)<br />
URL of online help for the corresponding control element<br />
To combine several option buttons in a group, you must position them one after<br />
another in the activation sequence without any gaps (Model.TabIndex property,<br />
described as Order in the dialog editor). If the activation sequence is interrupted by<br />
another control element, then <strong>OpenOffice</strong>.<strong>org</strong> automatically starts with a new control<br />
element group that can be activated regardless of the first group of control elements.<br />
Note – Unlike VBA, you cannot insert option buttons in a group of control elements<br />
in <strong>OpenOffice</strong>.<strong>org</strong> Basic. The grouping of control elements in <strong>OpenOffice</strong>.<strong>org</strong> Basic is<br />
only used to ensure a visual division by drawing a frame around the control elements.<br />
Checkboxes<br />
Checkboxes are used to record a Yes or No value and depending on the mode, they<br />
can adopt two or three states. In addition to the Yes and No states, a check box can<br />
have an in-between state if the corresponding Yes or No status has more than one<br />
meaning or is unclear.<br />
Checkboxes provide the following properties:<br />
244 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
State (Short)<br />
state of the checkbox (0: no, 1: yes, 2: in-between state)<br />
Label (String)<br />
label for the control element<br />
enableTriState (Boolean)<br />
Checkboxes<br />
in addition to the activated and deactivated states, you can also use the inbetween<br />
state<br />
The model object of a checkbox provides the following properties:<br />
Model.FontDescriptor (struct)<br />
structure with details of the font used (in accordance with<br />
com.sun.star.awt.FontDescriptor structure)<br />
Model.Label (String)<br />
label for the control element<br />
Model.Printable (Boolean)<br />
the control element can be printed<br />
Model.State (Short)<br />
state of the checkbox (0: no, 1: yes, 2: in-between state)<br />
Model.Tabstop (Boolean)<br />
the control element can be reached with the Tab key<br />
Model.TextColor (Long)<br />
text color of control element<br />
Model.HelpText (String)<br />
help text that is displayed when you rest the mouse cursor over the control<br />
element<br />
Model.HelpURL (String)<br />
URL of online help for the corresponding control element<br />
Text Fields<br />
Text fields allow users to type numbers and text. The<br />
Chapter 11 · Dialogs 245
Text Fields<br />
com.sun.star.awt.UnoControlEdit service forms the basis for text fields.<br />
A text field can contain one or more lines and can be edited or blocked for user<br />
entries. Text fields can also be used as special currency and numerical fields as well<br />
as screen fields for special tasks. As these control elements are based on the<br />
UnoControlEdit Uno service, their program-controlled handling is similar.<br />
Text fields provide the following properties:<br />
Text (String)<br />
current text<br />
SelectedText (String)<br />
currently highlighted text<br />
Selection (Struct)<br />
read-only highlighting of details (structure in accordance with<br />
com.sun.star.awt.Selection, with the Min and Max properties to specify the start<br />
and end of the current highlighting)<br />
MaxTextLen (short)<br />
maximum number of characters that you can type in the field<br />
Editable (Boolean)<br />
True activates the option for entering text, False blocks the entry option (the<br />
property cannot be called up directly but only through IsEditable)<br />
IsEditable (Boolean)<br />
the content of the control element can be changed, read-only<br />
The following properties are provided through the associated model object:<br />
Model.Align (short)<br />
orientation of text (0: left-aligned, 1: centered, 2: right-aligned)<br />
Model.BackgroundColor (long)<br />
color of the background of the control element<br />
Model.Border (short)<br />
type of border (0: no border, 1: 3D border, 2: simple border)<br />
Model.EchoChar (String)<br />
echo character for password fields<br />
246 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Model.FontDescriptor (struct)<br />
structure with details of font used (in accordance with<br />
com.sun.star.awt.FontDescriptor structure)<br />
Model.HardLineBreaks (Boolean)<br />
automatic line breaks are permanently inserted in the control element text<br />
Model.HScroll (Boolean)<br />
the text has a horizontal scrollbar<br />
Model.MaxTextLen (Short)<br />
maximum length of text, where 0 corresponds to no length limit<br />
Model.MultiLine (Boolean)<br />
permits entry to spans several lines<br />
Model.Printable (Boolean)<br />
the control element can be printed<br />
Model.ReadOnly (Boolean)<br />
the content of the control element is read-only<br />
Model.Tabstop (Boolean)<br />
the control element can be reached with the Tab key<br />
Model.Text (String)<br />
text associate with the control element<br />
Model.TextColor (Long)<br />
text color of control element<br />
Model.VScroll (Boolean)<br />
the text has a vertical scrollbar<br />
Model.HelpText (String)<br />
help text that is displayed when the mouse cursor rests over the control<br />
element<br />
Model.HelpURL (String)<br />
URL of online help for the corresponding control element<br />
Text Fields<br />
Chapter 11 · Dialogs 247
List Boxes<br />
List Boxes<br />
List boxes (com.sun.star.awt.UnoControlListBox service) support the following<br />
properties:<br />
ItemCount (Short)<br />
number of elements, read-only<br />
SelectedItem (String)<br />
text of highlighted entry, read-only<br />
SelectedItems (Array Of Strings)<br />
data field with highlighted entries, read-only<br />
SelectedItemPos (Short)<br />
number of the entry highlighted at present, read-only<br />
SelectedItemsPos (Array of Short)<br />
data field with the number of highlighted entries (for lists which support multiple<br />
selection), read-only<br />
MultipleMode (Boolean)<br />
True activates the option for multiple selection of entries, False blocks multiple<br />
selections (the property cannot be called up directly but only through<br />
IsMultipleMode)<br />
IsMultipleMode (Boolean)<br />
permits multiple selection within lists, read-only<br />
List boxes provide the following methods:<br />
addItem (Item, Pos)<br />
enters the string specified in the Item into the list at the Pos position<br />
addItems (ItemArray, Pos)<br />
enters the entries listed in the string's ItemArray data field into the list at the Pos<br />
position<br />
removeItems (Pos, Count)<br />
removes Count entries as of the Pos position<br />
selectItem (Item, SelectMode)<br />
activates or deactivates highlighting for the element specified in the string Item<br />
depending on the SelectMode Boolean variable<br />
248 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
makeVisible (Pos)<br />
scrolls through the list field so that the entry specified with Pos is visible<br />
The model object of the list boxes provides the following properties:<br />
Model.BackgroundColor (long)<br />
background color of control element<br />
Model.Border (short)<br />
type of border (0: no border, 1: 3D border, 2: simple border)<br />
Model.FontDescriptor (struct)<br />
structure with details of font used (in accordance with<br />
com.sun.star.awt.FontDescriptor structure)<br />
Model.LineCount (Short)<br />
number of lines in control element<br />
Model.MultiSelection (Boolean)<br />
permits multiple selection of entries<br />
Model.SelectedItems (Array of Strings)<br />
list of highlighted entries<br />
Model.StringItemList (Array of Strings)<br />
list of all entries<br />
Model.Printable (Boolean)<br />
the control element can be printed<br />
Model.ReadOnly (Boolean)<br />
the content of the control element is read-only<br />
Model.Tabstop (Boolean)<br />
the control element can be reached with the Tab key<br />
Model.TextColor (Long)<br />
text color of control element<br />
Model.HelpText (String)<br />
automatically displayed help text which is displayed if the mouse cursor is<br />
above the control element<br />
Model.HelpURL (String)<br />
URL of online help for the corresponding control element<br />
List Boxes<br />
Chapter 11 · Dialogs 249
List Boxes<br />
The VBA option for issuing list entries with a numerical additional value (ItemData)<br />
does not exist in <strong>OpenOffice</strong>.<strong>org</strong> Basic. If you want to administer a numerical value<br />
(for example a database ID) in addition to the natural language text, you must create<br />
an auxiliary data field that administers in parallel to the list box.<br />
250 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
12<br />
C H A P T E R 1 2<br />
12 Forms<br />
In many respects, the structure of <strong>OpenOffice</strong>.<strong>org</strong> forms corresponds to the dialogs.<br />
There are, however, a few key differences:<br />
Dialogs appear in the form of one single dialog window, which is displayed over<br />
the document and does not permit any actions other than dialog processing until<br />
the dialog is ended. Forms, on the other hand, are displayed directly in the<br />
document, just like drawing elements.<br />
A dialog editor is provided for creating dialogs, and this can be found in the<br />
<strong>OpenOffice</strong>.<strong>org</strong> Basic development environment. Forms are created using the<br />
Form Controls and the Form Design Toolbar directly within the document.<br />
Whereas the dialog functions are available in all <strong>OpenOffice</strong>.<strong>org</strong> documents, the<br />
full scope of the form functions are only available in text and spreadsheets.<br />
The control elements of a form can be linked with an external database table. This<br />
function is not available in dialogs.<br />
The control elements of dialogs and forms differ in several aspects.<br />
Users who want to provide their forms with their own methods for event handling,<br />
should refer to the Dialogs chapter. The mechanisms explained there are identical to<br />
those for forms.<br />
251
Forms<br />
Working With Forms<br />
<strong>OpenOffice</strong>.<strong>org</strong> forms may contain text fields, list boxes, radio buttons, and a range of<br />
other control elements, which are inserted directly in a text or spreadsheet. The Form<br />
Functions Toolbar is used for editing forms.<br />
A <strong>OpenOffice</strong>.<strong>org</strong> form may adopt one of two modes: the draft mode and the display<br />
mode. In draft mode, the position of control elements can be changed and their<br />
properties can be edited using a properties window.<br />
The Form Functions Toolbar is also used to switch between modes.<br />
Determining Object Forms<br />
<strong>OpenOffice</strong>.<strong>org</strong> positions the control elements of a form at drawing object level. The<br />
actual object form can be accessed through the Forms list at the drawing level. The<br />
objects are accessed as follows in text documents:<br />
Dim Doc As Object<br />
Dim DrawPage As Object<br />
Dim Form As Object<br />
Doc = StarDesktop.CurrentComponent<br />
DrawPage = Doc.DrawPage<br />
Form = DrawPage.Forms.GetByIndex(0)<br />
The GetByIndex method returns the form with the index number 0.<br />
When working with spreadsheets, an intermediate stage is needed for the Sheets list<br />
because the drawing levels are not located directly in the document but in the<br />
individual sheets:<br />
Dim Doc As Object<br />
Dim Sheet As Object<br />
Dim DrawPage As Object<br />
Dim Form As Object<br />
Doc = StarDesktop.CurrentComponent<br />
Sheet = Doc.Sheets.GetByIndex(0)<br />
DrawPage = Sheet.DrawPage<br />
Form = DrawPage.Forms.GetByIndex(0)<br />
As is already suggested by the GetByIndex method name, a document may contain<br />
several forms. This is useful, for example, if the contents of different databases are<br />
displayed within one document, or if a 1:n database relationship is displayed within a<br />
252 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
form. The option of creating sub-forms is also provided for this purpose.<br />
The Three Aspects of a Control<br />
Element Form<br />
A control element of a form has three aspects:<br />
Determining Object Forms<br />
The Model of the control element is the key object for the <strong>OpenOffice</strong>.<strong>org</strong> Basicprogrammer<br />
when working with control element forms.<br />
The counterpart to this is the View of the control element, which administers the<br />
display information.<br />
Since control element forms within the documents are administered like a special<br />
drawing element, there is also a Shape object which reflects the drawing<br />
element-specific properties of the control element (in particular its position and<br />
size).<br />
Accessing the Model of Control<br />
Element Forms<br />
The models of the control elements of a form are available through the GetByName<br />
method of the Object form:<br />
Dim Doc As Object<br />
Dim Form As Object<br />
Dim Ctl As Object<br />
Doc = StarDesktop.CurrentComponent<br />
Form = Doc.DrawPage.Forms.GetByIndex(0)<br />
Ctl = Form.getByName("MyListBox")<br />
The example determines the model of the MyListBox control element, which is<br />
located in the first form of the text document currently open.<br />
If you are not sure of the form of a control element, you can use the option for<br />
searching through all forms for the control element required:<br />
Dim Doc As Object<br />
Dim Forms As Object<br />
Dim Form As Object<br />
Dim Ctl As Object<br />
Dim I as Integer<br />
Chapter 12 · Forms 253
Accessing the Model of Control Element Forms<br />
Doc = StarDesktop.CurrentComponent<br />
Forms = Doc.Drawpage.Forms<br />
For I = 0 To Forms.Count - 1<br />
Form = Forms.GetbyIndex(I)<br />
If Form.HasByName("MyListBox") Then<br />
Ctl = Form.GetbyName("MyListBox")<br />
Exit Function<br />
End If<br />
Next I<br />
The example uses the HasByName method to check all forms of a text document to<br />
determine whether they contain a control element model called MyListBox. If a<br />
corresponding model is found, then a reference to this is saved in the Ctl variable<br />
and the search is terminated.<br />
Accessing the View of Control Element<br />
Forms<br />
To access the view of a control element form, you need the associated model. The<br />
view of the control element can then be determined with the assistance of the model<br />
and using the document controller.<br />
Dim Doc As Object<br />
Dim DocCrl As Object<br />
Dim Forms As Object<br />
Dim Form As Object<br />
Dim Ctl As Object<br />
Dim CtlView As Object<br />
Dim I as Integer<br />
Doc = StarDesktop.CurrentComponent<br />
DocCrl = Doc.getCurrentControler()<br />
Forms = Doc.Drawpage.Forms<br />
For I = 0 To Forms.Count - 1<br />
Form = Forms.GetbyIndex(I)<br />
If Form.HasByName("MyListBox") Then<br />
Ctl = Form.GetbyName("MyListBox")<br />
CtlView = DocCrl.GetControl(Ctl)<br />
Exit Function<br />
End If<br />
Next I<br />
The code listed in the example is very similar to the code listed in the previous<br />
example for determining a control element model. It uses not only the Doc document<br />
object but also the DocCrl document controller object which makes reference to the<br />
current document window. With the help of this controller object and the model of the<br />
254 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Accessing the View of Control Element Forms<br />
control element, it then uses the GetControl method to determine the view (CtlView<br />
variable) of the control element form.<br />
Accessing the Shape Object of Control<br />
Element Forms<br />
The method for accessing the shape objects of a control element also uses the<br />
corresponding drawing level of the document. To determine a special control element,<br />
all drawing elements of the drawing level must be searched through.<br />
Dim Doc As Object<br />
Dim Shape as Object<br />
Dim I as integer<br />
Doc = StarDesktop.CurrentComponent<br />
For i = 0 to Doc.DrawPage.Count - 1<br />
Shape = Doc.DrawPage(i)<br />
If HasUnoInterfaces(Shape, "com.sun.star.drawing.XControlShape") Then<br />
If Shape.Control.Name = "MyListBox" Then<br />
Exit Function<br />
End If<br />
End If<br />
Next<br />
The example checks all drawing elements to determine whether they support the<br />
com.sun.star.drawing.XControlShape interface needed for control element forms. If<br />
this is the case, the Control.Name property then checks whether the name of the<br />
control element is MyListBox. If this is true, the function ends the search.<br />
Determining the Size and Position of Control<br />
Elements<br />
As already mentioned, the size and position of control elements can be determined<br />
using the associated shape object. The control element shape, like all other shape<br />
objects, provides the Size and Position properties for this purpose:<br />
Size (struct)<br />
size of control element (com.sun.star.awt.Size data structure)<br />
Position (struct)<br />
position of control element (com.sun.star.awt.Point data structure)<br />
Chapter 12 · Forms 255
Accessing the Shape Object of Control Element Forms<br />
The following example shows how the position and size of a control element can be<br />
set using the associated shape object:<br />
Dim Shape As Object<br />
Point.x = 1000<br />
Point.y = 1000<br />
Size.Width = 10000<br />
Size.Height = 10000<br />
Shape.Size = Size<br />
Shape.Position = Point<br />
The shape object of the control element must already be known if the code is to<br />
function. If this is not the case, it must be determined using the preceding code.<br />
Control Element Forms<br />
The control elements available in forms are similar to those of dialogs. The selection<br />
ranges from simple text fields through list and combo boxes to various buttons.<br />
Below, you will find a list of the most important properties for control element forms.<br />
All properties form part of the associated model objects.<br />
In addition to the standard control elements, a table control element is also available<br />
for forms, which enables the complete incorporation of database tables. This is<br />
described in the Database Forms chapter.<br />
Buttons<br />
The model object of a form button provides the following properties:<br />
BackgroundColor (long)<br />
background color<br />
DefaultButton (Boolean)<br />
the button serves as a default value. In this case, it also responds to the entry<br />
button if it has no focus<br />
Enabled (Boolean)<br />
the control element can be activated<br />
256 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Tabstop (Boolean)<br />
the control element can be reached through the tabulator button<br />
TabIndex (Long)<br />
position of control element in activation sequence<br />
FontName (String)<br />
name of font type<br />
FontHeight (Single)<br />
height of character in points (pt)<br />
Tag (String)<br />
string containing additional information, which can be saved in the button for<br />
program-controlled access<br />
TargetURL (String)<br />
target URL for buttons of the URL type<br />
TargetFrame (String)<br />
Buttons<br />
name of window (or frame) in which TargetURL is to be opened when activating<br />
the button (for buttons of the URL type)<br />
Label (String)<br />
button label<br />
TextColor (Long)<br />
text color of control element<br />
HelpText (String)<br />
automatically displayed help text which is displayed if the mouse cursor is<br />
above the control element<br />
HelpURL (String)<br />
URL of online help for the corresponding control element<br />
ButtonType (Enum)<br />
action that is linked with the button (default value from<br />
com.sun.star.form.FormButtonType)<br />
Through the ButtonType property, you have the opportunity to define an action that is<br />
automatically performed when the button is pressed. The associated<br />
com.sun.star.form.FormButtonType group of constants provides the following values:<br />
Chapter 12 · Forms 257
Buttons<br />
PUSH<br />
SUBMIT<br />
RESET<br />
URL<br />
standard button<br />
end of form entry (particularly relevant for HTML forms)<br />
resets all values within the form to their original values<br />
call of the URL defined in TargetURL (is opened within the window which was<br />
specified through TargetFrame)<br />
The OK and Cancel button types provided in dialogs are not supported in forms.<br />
Option Buttons<br />
The following properties of an option button are available through its model object:<br />
Enabled (Boolean)<br />
the control element can be activated<br />
Tabstop (Boolean)<br />
the control element can be reached through the tab key<br />
TabIndex (Long)<br />
position of control element in the activation sequence<br />
FontName (String)<br />
name of font type<br />
FontHeight (Single)<br />
height of character in points (pt)<br />
Tag (String)<br />
string containing additional information, which can be saved in the button for<br />
program-controlled access<br />
Label (String)<br />
inscription of button<br />
258 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Printable (Boolean)<br />
the control element can be printed<br />
State (Short)<br />
if 1, the option is activated, otherwise it is deactivated<br />
RefValue (String)<br />
Option Buttons<br />
string for saving additional information (for example, for administering data<br />
record IDs)<br />
TextColor (Long)<br />
text color of control element<br />
HelpText (String)<br />
automatically displayed help text, which is displayed if the mouse cursor is<br />
above the control element<br />
HelpURL (String)<br />
URL of online help for the corresponding control element<br />
The mechanism for grouping option buttons distinguishes between the control<br />
elements for dialogs and forms. Whereas control elements appearing one after<br />
another in dialogs are automatically combined to form a group, grouping in forms is<br />
performed on the basis of names. To do this, all option buttons of a group must<br />
contain the same name. <strong>OpenOffice</strong>.<strong>org</strong> combines the grouped control elements into<br />
an array so that the individual buttons of a <strong>OpenOffice</strong>.<strong>org</strong> Basic program can be<br />
reached in the same way.<br />
The following example shows how the model of a control element group can be<br />
determined.<br />
Dim Doc As Object<br />
Dim Forms As Object<br />
Dim Form As Object<br />
Dim Ctl As Object<br />
Dim I as Integer<br />
Doc = StarDesktop.CurrentComponent<br />
Forms = Doc.Drawpage.Forms<br />
For I = 0 To Forms.Count - 1<br />
Form = Forms.GetbyIndex(I)<br />
If Form.HasByName("MyOptions") Then<br />
Ctl = Form. GetGroupbyName("MyOptions")<br />
Exit Function<br />
End If<br />
Next I<br />
The code corresponds to the previous example for determining a simple control<br />
Chapter 12 · Forms 259
Option Buttons<br />
element model. It searches through all forms in the current text document in a loop<br />
and uses the HasByName method to check whether the corresponding form contains<br />
an element with the MyOptions name it is searching for. If this is the case, then the<br />
model array is accessed using the GetGroupByName method (rather than the<br />
GetByName method to determine simple models).<br />
Checkboxes<br />
The model object of a checkbox form provides the following properties:<br />
Enabled (Boolean)<br />
the control element can be activated<br />
Tabstop (Boolean)<br />
the control element can be reached through the tab key<br />
TabIndex (Long)<br />
position of control element in the activation sequence<br />
FontName (String)<br />
name of font type<br />
FontHeight (Single)<br />
height of character in points (pt)<br />
Tag (String)<br />
string containing additional information, which can be saved in the button for<br />
program-controlled access<br />
Label (String)<br />
button label<br />
Printable (Boolean)<br />
the control element can be printed<br />
State (Short)<br />
if 1, the option is activated, otherwise it is deactivated<br />
RefValue (String)<br />
string for saving additional information (for example, for administrating data<br />
record IDs)<br />
260 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
TextColor (Long)<br />
text color of control element<br />
HelpText (String)<br />
automatically displayed help text, which is displayed if the mouse cursor is<br />
above the control element<br />
HelpURL (String)<br />
URL of online help for the corresponding control element<br />
Text Fields<br />
The model objects of text field forms offer the following properties:<br />
Align (short)<br />
orientation of text (0: left-aligned, 1: centered, 2: right-aligned)<br />
BackgroundColor (long)<br />
background color of control element<br />
Border (short)<br />
type of border (0: no border, 1: 3D border, 2: simple border)<br />
EchoChar (String)<br />
echo character for password field<br />
FontName (String)<br />
name of font type<br />
FontHeight (Single)<br />
height of character in points (pt)<br />
HardLineBreaks (Boolean)<br />
Checkboxes<br />
the automatic line breaks are permanently inserted in the text of the control<br />
element<br />
HScroll (Boolean)<br />
the text has a horizontal scrollbar<br />
MaxTextLen (Short)<br />
maximum length of text; if 0 is specified, there are no limits<br />
Chapter 12 · Forms 261
Text Fields<br />
MultiLine (Boolean)<br />
permits multi-line entries<br />
Printable (Boolean)<br />
the control element can be printed<br />
ReadOnly (Boolean)<br />
the content of the control element is read-only<br />
Enabled (Boolean)<br />
the control element can be activated<br />
Tabstop (Boolean)<br />
the control element can be reached through the tab key<br />
TabIndex (Long)<br />
position of the control element in the activation sequence<br />
FontName (String)<br />
name of font type<br />
FontHeight (Single)<br />
height of character in points (pt)<br />
Text (String)<br />
text of control element<br />
TextColor (Long)<br />
text color of control element<br />
VScroll (Boolean)<br />
the text has a vertical scrollbar<br />
HelpText (String)<br />
automatically displayed help text, which is displayed if the mouse cursor is<br />
above the control element<br />
HelpURL (String)<br />
URL of online help for the corresponding control element<br />
262 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
List Boxes<br />
The model object of the list box forms provides the following properties:<br />
BackgroundColor (long)<br />
background color of control element<br />
Border (short)<br />
type of border (0: no border, 1: 3D frame, 2: simple frame)<br />
FontDescriptor (struct)<br />
structure with details of font to be used (in accordance with<br />
com.sun.star.awt.FontDescriptor structure)<br />
LineCount (Short)<br />
number of lines of control element<br />
MultiSelection (Boolean)<br />
permits multiple selection of entries<br />
SelectedItems (Array of Strings)<br />
list of highlighted entries<br />
StringItemList (Array of Strings)<br />
list of all entries<br />
ValueItemList (Array of Variant)<br />
list containing additional information for each entry (for example, for<br />
administrating data record IDs)<br />
Printable (Boolean)<br />
the control element can be printed<br />
ReadOnly (Boolean)<br />
the content of the control element is read-only<br />
Enabled (Boolean)<br />
the control element can be activated<br />
Tabstop (Boolean)<br />
the control element can be reached through the tab key<br />
TabIndex (Long)<br />
position of control element in the activation sequence<br />
List Boxes<br />
Chapter 12 · Forms 263
List Boxes<br />
FontName (String)<br />
name of font type<br />
FontHeight (Single)<br />
height of character in points (pt)<br />
Tag (String)<br />
string containing additional information which can be saved in the button for<br />
program-controlled access<br />
TextColor (Long)<br />
text color of control element<br />
HelpText (String)<br />
automatically displayed help text, which is displayed if the mouse cursor is<br />
above the control element<br />
HelpURL (String)<br />
URL of online help for the corresponding control element<br />
Note – Through their ValueItemList property, list box forms provide a counterpart to<br />
the VBA property, ItemData, through which you can administer additional information<br />
for individual list entries.<br />
Furthermore, the following methods are provided though the view object of the list<br />
box:<br />
addItem (Item, Pos)<br />
inserts the string specified in the Item at the Pos position in the list<br />
addItems (ItemArray, Pos)<br />
inserts the entries listed in the string's ItemArray data field in the list at the Pos<br />
position<br />
removeItems (Pos, Count)<br />
removes Count entries as of the Pos position<br />
selectItem (Item, SelectMode)<br />
activates or deactivates the highlighting for the element specified in the string<br />
Item depending on the SelectMode variable<br />
makeVisible (Pos)<br />
scrolls through the list field so that the entry specified by Pos is visible<br />
264 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009
Database Forms<br />
List Boxes<br />
<strong>OpenOffice</strong>.<strong>org</strong> forms can be directly linked to a database. The forms created in this<br />
way provide all the functions of a full database front end without requiring<br />
independent programming work.<br />
You can page through and search in the selected tables and queries, as well as<br />
change data records and insert new data records. <strong>OpenOffice</strong>.<strong>org</strong> automatically<br />
ensures that the relevant data is retrieved from the database, and that any changes<br />
made are written back to the database.<br />
A database form corresponds to a standard <strong>OpenOffice</strong>.<strong>org</strong> form. In addition to the<br />
standard properties, the following database-specific properties must also be set in the<br />
form:<br />
DataSourceName (String)<br />
name of data source (refer to Database Access; the data source must be<br />
globally created in <strong>OpenOffice</strong>.<strong>org</strong>)<br />
Command (String)<br />
name of table, query, or the SQL select command to which a link is to be made<br />
CommandType (Const)<br />
specifies whether the Command is a table, a query or a SQL command (value<br />
from com.sun.star.sdb.CommandType enumeration)<br />
The com.sun.star.sdb.CommandType enumeration covers the following values:<br />
TABLE<br />
QUERY<br />
Table<br />
COMMAND<br />
Query<br />
SQL command<br />
The database fields are assigned to the individual control elements through this<br />
property:<br />
DataField (String)<br />
name of linked database field<br />
Chapter 12 · Forms 265
Tables<br />
Tables<br />
Another control element is provided for work with databases, the table control<br />
element. This represents the content of a complete database table or query. In the<br />
simplest scenario, a table control element is linked to a database using the autopilot<br />
form, which links all columns with the relevant database fields in accordance with the<br />
user specifications.<br />
266 <strong>OpenOffice</strong>.<strong>org</strong> 3.1 <strong>BASIC</strong> <strong>Guide</strong> · April 2009