BG3400 BasicProgrammersGuide

LibreOffice 3.
4 Basic Programmer's Guide
Copyright
The contents of this document are subject to the Public Documentation License. You may only use this document if you comply with the terms of the license. See: http://www.openoffice.org/licenses/PDL.html
Contents
opyright.............................................................................................................................................................!
Preface...................................................................................................... 5
1 OpenOffice.org BASIC Programming Guide..................................................7 "bout #pen#ffice.org $asic...............................................................................................................................% &ntended 'sers of #pen#ffice.org $asic.............................................................................................................( 'se of #pen#ffice.org $asic...............................................................................................................................( )ore &nformation.................................................................................................................................................(
2 The Language of OpenOffice.org BASIC.......................................................9 #*er*iew of a $asic Program..............................................................................................................................+ ,or-ing ,ith .ariables.....................................................................................................................................// Strings................................................................................................................................................................/! 0umbers............................................................................................................................................................./1 $oolean .alues................................................................................................................................................../2 Date and Time..................................................................................................................................................../2 "rrays................................................................................................................................................................/% Scope and Life Span of .ariables......................................................................................................................!3 onstants............................................................................................................................................................!/ #perators............................................................................................................................................................!! $ranching...........................................................................................................................................................!1 Loops.................................................................................................................................................................!4 Procedures and 5unctions..................................................................................................................................!% 6rror 7andling...................................................................................................................................................13 #ther &nstructions..............................................................................................................................................1!
!un"ime Li#rar$....................................................................................... 5 on*ersion 5unctions........................................................................................................................................14 Strings................................................................................................................................................................1( Date and Time....................................................................................................................................................83 5iles and Directories..........................................................................................................................................8! )essage and &nput $o9es..................................................................................................................................8% #ther 5unctions.................................................................................................................................................8+
% In"roduc"ion "o "he API.............................................................................51 'ni*ersal 0etwor- #bjects :'0#;...................................................................................................................4/ Properties and )ethods.....................................................................................................................................4!
1
)odules< Ser*ices and &nterfaces......................................................................................................................41 Tools for ,or-ing with '0#............................................................................................................................41 #*er*iew of entral &nterfaces..........................................................................................................................48
5 &or'ing (i"h )ocumen"*..........................................................................59 The StarDes-top................................................................................................................................................4+ Styles and Templates..........................................................................................................................................22
+ Te," )ocumen"*.......................................................................................+9 The Structure of Te9t Documents......................................................................................................................2+ 6diting Te9t Documents....................................................................................................................................%4 )ore Than =ust Te9t..........................................................................................................................................(/
7 Spread*hee" )ocumen"*...........................................................................91 The Structure of Spreadsheets...........................................................................................................................+/ 6diting Spreadsheet Documents....................................................................................................................../3%
- )ra(ing* and Pre*en"a"ion*...................................................................111 The Structure of Drawings.............................................................................................................................../// 6diting Drawing #bjects................................................................................................................................./!4 Presentations..................................................................................................................................................../!(
9 Char"* .)iagram*/..................................................................................1 1 'sing harts in Spreadsheets........................................................................................................................../1/ The Structure of harts..................................................................................................................................../1! hart Types....................................................................................................................................................../83
10 )a"a#a*e*.............................................................................................. 1% S>L: a >uery Language................................................................................................................................../81 Types of Database "ccess................................................................................................................................/81 Data Sources..................................................................................................................................................../88 Database "ccess.............................................................................................................................................../82
11 )ia1og*.................................................................................................. 151 ,or-ing ,ith Dialogs...................................................................................................................................../4/ Properties........................................................................................................................................................./41 6*ents............................................................................................................................................................../42 Dialog ontrol 6lements................................................................................................................................./2/
12 2orm*.................................................................................................... 1+7 ,or-ing ,ith 5orms......................................................................................................................................./2% ontrol 6lement 5orms..................................................................................................................................../%3
Database 5orms.............................................................................................................................................../%2
Preface
This guide pro*ides an introduction to programming with #pen#ffice.org $asic. To get the most out of this boo-< you should be familiar with other programming languages. 69tensi*e e9amples are pro*ided to help you ?uic-ly de*elop your own #pen#ffice.org $asic programs. Note Throughout this document< the #pen#ffice.org installation directory is represented in synta9 as install-dir.
C H
P ! " #
OpenOffice.org BASIC Programming Guide
This guide pro*ides an introduction to programming with #pen#ffice.org $asic. To get the most out of this boo-< you should be familiar with other programming languages. 69tensi*e e9amples are pro*ided to help you ?uic-ly de*elop your own #pen#ffice.org $asic programs. This guide di*ides information about #pen#ffice.org administration into se*eral chapters. The first three chapters introduce you to #pen#ffice.org $asic:

The Language of #pen#ffice.org $asic @untime Library &ntroduction to the "P&
These chapters pro*ide an o*er*iew of #pen#ffice.org $asic and should be read by anyone who intends to write #pen#ffice.org $asic programs. The remaining chapters describe the indi*idual components of the #pen#ffice.org "P& in more detail and can be read selecti*ely as re?uired:

,or-ing with Documents Te9t Documents Spreadsheet Documents Drawings and Presentations harts :Diagrams; Databases Dialogs 5orms
bout Ope%Office.org Basic

The #pen#ffice.org $asic programming language has been de*eloped especially for #pen#ffice.org and is firmly integrated in the #ffice pac-age. "s the name suggests< #pen#ffice.org $asic is a programming language from the $asic family. "nyone who has pre*iously wor-ed with other $asic languages A in particular with .isual $asic or .isual $asic for "pplications :.$"; from )icrosoft A will ?uic-ly become accustomed to #pen#ffice.org $asic. Large sections of the basic constructs of #pen#ffice.org $asic are compatible with .isual $asic. The #pen#ffice.org $asic programming language can be di*ided into four components: The language of #pen#ffice.org $asic: Defines the elementary linguistic constructs< for e9ample< for *ariable declarations< loops< and functions. The runtime library: Pro*ides standard functions which ha*e no direct reference to #pen#ffice.org< for e9ample< functions for editing numbers< strings< date *alues< and files. The #pen#ffice.org "P& :"pplication Programming &nterface;: Permits access to #pen#ffice.org
About OpenOffice.org Basic
documents and allows these to be created< sa*ed< modified< and printed. The Dialog 6ditor: reates personal dialog windows and pro*ides scope for the adding of control elements and e*ent handlers.
Note VBA : ompatibility between #pen#ffice.org $asic and .$" relates to the #pen#ffice.org $asic language as well as the runtime library. The #pen#ffice.org "P& and the Dialog 6ditor are not compatible with .$" :standardiBing these interfaces would ha*e made many of the concepts pro*ided in #pen#ffice.org impossible;.
&%te%ded 'sers of Ope%Office.org Basic

The scope of application for #pen#ffice.org $asic begins where the standard functions of #pen#ffice.org end. @outine tas-s can therefore be automated in #pen#ffice.org $asic< lin-s can be made to other programs A for e9ample to a database ser*er A and comple9 acti*ities can be performed at the press of a button by using predefined scripts. #pen#ffice.org $asic offers complete access to all #pen#ffice.org functions< supports all functions< modifies document types< and pro*ides options for creating personal dialog windows.
'se of Ope%Office.org Basic

#pen#ffice.org $asic can be used by any #pen#ffice.org user without any additional programs or aids. 6*en in the standard installation< #pen#ffice.org $asic has all the components needed to create its own $asic macros< including: The integrated de*elopment en*ironment :&D6; which pro*ides an editor for creating and testing macros. The interpreter< which is needed to run #pen#ffice.org $asic macros. The interfaces to *arious #pen#ffice.org applications< which allow for direct access to #ffice documents.
(ore &%formatio%
The components of the #pen#ffice.org "P& that are discussed in this guide were selected based on their practical benefits for the #pen#ffice.org $asic programmer. &n general< only parts of the interfaces are discussed. 5or a more detailed picture< see the "P& reference. The De*eloperCs Duide describes the #pen#ffice.org "P& in more detail than this guide< but is primarily intended for =a*a and EE programmers. "nyone who is already familiar with #pen#ffice.org $asic programming can find additional information in the De*eloperCs Duide on #pen#ffice.org $asic and #pen#ffice.org programming. Programmers who want to wor- directly with =a*a or EE rather than #pen#ffice.org $asic should consult the #pen#ffice.org De*eloperCs Duide instead of this guide. #pen#ffice.org programming with =a*a or E E is a considerably more comple9 process than programming with #pen#ffice.org $asic.
10
LibreOffice 3.4 Basic Programmer's Guide !eptember "011
C H
P ! " #
The Language of OpenOffice.org BASIC
#pen#ffice.org $asic belongs to the family of $asic languages. )any parts of #pen#ffice.org $asic are identical to )icrosoft .isual $asic for "pplications and )icrosoft .isual $asic. "nyone who has already wor-ed with these languages can ?uic-ly become accustomed to #pen#ffice.org $asic. Programmers of other languages F such as =a*a< EE< or Delphi F should also find it easy to familiariBe themsel*es with #pen#ffice.org $asic. #pen#ffice.org $asic is a fullyGde*eloped procedural programming language and no longer re?uires rudimentary control structures< such as GoTo and GoSub. You can also benefit from the ad*antages of objectGoriented programming since an interface in #pen#ffice.org $asic enables you to use e9ternal object libraries. The entire #pen#ffice.org "P& is based on these interfaces< which are described in more detail in the following chapters of this document. This chapter pro*ides an o*er*iew of the -ey elements and constructs of the #pen#ffice.org $asic language< as well as the framewor- in which applications and libraries are oriented to #pen#ffice.org $asic.
O*er*ie+ of a Basic Program

#pen#ffice.org $asic is an interpreter language. 'nli-e EE or Delphi< the #pen#ffice.org $asic compiler does not create e9ecutable or selfGe9tracting files that are capable of running automatically. &nstead< you e9ecute an #pen#ffice.org $asic program inside #pen#ffice.org. The code is first chec-ed for ob*ious errors and then e9ecuted line by line.
Program Li%es
The $asic interpreterCs lineGoriented e9ecution produces one of the -ey differences between $asic and other programming languages. ,hereas the position of hard line brea-s in the source code of =a*a< EE< or Delphi programs is irrele*ant< each line in a $asic program forms a selfGcontained unit. 5unction calls< mathematical e9pressions< and other linguistic elements< such as function and loop headers< must be completed on the same line that they begin on. &f there is not enough space< or if this results in long lines< then se*eral lines can be lin-ed together by adding underscores H. The following e9ample shows how four lines of a mathematical e9pression can be lin-ed:
LongExpression = (Expression1 * Expression2) + _(Expression3 * Expression4) + _ (Expression5 * Expression6) + _(Expression7 * Expression8)
11
O#er#ie$ of a Basic Program
Note The underscore must always be the last character in a lin-ed line and cannot be followed by a space or a tab or a comment< otherwise the code generates an error. &n addition to lin-ing indi*idual lines< in #pen#ffice.org $asic you can use colons to di*ide one line into se*eral sections< so that there is enough space for se*eral e9pressions. The assignments
= 1 = + 1 = + 1
can be written as follows:

= 1 ! = + 1 ! = + 1
Comme%ts
&n addition to the program code to be e9ecuted< an #pen#ffice.org $asic program can also contain comments that e9plain the indi*idual parts of the program and pro*ide important information that can be helpful at a later point. #pen#ffice.org $asic pro*ides two methods for inserting comments in the program code:

"ll characters that follow an apostrophe are treated as comments:

% T&is is 'o##en( )or * ri b+e $
"i# $
The -eyword ,e#< followed by the comment:
,e# T&is 'o##en( is in(ro-u'e- b. (&e /e.0or- ,e#1
" comment usually includes all characters up to the end of the line. #pen#ffice.org $asic then interprets the following line as a regular instruction again. &f comments co*er se*eral lines< each line must be identified as a comment:
"i# 2 % T&is 'o##en( )or * ri b+e 2 is re+ (i*e+. +ong % n- s(re('&es o*er se*er + +ines1 T&e % 'o##en( '& r '(er #us( (&ere)ore be repe (e% in e '& +ine1
(ar,ers
" #pen#ffice.org $asic program can contain doBens< hundreds< or e*en thousands of markers< which are names for *ariables< constants< functions< and so on. ,hen you select a name for a mar-er< the following rules apply:

)ar-ers can only contain Latin letters< numbers< and underscores :H;. The first character of a mar-er must be a letter or an underscore. )ar-ers cannot contain special characters< such as I J K L. The ma9imum length of a mar-er is !44 characters. 0o distinction is made between uppercase and lowercase characters. The 3neTes(4 ri b+e mar-er< for e9ample< defines the same *ariable as one(es(4 ri b+e and 35ETEST4$,6$2LE. There is< howe*er< one e9ception to this rule: a distinction is made between uppercase and lowercase characters for '0#G"P& constants. )ore information about '0# is presented in &ntroduction to the #pen#ffice.org "P&.
Note VBA : The rules for constructing mar-ers are different in #pen#ffice.org $asic than in .$". 5or e9ample< #pen#ffice.org $asic only allows special characters in mar-ers when using 3p(ion 7o#p (ib+e< since they can cause problems in international projects. 7ere are a few e9amples of correct and incorrect mar-ers:
Surn #e Surn #e5 8irs( 5 #e "9:;4u 5Surn #es 8irs(<5 #e % % % % % % 7orre'( 7orre'( (nu#ber 5 is no( (&e )irs( -igi() 6n'orre'( (sp 'es re no( per#i((e-) 6n'orre'( (+e((ers su'& s 9< ; re no( per#i((e-) 6n'orre'( ((&e )irs( '& r '(er #us( no( be nu#ber) 6n'orre'( ('o## s n- )u++ s(ops re no( per#i((e-)
1"
O#er#ie$ of a Basic Program
6nclosing a *ariable name in s?uare brac-ets allows names that might otherwise be disallowedM for e9ample< spaces.
"i# =8irs( 5 #e> $s S(ring "i# ="9:;4u> $s 6n(eger =8irs( 5 #e> = @$n-re0@ ="9:;4u> = 2 %Sp 'e ''ep(e- in s?u re br '/e(s %Spe'i + '& r '(ers in s?u re br '/e(s
-or,i%g -ith .ariab/es

&mp/icit .ariab/e 0ec/aratio%
$asic languages are designed to be easy to use. "s a result< #pen#ffice.org $asic enables the creation of a *ariable through simple usage and without an e9plicit declaration. &n other words< a *ariable e9ists from the moment that you include it in your code. Depending on the *ariables that are already present< the following e9ample declares up to three new *ariables:
= b + '
Declaring *ariables implicitly is not good programming practice because it can result in the inad*ertent introduction of a new *ariable through< for e9ample< a typing error. &nstead of producing an error message< the interpreter initialiBes the typing error as a new *ariable with a *alue of 3. &t can be *ery difficult to locate errors of this -ind in your code.
"1p/icit .ariab/e 0ec/aratio%

To pre*ent errors caused by an implicit declaration of *ariables< #pen#ffice.org $asic pro*ides a switch called:
3p(ion Exp+i'i(
This must be listed in the first program line of each module and ensures that an error message is issued if one of the *ariables used is not declared. The 3p(ion Exp+i'i( switch should be included in all $asic modules. &n its simplest form< the command for an e9plicit declaration of a *ariable is as follows:
"i# A.4 r
This e9ample declares a *ariable with the name A.4 r and the type * ri n(. " *ariant is a uni*ersal *ariable that can record all concei*able *alues< including strings< whole numbers< floating point figures< and $oolean *alues. 7ere are a few e9amples of .ariant *ariables:
A.4 A.4 A.4 A.4 r r r r = = = = @Be++o Cor+-@ 1 11D True % % % % $ssign#en( $ssign#en( $ssign#en( $ssign#en( o) o) o) o) s(ring 0&o+e nu#ber )+o (ing poin( nu#ber 2oo+e n * +ue
The *ariables declared in the pre*ious e9ample can e*en be used for different *ariable types in the same program. "lthough this pro*ides considerable fle9ibility< it is best to restrict a *ariable to one *ariable type. ,hen #pen#ffice.org $asic encounters an incorrectly defined *ariable type in a particular conte9t< an error message is generated. 'se the following style when you ma-e a typeGbound *ariable declaration:
"i# A.4 r $s 6n(eger % "e'+ r (ion o) * ri b+e o) (&e in(eger (.pe
The *ariable is declared as an integer type and can record whole number *alues. You can also use the following style to declare an integer type *ariable:
"i# A.4 rE % "e'+ r (ion o) * ri b+e o) (&e in(eger (.pe
%&apter " '&e Language of OpenOffice.org BA!(%
13
)or*ing )it& +ariab,es
The Dim instruction can record se*eral *ariable declarations:

"i# A.4 r1< A.4 r2
&f you want to assign the *ariables to a permanent type< you must ma-e separate assignments for each *ariable:
"i# A.4 r1 $s 6n(eger< A.4 r2 $s 6n(eger
&f you do not declare the type for a *ariable< #pen#ffice.org $asic assigns the *ariable a *ariant type. 5or e9ample< in the following *ariable declaration< A.4 r1 becomes a *ariant and A.4 r2 becomes an integer:
"i# A.4 r1< A.4 r2 $s 6n(eger
The following sections list the *ariable types that are a*ailable in #pen#ffice.org $asic and describe how they can be used and declared.
2tri%gs
Strings< together with numbers< form the most important basic types of #pen#ffice.org $asic. " string consists of a se?uence of consecuti*e indi*idual characters. The computer sa*es the strings internally as a se?uence of numbers where each number represents one specific character.
3rom a 2et of 2C&& Characters to '%icode

haracter sets match characters in a string with a corresponding code :numbers and characters; in a table that describes how the computer is to display the string.
!he 2C&& Character 2et

The "S && character set is a set of codes that represent numbers< characters< and special symbols by one byte. The 3 to /!% "S && codes correspond to the alphabet and to common symbols :such as periods< parentheses< and commas;< as well as some special screen and printer control codes. The "S && character set is commonly used as a standard format for transferring te9t data between computers. 7owe*er< this character set does not include a range of special characters used in 6urope< such as J< I< and K< as well as other character formats< such as the yrillic alphabet.
!he N2& Character 2et

)icrosoft based its ,indows product on the "merican 0ational Standards &nstitute :"0S&; character set< which was gradually e9tended to include characters that are missing from the "S && character set.
Code Pages
The &S# ((4+ character sets pro*ide an international standard. The first /!( characters of the &S# character set correspond to the "S && character set. The &S# standard introduces new character sets : code pages; so that more languages can be correctly displayed. 7owe*er< as a result< the same character *alue can represent different characters in different languages.
14
!trings
'%icode
'nicode increases the length of a character to four bytes and combines different character sets to create a standard to depict as many of the worldCs languages as possible. .ersion !.3 of 'nicode is now supported by many programs A including #pen#ffice.org and #pen#ffice.org $asic.
2tri%g .ariab/es
#pen#ffice.org $asic sa*es strings as string *ariables in 'nicode. " string *ariable can store up to 24414 characters. &nternally< #pen#ffice.org $asic sa*es the associated 'nicode *alue for e*ery character. The wor-ing memory needed for a string *ariable depends on the length of the string. 69ample declaration of a string *ariable:
"i# 4 ri b+e $s S(ring
You can also write this declaration as:

"i# 4 ri b+eF
Note VBA : ,hen porting .$" applications< ensure that the ma9imum allowed string length in #pen#ffice.org $asic is obser*ed :24414 characters;.
2pecificatio% of "1p/icit 2tri%gs

To assign an e9plicit string to a string *ariable< enclose the string in ?uotation mar-s :N;.
"i# A.S(ring $s S(ring A.S(ring = @ T&is is (es(@
To split a string across two lines of code< add an ampersand sign :the concatenation operator; and the underscore continuation character at the end of the first line:
"i# A.S(ring $s S(ring A.S(ring = @T&is s(ring is so +ong (& ( i( @ G _ @& s been sp+i( o*er (0o +ines1@
To include a ?uotation mar- :N; in a string< enter it twice at the rele*ant point:
"i# A.S(ring $s S(ring A.S(ring = @ @@H?uo( (ion # r/1@ % pro-u'es @H?uo( (ion # r/
Numbers
#pen#ffice.org $asic supports fi*e basic types for processing numbers:

&nteger Long &nteger Single Double urrency
1-
.umbers
&%teger .ariab/es
&nteger *ariables can store any whole number between -32768 and 32767. "n integer *ariable can ta-e up to two bytes of memory. The type declaration symbol for an integer *ariable is E. alculations that use integer *ariables are *ery fast and are particularly useful for loop counters. &f you assign a floating point number to an integer *ariable< the number is rounded up or down to the ne9t whole number. 69ample declarations for integer *ariables:
"i# 4 ri b+e $s 6n(eger "i# 4 ri b+eE
Lo%g &%teger .ariab/es

Long integer *ariables can store any whole number between 2147483648 and 2147483647. " long integer *ariable can ta-es up to four bytes of memory. The type declaration symbol for a long integer is G. alculations with long integer *ariables are *ery fast and are particularly useful for loop counters. &f you assign a floating point number to a long integer *ariable< the number is rounded up or down to the ne9t whole number. 69ample declarations for long integer *ariables:
"i# 4 ri b+e s Long "i# 4 ri b+eG
2i%g/e .ariab/es
Single *ariables can store any positi*e or negati*e floating point number between 3.402823 x 1038 and 1.401298 x 10-45. " single *ariable can ta-e up to four bytes of memory. The type declaration symbol for a single *ariable is I. #riginally< single *ariables were used to reduce the computing time re?uired for the more precise double *ariables. 7owe*er< these speed considerations no longer apply< reducing the need for single *ariables. 69ample declarations for single *ariables:
"i# 4 ri b+e s Sing+e "i# 4 ri b+eI
0oub/e .ariab/es
Double *ariables can store any positi*e or negati*e floating point numbers between 1.79769313486232 x 10308 and 4.94065645841247 x 10-324. " double *ariable can ta-e up to eight bytes of memory. Double *ariables are suitable for precise calculations. The type declaration symbol is J. 69ample declarations of double *ariables:
"i# 4 ri b+e $s "oub+e "i# 4 ri b+eJ
Curre%cy .ariab/es
urrency *ariables differ from the other *ariable types by the way they handle *alues. The decimal point is fi9ed and is followed by four decimal places. The *ariable can contain up to /4 numbers before the decimal point. " currency *ariable can store any *alue between -922337203685477.5808 and +922337203685477.5807 and ta-es up to eight bytes of memory. The type declaration symbol for a currency *ariable is K.
1/
.umbers
urrency *ariables are mostly intended for business calculations that yield unforeseeable rounding errors due to the use of floating point numbers. 69ample declarations of currency *ariables:
"i# 4 ri b+e $s 7urren'. "i# 4 ri b+eK
-ar%i%g The handling of $asic urrency type is not reliable. &ssue 1/33/ &ssue 4838+ &ssue +//!/ &ssue /3%!%% are still not corrected on #pen#ffice.org *ersion 1././.
3/oats
The types single< double and currency are often collecti*ely referred to as floats< or floatingGpoint number types. They can contain numerical *alues with decimal fractions of *arious length< hence the name: The decimal point seems to be able to CfloatC through the number. You can declare *ariables of the type float. The actual *ariable type :single< long< currency; is determined the moment a *alue is assigned to the *ariable:
"i# $ $s 8+o ( $ = 121D1126
2pecificatio% of "1p/icit Numbers

0umbers can be presented in se*eral ways< for e9ample< in decimal format or in scientific notation< or e*en with a different base than the decimal system. The following rules apply to numerical characters in #pen#ffice.org $asic:
-ho/e Numbers
The simplest method is to wor- with whole numbers. They are listed in the source te9t without a comma separating the thousand figure:
"i# $ $s 6n(eger "i# 2 $s 8+o ( $ = 121D 2 = 2438
The numbers can be preceded by both a plus :E; or minus :G; sign :with or without a space in between;:
"i# $ $s 6n(eger "i# 2 $s 8+o ( $ = + 121 2 = H 243
0ecima/ Numbers
,hen you type a decimal number< use a period :.; as the decimal point. This rule ensures that source te9ts can be transferred from one country to another without con*ersion.
"i# $ $s 6n(eger "i# 2 $s 6n(eger "i# 7 $s 8+o ( $ = 1223153 % is roun-e2 = H 23446146 % is roun-e7 = + 3532176323
You can also use plus :E; or minus :G; signs as prefi9es for decimal numbers :again with or without spaces;.
17
.umbers
&f a decimal number is assigned to an integer *ariable< #pen#ffice.org $asic rounds the figure up or down.
"1po%e%tia/ -riti%g 2ty/e

#pen#ffice.org $asic allows numbers to be specified in the e9ponential writing style< for e9ample< you can write 115eH1D for the number /.4 9 /3-10 :3.333333333/4;. The letter NeN can be lowercase or uppercase with or without a plus sign :E; as a prefi9. 7ere are a few correct and incorrect e9amples of numbers in e9ponential format:
"i# $ $s "oub+e $ $ $ $ $ $ $ = = = = = = = 1143E2 + 1143E2 H 1143E2 1143EH2 1143E H2 1<43EH2 1143E212 % % % % % % % 7orre'( 7orre'( (sp 'e be(0een p+us n- b si' nu#ber) 7orre'( (sp 'e be(0een #inus n- b si' nu#ber) 7orre'( (neg (i*e exponen() 6n'orre'( (sp 'es no( per#i((e- 0i(&in (&e nu#ber) 6n'orre'( ('o## s no( per#i((e- s -e'i# + poin(s) 6n'orre'( (exponen( #us( be 0&o+e nu#ber)
0ote< that in the first and third incorrect e9amples that no error message is generated e*en though the *ariables return incorrect *alues. The e9pression
$ = 1143E H2
is interpreted as /.81 minus !< which corresponds to the *alue G3.4%. 7owe*er< the *alue /.81 9 /3-2 :corresponding to 3.3/81; was the intended *alue. ,ith the *alue
$ = 1143E212
#pen#ffice.org $asic ignores the part of the e9ponent after the decimal point and interprets the e9pression as
$ = 1143E2
He1adecima/ .a/ues
&n the he9adecimal system :base /2 system;< a !Gdigit number corresponds to precisely one byte. This allows numbers to be handled in a manner which more closely reflects machine architecture. &n the he9adecimal system< the numbers 3 to + and the letters " to 5 are used as numbers. "n " stands for the decimal number /3< while the letter 5 represents the decimal number /4. #pen#ffice.org $asic lets you use whole numbered he9adecimal *alues< so long as they are preceded by GB.
"i# $ $s Long $ = GB88 % Bex -e'i# + * +ue 88< 'orrespon-s (o (&e -e'i# + * +ue 255 $ = GB1D % Bex -e'i# + * +ue 1D< 'orrespon-s (o (&e -e'i# + * +ue 16
Octa/ .a/ues
#pen#ffice.org $asic also understands the octal system :base ( system;< which uses the numbers 3 to %. You must use whole numbers that are preceded by G3.
"i# $ $s Long $ = G377 % 3'( + * +ue 77< 'orrespon-s (o (&e -e'i# + * +ue 63 $ = G31D % 3'( + * +ue 1D< 'orrespon-s (o (&e -e'i# + * +ue 8
10
Boo,ean +a,ues
Boo/ea% .a/ues
$oolean *ariables can only contain one of two *alues: True or 8 +se. They are suitable for binary specifications that can only adopt one of two statuses. " $oolean *alue is sa*ed internally as a twoGbyte integer *alue< where 3 corresponds to the 5alse and any other *alue to True. There is no type declaration symbol for $oolean *ariables. The declaration can only be made using the supplement $s 2oo+e n. 69ample declaration of a $oolean *ariable:
"i# 4 ri b+e $s 2oo+e n
0ate a%d !ime

Date *ariables can contain date and time *alues. ,hen sa*ing date *alues< #pen#ffice.org $asic uses an internal format that permits comparisons and mathematical operations on date and time *alues. There is no type declaration symbol for date *ariables. The declaration can only be made using the supplement $s " (e. 69ample declaration of a date *ariable:
"i# 4 ri b+e $s " (e
rrays
&n addition to simple *ariables :scalars;< #pen#ffice.org $asic also supports arrays :data fields;. " data field contains se*eral *ariables< which are addressed through an inde9.
0efi%i%g rrays
"rrays can be defined as follows:
2imp/e rrays
"n array declaration is similar to that of a simple *ariable declaration. 7owe*er< unli-e the *ariable declaration< the array name is followed by parentheses which contain the specifications for the number of elements. The e9pression Dim )y"rray:1; declares an array that has four *ariables of the *ariant data type< namely A.$rr .(D)< A.$rr .(1)< A.$rr .(2)< and A.$rr .(3). You can also declare typeGspecific *ariables in an array. 5or e9ample< the following line declares an array with four integer *ariables:
"i# A.6n(eger(3) $s 6n(eger
&n the pre*ious e9amples< the inde9 for the array always begins with the standard start *alue of Bero. "s an alternati*e< a *alidity range with start and end *alues can be specified for the data field declaration. The following e9ample declares a data field that has si9 integer *alues and which can be addressed using the inde9es 4 to /3:
"i# A.6n(eger(5 To 1D) $s 6n(eger
The inde9es do not need to be positi*e *alues. The following e9ample also shows a correct declaration< but with negati*e data field limits:
"i# A.6n(eger(H1D To H5) $s 6n(eger
19
Arra1s
&t declares an integer data field with 2 *alues that can be addressed using the inde9es G/3 to G4. There are no practical limits on the inde9es or on the number of elements in an array< so long as there is enough memory:
"i# s(H53DDD (o 8LDDD) $s S(ring s(H52DDD) = @ @ s(7LLLL) = @bb@ prin( s(H52DDD)< s(7LLLL)
Note VBA : #ther limit *alues sometimes apply for data field inde9es in .$". The same also applies to the ma9imum number of elements possible per dimension. The *alues *alid there can be found in the rele*ant .$" documentation.
2pecified .a/ue for 2tart &%de1

The start inde9 of a data field usually begins with the *alue 3. "lternati*ely< you can change the start inde9 for all data field declarations to the *alue / by using the call:
3p(ion 2 se 1
The call must be included in the header of a module if you want it to apply to all array declarations in the module. 7owe*er< this call does not affect the '0# se?uences that are defined through the #pen#ffice.org "P& whose inde9 always begins with 3. To impro*e clarity< you should a*oid using #ption $ase /. The number of elements in an array is not affected if you use 3p(ion 2 se 1< only the start inde9 changes. The declaration
3p(ion 2 se 1 % 111 "i# A.6n(eger(3)
creates 8 integer *ariables which can be described with the e9pressions A.6n(eger(1)< A.6n(eger(2)< A.6n(eger(3)< and A.6n(eger(4). Note VBA : &n #pen#ffice.org $asic< the e9pression 3p(ion 2 se 1 does not affect the number of elements in an array as it does in .$". &t is< rather< the start inde9 which mo*es in #pen#ffice.org $asic. ,hile the declaration A.6n(eger(3) creates three integer *alues in .$" with the inde9es / to 1< the same declaration in #pen#ffice.org $asic creates four integer *alues with the inde9es / to 8. $y using 3p(ion 7o#p (ib+e< #pen#ffice.org $asic beha*es li-e .$".
(u/ti40ime%sio%a/ 0ata 3ie/ds

&n addition to single dimensional data fields< #pen#ffice.org $asic also supports wor- with multiG dimensional data fields. The corresponding dimensions are separated from one another by commas. The e9ample Dim )y&nt"rray:4< 4; "s &nteger defines an integer array with two dimensions< each with 2 inde9es :can be addressed through the inde9es 3 to 4;. The entire array can record a total of 2 9 2 O 12 integer *alues. You can define hundreds of dimensions in #pen#ffice.org $asic "rraysM howe*er< the amount of a*ailable memory limits the number of dimensions you can ha*e.
0y%amic Cha%ges i% the 0ime%sio%s of 0ata 3ie/ds

The pre*ious e9amples are based on data fields of a specified dimension. You can also define arrays in which the dimension of the data fields dynamically changes. 5or e9ample< you can define an array to contain all of the words in a te9t that begin with the letter ". "s the number of these words is initially un-nown< you need to be able to subse?uently change the field limits. To do this in #pen#ffice.org $asic<
"0
Arra1s
use the following call:

,e"i# A.$rr .(1D)
Note VBA : 'nli-e .$"< where you can only dimension dynamic arrays by using "i# A.$rr .()< #pen#ffice.org $asic lets you change both static and dynamic arrays using ,e"i#. The following e9ample changes the dimension of the initial array so that it can record // or !/ *alues:
"i# A.$rr .(4) $s 6n(eger % "e'+ r (ion 0i(& )i*e e+e#en(s % 111 ,e"i# A.$rr .(1D) $s 6n(eger % 6n're se (o 11 e+e#en(s % 111 ,e"i# A.$rr .(2D) $s 6n(eger % 6n're se (o 21 e+e#en(s
,hen you reset the dimensions of an array< you can use any of the options outlined in the pre*ious sections. This includes declaring multiGdimensional data fields and specifying e9plicit start and end *alues. ,hen the dimensions of the data field are changed< all contents are lost. &f you want to -eep the original *alues< use the Mreser*e command:
"i# A.$rr .(1D) $s 6n(eger % "e)ining (&e ini(i + % -i#ensions % 111 ,e"i# Mreser*e A.$rr .(2D) $s 6n(eger % 6n're se in % - ( )ie+-< 0&i+e % re( ining 'on(en(
,hen you use Mreser*e< ensure that the number of dimensions and the type of *ariables remain the same. Note VBA : 'nli-e .$"< where only the upper limit of the last dimension of a data field can be changed through Mreser*e< #pen#ffice.org $asic lets you change other dimensions as well. &f you use ,e"i# with Mreser*e< you must use the same data type as specified in the original data field declaration.
0etermi%i%g the 0ime%sio%s of 0ata 3ie/ds

5unctions L$ound:; and '$ound:; return respecti*ely the lowest permitted inde9 *alue and the highest permitted inde9 *alue of an array. This is useful when an array has changed its dimensions.
"i# A.$rr .(1D) $s 6n(eger % 111 so#e ins(ru'(ions "i# n $s 6n(eger n = 47 % 'ou+- be (&e resu+( o) 'o#pu( (ion ,e-i# A.$rr .(n) $s 6n(eger Asg2ox(L2oun-(A.$rr .)) % -isp+ .s ! D Asg2ox(N2oun-(A.$rr .)) % -isp+ .s ! 47
5or a multiGdimensional array you need to specify the position :/ to n; of the inde9 you want to -now the permitted lower and upper *alues:
"i# A.$rr .(1D< 13 (o 28) $s 6n(eger Asg2ox(L2oun-(A.$rr .< 2)) % -isp+ .s ! 13 Asg2ox(N2oun-(A.$rr .< 2)) % -isp+ .s ! 28
"mpty arrays
&n some cases< especially when dealing with the "P&< you need to declare an empty array. Such array is declared without dimension< but may later be filled by an "P& function or with a @edim statement:
"i# s() $s S(ring % -e'+ re n e#p(. % HHH + (er in (&e progr # 111 ,e-i# s(13) $s S(ring rr .
You cannot assign a *alue to an empty array< since it does not contain any elements.
"1
Arra1s
The NsignatureN of an empty array is that '$ound:; returns G/ and L$ound:; returns 3:
"i# A.$rr .() $s 6n(eger Asg2ox(L2oun-(A.$rr .)) % -isp+ .s ! D Asg2ox(N2oun-(A.$rr .)) % -isp+ .s ! H1
Some "P& functions return an array containing elements :inde9ed from Bero; or return an empty array. 'se '$ound:; to chec- if the returned array is empty.
0efi%i%g *a/ues for arrays

.alues for the "rray fields can be stored li-e this:
A.$rr .(D) = @so#e* +ue@
ccessi%g rrays
"ccessing *alues in an array wor-s li-e this:
Asg2ox(@4 +ue!@ G A.$rr .(D))
rray Creatio%5 *a/ue assig%me%t a%d access e1amp/e

"nd e9ample containing all steps that show real array usage:
Sub Tes($rr .$xess G A.$rr .(D))En- Sub "i# A.$rr .(3) A.$rr .(D) = @+ + @ Asg2ox(@4 +ue!@
2cope a%d Life 2pa% of .ariab/es

" *ariable in #pen#ffice.org $asic has a limited life span and a limited scope from which it can be read and used in other program fragments. The amount of time that a *ariable is retained< as well as where it can be accessed from< depends on its specified location and type.
Loca/ .ariab/es
.ariables that are declared in a function or a procedure are called local *ariables:
Sub Tes( "i# A.6n(eger $s 6n(eger % 111 En- Sub
Local *ariables only remain *alid as long as the function or the procedure is e9ecuting< and then are reset to Bero. 6ach time the function is called< the *alues generated pre*iously are not a*ailable. To -eep the pre*ious *alues< you must define the *ariable as S( (i':
Sub Tes( S( (i' A.6n(eger $s 6n(eger % 111 En- Sub
Note VBA : 'nli-e .$"< #pen#ffice.org $asic ensures that the name of a local *ariable is not used simultaneously as a global and a pri*ate *ariable in the module header. ,hen you port a .$" application to #pen#ffice.org $asic< you must change any duplicate *ariable names.
""
!cope and Life !pan of +ariab,es
Pub/ic 0omai% .ariab/es

Public domain *ariables are defined in the header section of a module by the -eyword "i#. These *ariables are a*ailable to all of the modules in their library: )odule ":
"i# $ $s 6n(eger Sub Tes( 8+ip 8+op En- Sub Sub 8+ip $ = $ + 1 En- Sub
)odule $:
Sub 8+op $ = $ H 1 En- Sub
The *alue of *ariable $ is not changed by the Tes( function< but is increased by one in the 8+ip function and decreased by one in the 8+op function. $oth of these changes to the *ariable are global. You can also use the -eyword Mub+i' instead of "i# to declare a public domain *ariable:
Mub+i' $ $s 6n(eger
" public domain *ariable is only a*ailable so long as the associated macro is e9ecuting and then the *ariable is reset.
G/oba/ .ariab/es
&n terms of their function< global *ariables are similar to public domain *ariables< e9cept that their *alues are retained e*en after the associated macro has e9ecuted. Dlobal *ariables are declared in the header section of a module using the -eyword G+ob +:
G+ob + $ $s 6n(eger
Pri*ate .ariab/es
Mri* (e *ariables are only a*ailable in the module in which they are defined. 'se the -eyword Mri* (e to
define the *ariable:

Mri* (e A.6n(eger $s 6n(eger
&f se*eral modules contain a Mri* (e *ariable with the same name< #pen#ffice.org $asic creates a different *ariable for each occurrence of the name. &n the following e9ample< both module $ and 2 ha*e a Mri* (e *ariable called 7. The Tes( function first sets the Mri* (e *ariable in module $ and then the Mri* (e *ariable in module 2. )odule ":
Mri* (e 7 $s 6n(eger Sub Tes( Se(Ao-u+e$ Se(Ao-u+e2 S&o04 r$ S&o04 r2 En- Sub Sub Se(Ao-u+e$ 7 = 1D En- Sub % % % % Se(s (&e * ri b+e 7 )ro# #o-u+e $ Se(s (&e * ri b+e 7 )ro# #o-u+e 2 S&o0s (&e * ri b+e 7 )ro# #o-u+e $ (= 1D) S&o0s (&e * ri b+e 7 )ro# #o-u+e 2 (= 2D)
"3
!cope and Life !pan of +ariab,es
Sub S&o04 r$ Asg2ox 7 En- Sub
% S&o0s (&e * ri b+e 7 )ro# #o-u+e $1
)odule $:
Mri* (e 7 $s 6n(eger Sub Se(Ao-u+e2 7 = 2D En- Sub Sub S&o04 r2 Asg2ox 7 En- Sub % S&o0s (&e * ri b+e 7 )ro# #o-u+e 21
Peep in mind that Show.ar$ only shows the e9pected *alue of :!3; because Sub Test is -eeping it in scope. &f the calls to Set)odule$ and Show.ar$ are independent< e.g. Set)odule$ is triggered from one toolbar button and Show.ar$ is triggered from another toolbar button< then Show.ar$ will display a *alue of 3 since module *ariables are reset after each macro completion.
Co%sta%ts
onstants are *alues which may be used but not changed by the program.
0efi%i%g Co%sta%ts
&n #pen#ffice.org $asic< use the -eyword 7ons( to declare a constant.
7ons( $ = 1D
You can also specify the constant type in the declaration:

7ons( 2 $s "oub+e = 1D
2cope of Co%sta%ts
onstants ha*e the same scope as *ariables :see Scope and Life Span of .ariables;< but the synta9 is slightly different. " 7ons( definition in the module header is a*ailable to the code in that module. To ma-e the definition a*ailable to other modules< add the Mub+i' -eyword.
Mub+i' 7ons( one $s 6n(eger = 1
Predefi%ed Co%sta%ts
#pen#ffice.org $asic predefines se*eral constants. "mong the most useful are:

True and 8 +se< for $oolean assignment statements M6 as a type "oub+e numeric *alue
"i# bBi( s 2oo+e n bBi( = True "i# -$re s "oub+e< -, -ius s "oub+e % 111 ( ssign * +ue (o -, -ius) -$re = M6 * -, -ius * -, -ius
"4
Operators
Operators
#pen#ffice.org $asic understands common mathematical< logical< and comparison operators.
(athematica/ Operators
)athematical operators can be applied to all numbers types< whereas the E operator can also be used to concatenate strings.
+ G H * O P Q A3"
"ddition of numbers and date *alues< concatenation of strings oncatenation of strings Subtraction of numbers and date *alues )ultiplication of numbers Di*ision of numbers Di*ision of numbers with a whole number result :rounded; @aising the power of numbers modulo operation :calculation of the remainder of a di*ision;
Note "lthough you can use the E operator to concatenate strings< the $asic interpreter can become confused when concatenating a number to a string. The Q operator is safer when dealing with strings because it assumes that all arguments should be strings< and con*erts the arguments to strings if they are not strings.
Logica/ Operators
Logical operators allow you to do operations on elements according to the rules of $oolean algebra. &f the operators are applied to $oolean *alues< the operation pro*ides the result re?uired directly. &f used in conjunction with integer and long integer *alues< the operation is done at the bit le*el.
$5" 3, R3, 53T ES4 6AM
"nd operator #r operator 69clusi*e #r operator 0egation 6?ui*alent test :both parts True or 8 +se; &mplication :if the first e9pression is true< then the second must also be true;
Compariso% Operators
omparison operators can be applied to all elementary *ariable types :numbers< date details< strings< and $oolean *alues;.
=
6?uality of numbers< date *alues and strings
"-
Operators
TU U U= T T=
&ne?uality of numbers< date *alues and strings Dreater than chec- for numbers< date *alues and strings Dreater than or e?ual to chec- for numbers< date *alues and strings Less than chec- for numbers< date *alues and strings Less than or e?ual to chec- for numbers< date *alues and strings
Note VBA : #pen#ffice.org $asic does not support the .$" Li/e comparison operator.
Bra%chi%g
'se branching statements to restrict the e9ecution of a code bloc- until a particular condition is satisfied.
&f...!he%..."/se
The most common branching statement is the 6) statement as shown in the following e9ample:
6) $ U 3 T&en 2 = 2 En- 6)
The 2 = 2 assignment only occurs when *alue of *ariable $ is greater than three. " *ariation of the 6) statement is the 6)OE+se clause:
6) $ U 3 T&en 2 = 2 E+se 2 = D En- 6)
&n this e9ample< the *ariable 2 is assigned the *alue of ! when $ is greater than 1< otherwise 2 is assigned the *alue of 3. 5or more comple9 statements< you can cascade the 6) statement< for e9ample:
6) $ = D T&en 2 = D E+se6) $ T 3 T&en 2 = 1 E+se 2 = 2 En- 6)
&f the *alue of *ariable $ e?uals Bero< 2 is assigned the *alue 3. &f $ is less than 1 :but not e?ual to Bero;< then 2 is assigned the *alue /. &n all other instances :that is< if $ is greater than or e?ual to 1;< 2 is assigned the *alue !. " complete &f statement may be written on a single line< with a simpler synta9. The first e9ample of this page may be written as:
6) $ U 3 T&en 2 = 2
The second e9ample of this page may be written as:

6) $ U 3 T&en 2 = 2 E+se 2 = D
"/
Branc&ing
2e/ect...Case
The Se+e'(1117 se instruction is an alternati*e to the cascaded 6) statement and is used when you need to chec- a *alue against *arious conditions:
Se+e'( 7 se " .3)Cee/ 7 se 1! 5 #e3)Cee/- . = @Sun- .@ 7 se 2! 5 #e3)Cee/- . = @Aon- .@ 7 se 3! 5 #e3)Cee/- . = @Tues- .@ 7 se 4! 5 #e3)Cee/- . = @Ce-nes- .@ 7 se 5! 5 #e3)Cee/- . = @T&urs- .@ 7 se 6! 5 #e3)Cee/- . = @8ri- .@ 7 se 7! 5 #e3)Cee/- . = @S (ur- .@ En- Se+e'(
&n this e9ample< the name of a wee-day corresponds to a number< so that the " .3)Cee/ *ariable is assigned the *alue of / for Sun- .< ! for Aon- . *alue< and so on. The Se+e'( command is not restricted to simple /:/ assignments A you can also specify comparison operators or lists of e9pressions in a 7 se branch. The following e9ample lists the most important synta9 *ariants:
Se+e'( 7 se 4 r 7 se 1 To 5 % 111 4 r is be(0een (&e nu#bers 1 n- 5 (in'+u-ing (&e * +ues 1 7 se U 1DD % 111 4 r is gre (er (& n 1DD 7 se 6< 7< 8 % 111 4 r is 6< 7 or 8 7 se 6< 7< 8< U 15< T D % 111 4 r is 6< 7< 8< gre (er (& n 15< or +ess (& n D 7 se E+se % 111 ++ o(&er ins( n'es En- Se+e'( n- 5)1
0ow consider a misleading :ad*anced; e9ample< and a common error:

Se+e'( 7 se 4 r 7 se 4 r = 8 % 111 4 r is D 7 se E+se % 111 ++ o(&er ins( n'es En- Se+e'(
The statement :.ar O (; e*aluates to T@'6 if .ar is (< and 5"LS6 otherwise. T@'6 is G/ and 5"LS6 is 3. The Select ase statement e*aluates the e9pression< which is T@'6 or 5"LS6< and then compares that *alue to .ar. ,hen .ar is 3< there is a match. &f you understand the last e9ample< then you also -now why this e9ample does not do what it appears
Se+e'( 7 se 4 r 7 se 4 r U 8 $n- 4 r T 11 % 111 4 r is D 7 se E+se % 111 ++ o(&er ins( n'es En- Se+e'(
Loops
" loop e9ecutes a code bloc- for the number of passes that are specified. You can also ha*e loops with an undefined number of passes.
"7
Loops
3or...Ne1t
The 8or1115ex( loop has a fi9ed number of passes. The loop counter defines the number of times that the loop is to be e9ecuted. &n the following e9ample< *ariable 6 is the loop counter< with an initial *alue of /. The counter is incremented by / at the end of each pass. ,hen *ariable & e?uals /3< the loop stops.
"i# 6 8or 6 = 1 To 1D % 111 6nner p r( o) +oop 5ex( 6
&f you want to increment the loop counter by a *alue other than / at the end of each pass< use the S(ep function:
"i# 6 8or 6 = 1 To 1D S(ep D15 % 111 6nner p r( o) +oop 5ex( 6
&n the preceding e9ample< the counter is increased by 3.4 at the end of each pass and the loop is e9ecuted /+ times. You can also use negati*e step *alues:
"i# 6 8or 6 = 1D To 1 S(ep H1 % 111 6nner p r( o) +oop 5ex( 6
&n this e9ample< the counter begins at /3 and is reduced by / at the end of each pass until the counter is /. The Exi( 8or instruction allows you to e9it a 8or loop prematurely. &n the following e9ample< the loop is terminated during the fifth pass:
"i# 6 8or 6 = 1 To 1D 6) 6 = 5 T&en Exi( 8or En- 6) % 111 6nner p r( o) +oop 5ex( 6
3or "ach
The 8or E '&1115ex( loop *ariation in .$" is supported in #pen#ffice.org $asic. 8or E '& loops do not use an e9plicit counter li-e a 8or1115ex( loop does. " 8or E '& loop says Ndo this to e*erything in this setN< rather than Ndo this n timesN. 5or e9ample:
7ons( -1 = 2 7ons( -2 = 3 7ons( -3 = 2 "i# i "i# (-1< -2< -3) 8or E '& i 6n () % 111 6nner p r( o) +oop 5ex( i
The loop will e9ecute 12 times.
0o...Loop
The "o111Loop is not lin-ed to a fi9ed number of passes. &nstead< the "o111Loop is e9ecuted until a certain condition is met. There are four *ersions of the "o111Loop. &n the first two e9amples< the code within the loop may not be e9ecuted at all :Ndo 3 timesN logic;. &n the latter e9amples< the code will be e9ecuted at least once. :&n the following e9amples< $ U 1D represents any condition;: $
"0
!he Do While...Loop *ersio%

Loops
"o C&i+e $ U 1D % 111 +oop bo-. Loop
chec-s whether the condition after the C&i+e is r!e before e*ery pass and only then e9ecutes the loop. ) !he Do Until...Loop *ersio%
"o Nn(i+ $ U 1D % 111 +oop bo-. Loop
e9ecutes the loop as long as the condition after the Nn(i+ e*aluates to "a#se. 3 !he Do...Loop While *ersio%
"o % 111 +oop bo-. Loop C&i+e $ U 1D
only chec-s the condition after the first loop pass and terminates if the condition after the C&i+e e*aluates to "a#se. 4 !he Do...Loop Until *ersio%
"o % 111 +oop bo-. Loop Nn(i+ $ U 1D
also chec-s its condition after the first pass< but terminates if the condition after the Nn(i+ e*aluates to r!e. "s in the 8or1115ex( loop< the "o111Loop also pro*ides a terminate command. The Exi( "o command can e9it at loop at any point within the loop.
"o 6) $ = 4 T&en Exi( "o En- 6) % 111 +oop bo-. Loop C&i+e $ U 1D
&n some cases the loop may only terminate when a condition is met within the loop. Then you can use the NperpetualN Do Loop:
"o % 111 so#e in(ern + ' +'u+ (ions 6) $ = 4 T&en Exi( "o % 111 o(&er ins(ru'(ions Loop
-hi/e...-e%d
The C&i+e111Cen- loop construct wor-s e9actly the same as the "o C&i+e111Loop< but with the disad*antage that there is no Exi( command a*ailable. The following two loops produce identical results:
"o C&i+e $ U 1D % 111 +oop bo-. Loop C&i+e $ U 1D % 111 +oop bo-. Cen-
Programmi%g "1amp/e6 2orti%g -ith "mbedded Loops

There are many ways to use loops< for e9ample< to search lists< return *alues< or e9ecute comple9 mathematical tas-s. The following e9ample is an algorithm that uses two loops to sort a list by names.
Sub Sor( "i# En(r.(1 To 1D) $s S(ring "i# 7oun( $s 6n(eger
"9
Loops
"i# 7oun(2 $s 6n(eger "i# Te#p $s S(ring En(r.(1) = @M ((.@ En(r.(2) = @Vur(@ En(r.(3) = @T&o# s@ En(r.(4) = @Ai'& e+@ En(r.(5) = @" *i-@ En(r.(6) = @7 (&.@ En(r.(7) = @Susie@ En(r.(8) = @E-0 r-@ En(r.(L) = @7&ris(ine@ En(r.(1D) = @Werr.@ 8or 7oun( = 1 To L 8or 7oun(2 = 7oun( + 1 To 1D 6) En(r.(7oun() U En(r.(7oun(2) T&en Te#p = En(r.(7oun() En(r.(7oun() = En(r.(7oun(2) En(r.(7oun(2) = Te#p En- 6) 5ex( 7oun(2 5ex( 7oun( 8or 7oun( = 1 To 1D Mrin( En(r.(7oun() 5ex( 7oun( En- Sub
The *alues are interchanged as pairs se*eral times until they are finally sorted in ascending order. Li-e bubbles< the *ariables gradually migrate to the right position. 5or this reason< this algorithm is also -nown as a $ubble Sort.
Procedures a%d 3u%ctio%s

Procedures and functions form pi*otal points in the structure of a program. They pro*ide the framewor- for di*iding a comple9 problem into *arious subGtas-s.
Procedures
" proced!re e9ecutes an action without pro*iding an e9plicit *alue. &ts synta9 is
Sub Tes( % 111 &ere is (&e En- Sub '(u + 'o-e o) (&e pro'e-ure
The e9ample defines a procedure called Tes( that contains code that can be accessed from any point in the program. The call is made by entering the procedure name at the rele*ant point of the program.
3u%ctio%s
" "!$c %o$< just li-e a procedure< combines a bloc- of programs to be e9ecuted into one logical unit. 7owe*er< unli-e a procedure< a function pro*ides a return *alue.
8un'(ion Tes( % 111 &ere is (&e Tes( = 123 En- 8un'(ion '(u + 'o-e o) (&e )un'(ion
The return *alue is assigned using simple assignment. The assignment does not need to be placed at the end of the function< but can be made anywhere in the function. The preceding function can be called within a program as follows:
30
Procedures and 2unctions
"i# $ $ = Tes(
The code defines a *ariable $ and assigns the result of the Tes( function to it. The return *alue can be o*erwritten se*eral times within the function. "s with classic *ariable assignment< the function in this e9ample returns the *alue that was last assigned to it.
8un'(ion Tes( Tes( = 12 % 111 Tes( = 123 En- 8un'(ion
&n this e9ample< the return *alue of the function is /!1. &f nothing is assigned< the function returns a Xero *alue :number 3 for numerical *alues and a blan- for strings;. The return *alue of a function can be any type. The type is declared in the same way as a *ariable declaration:
8un'(ion Tes( $s 6n(eger % 111 &ere is (&e '(u + 'o-e o) (&e )un'(ion En- 8un'(ion
&f the return type is not specified :see first e9ample of this page;< the function returns a *ariant.
!ermi%ati%g Procedures a%d 3u%ctio%s Premature/y

&n #pen#ffice.org $asic< you can use the Exi( Sub and Exi( 8un'(ion commands to terminate a procedure or function prematurely< for e9ample< for error handling. These commands stop the procedure or function and return the program to the point at which the procedure or function was called up. The following e9ample shows a procedure which terminates implementation when the Error3''ure*ariable has the *alue True.
Sub Tes( "i# Error3''ure- $s 2oo+e n % 111 6) Error3''ure- T&en Exi( Sub En- 6) % 111 En- Sub
Passi%g Parameters
5unctions and procedures can recei*e one or more parameters. 6ssential parameters must be enclosed in parentheses after the function or procedure names. The following e9ample defines a procedure that e9pects an integer *alue $ and a string 2 as parameters.
Sub Tes( ($ $s 6n(eger< 2 $s S(ring) % 111 En- Sub
Parameters are normally passed by &e"ere$ce in #pen#ffice.org $asic. hanges made to the *ariables are retained when the procedure or function is e9ited:
Sub Tes( "i# $ $s 6n(eger $ = 1D 7& nge4 +ue($) % T&e p r #e(er $ no0 & s (&e * +ue 2D En- Sub Sub 7& nge4 +ue(T&e4 +ue $s 6n(eger) T&e4 +ue = 2D
31
En- Sub
&n this e9ample< the *alue $ that is defined in the Tes( function is passed as a parameter to the 7& nge4 +ue function. The *alue is then changed to !3 and passed to T&e4 +ue< which is retained when the function is e9ited. You can also pass a parameter as a 'a#!e if you do not want subse?uent changes to the parameter to affect the *alue that is originally passed. To specify that a parameter is to be passed as a *alue< ensure that the 2.4 + -eyword precedes the *ariable declaration in the function header. &n the preceding e9ample< if we replace the 7& nge4 +ue function then the superordinate *ariable " remains unaffected by this change. "fter the call for the 7& nge4 +ue function< *ariable $ retains the *alue /3.
Sub 7& nge4 +ue(2.4 + T&e4 +ue $s 6n(eger) T&e4 +ue = 2D En- Sub
Note VBA : The method for passing parameters to procedures and functions in #pen#ffice.org $asic is *irtually identical to that in .$". $y default< the parameters are passed by reference. To pass parameters as *alues< use the 2.4 + -eyword. &n .$"< you can also use the -eyword 2.,e) to force a parameter to be passed by reference. #pen#ffice.org $asic recogniBes but ignores this -eyword< because this is already the default procedure in #pen#ffice.org $asic.
Optio%a/ Parameters
5unctions and procedures can only be called up if all the necessary parameters are passed during the call. #pen#ffice.org $asic lets you define parameters as op %o$a#< that is< if the corresponding *alues are not included in a call< #pen#ffice.org $asic passes an empty parameter. &n the following e9ample the $ parameter is obligatory< whereas the 2 parameter is optional.
Sub Tes(($ $s 6n(eger< 3p(ion + 2 $s 6n(eger) % 111 En- Sub
The 6sAissing function chec-s whether a parameter has been passed or is left out.
Sub Tes(($ $s 6n(eger< 3p(ion + 2 $s 6n(eger) "i# 2_Lo' + $s 6n(eger % 7&e'/ 0&e(&er 2 p r #e(er is '(u ++. presen( 6) 5o( 6sAissing (2) T&en 2_Lo' + = 2 % 2 p r #e(er presen( E+se 2_Lo' + = D % 2 p r #e(er #issing HU -e) u+( * +ue D En- 6) % 111 S( r( (&e '(u + )un'(ion En- Sub
The e9ample first tests whether the 2 parameter has been passed and< if necessary< passes the same parameter to the internal 2_Lo' + *ariable. &f the corresponding parameter is not present< then a default *alue :in this instance< the *alue 3; is passed to 2_Lo' + rather than the passed parameter. Note VBA : The M r #$rr . -eyword present in .$" is not supported in #pen#ffice.org $asic.
#ecursio%
" recursi*e procedure or function is one that has the ability to call itself until it detects that some base condition has been satisfied. ,hen the function is called with the base condition< a result is returned. The following e9ample uses a recursi*e function to calculate the factorial of the numbers 42< H42< and 3114:
3"
Sub A in Asgbox 7 +'u+ (e8 '(ori +( 42 ) Asgbox 7 +'u+ (e8 '(ori +( H42 ) Asgbox 7 +'u+ (e8 '(ori +( 3114 ) En- Sub
% "isp+ .s 1<4D5DD611775288E+51 % "isp+ .s @6n* +i- nu#ber )or ) '(ori +I@ % "isp+ .s @6n* +i- nu#ber )or ) '(ori +I@
8un'(ion 7 +'u+ (e8 '(ori +( 5u#ber ) 6) 5u#ber T D 3r 5u#ber TU 6n(( 5u#ber ) T&en 7 +'u+ (e8 '(ori + = @6n* +i- nu#ber )or ) '(ori +I@ E+se6) 5u#ber = D T&en 7 +'u+ (e8 '(ori + = 1 E+se % T&is is (&e re'ursi*e ' ++! 7 +'u+ (e8 '(ori + = 5u#ber * 7 +'u+ (e8 '(ori +( 5u#ber H 1 ) En-i) En- 8un'(ion
The e9ample returns the factorial of the number 42 by recursi*ely calling the 7 +'u+ (e8 '(ori + function until it reaches the base condition of DI = 1. Note The recursion le*els are set at different le*els based on the software platform. 5or ,indows the recursion le*el is 4(33. 5or Solaris and Linu9< an e*aluation of the stac-siBe is performed and the recursion le*el is calculated.
"rror Ha%d/i%g
orrect handling of error situations is one of the most timeGconsuming tas-s of programming. #pen#ffice.org $asic pro*ides a range of tools for simplifying error handling.
!he O% "rror &%structio%

The 3n Error instruction is the -ey to any error handling:
Sub Tes( 3n Error Go(o ErrorB n-+er % 111 un-er( /e ( s/ -uring 0&i'& n error # . o''ur Exi( Sub ErrorB n-+er! % 111 in-i*i-u + 'o-e )or error & n-+ing En- Sub
The 3n Error Go(o ErrorB n-+er line defines how #pen#ffice.org $asic proceeds in the e*ent of an error. The Go(o ErrorB n-+er ensures that #pen#ffice.org $asic e9its the current program line and then e9ecutes the ErrorB n-+er! code.
!he #esume Comma%d

The ,esu#e 5ex( command continues the program from the line that follows where the error occurred in the program after the code in the error handler has been e9ecuted:
ErrorB n-+er! % 111 in-i*i-u + 'o-e )or error & n-+ing ,esu#e 5ex(
'se the ,esu#e Mro'ee- command to specify a jump point for continuing the program after error handling:
ErrorB n-+er! % 111 in-i*i-u + 'o-e )or error & n-+ing ,esu#e Mro'eeMro'ee-! % 111 (&e progr # 'on(inues &ere )(er (&e error
33
3rror 4and,ing
The term Proceed is a label. &t could be for e9ample< "!8%. The synta9 for label names is the same as for *ariable names. To continue a program without an error message when an error occurs< use the following format:
Sub Tes( 3n Error ,esu#e 5ex( % 111 per)or# ( s/ -uring 0&i'& En- Sub n error # . o''ur
'se the 3n Error ,esu#e 5ex( command with caution as its effect is global.
7ueries #egardi%g "rror &%formatio%

&n error handling< it is useful to ha*e a description of the error and to -now where and why the error occurred:

The Err *ariable contains the number of errors that has occurred. The ErrorF *ariable contains a description of the error. The Er+ *ariable contains the line number where the error occurred.
The call )sg$o9 N6rror N Q 6rr Q N: N Q 6rrorR Q N :line : N Q 6rl Q N;N shows how the error information can be displayed in a message window. Note VBA : ,hereas .$" summariBes the error messages in a statistical object called Err< #pen#ffice.org $asic pro*ides the Err< ErrorF< and Er+ *ariables. The status information remains *alid until the program encounters a ,esu#e or 3n Error command< whereupon the information is reset. Note VBA : &n .$"< the Err17+e r method of the Err object resets the error status after an error occurs. &n #pen#ffice.org $asic< this is accomplished with the 3n Error or ,esu#e commands.
!ips for 2tructured "rror Ha%d/i%g

$oth the definition command< 3n Error< and the return command< ,esu#e< are *ariants of the Go(o construct. &f you want to cleanly structure your code to pre*ent generating errors when you use this construct< you should not use jump commands without monitoring them. are should be ta-en when you use the 3n Error ,esu#e 5ex( command as this dismisses all open error messages. The best solution is to use only one approach for error handling within a program G -eep error handling separate from the actual program code and do not jump bac- to the original code after the error occurs. The following code is an e9ample of an error handling procedure:
Sub Ex #p+e % "e)ine error & n-+er ( (&e s( r( o) (&e )un'(ion 3n Error Go(o ErrorB n-+er % 111 Bere is (&e '(u + progr # 'o-e 3n Error Go(o D % "e '(i* (e error & n-+ing % En- o) regu+ r progr # i#p+e#en( (ion Exi( Sub % S( r( poin( o) error & n-+ing ErrorB n-+er! % 7&e'/ 0&e(&er error 0 s expe'(e6) Err = Expe'(e-Error5o T&en % 111 Mro'ess error
34
3rror 4and,ing
E+se % 111 C rning o) unexpe'(e- error En- 6) 3n Error Go(o D % "e '(i* (e error & n-+ing En- Sub
This procedure begins with the definition of an error handler< followed by the actual program code. "t the end of the program code< the error handling is deacti*ated by the 3n Error Go(o D call and the procedure implementation is ended by the Exi( Sub command :not to be confused with En- Sub;. The e9ample first chec-s if the error number corresponds to the e9pected number :as stored in the imaginary Expe'(e-Error5o constant; and then handles the error accordingly. &f another error occurs< the system outputs a warning. &t is important to chec- the error number so that unanticipated errors can be detected. The 3n Error Go(o D call at the end of the code resets the status information of the error :the error code in the Err system *ariables; so that an error occurring at a later date can be clearly recogniBed.
Other &%structio%s
!ype..."%d !ype
" struct is a collection of data fields< that can be manipulated as a single item. &n older terms< you may thinof a struct as a record< or part of a record. The "P& often uses preGdefined structs< but these are UNO structs< a highlyGspecialiBed -ind of struct.
0efi%itio%
,ith the T.pe111En- T.pe statements< you can define your own :nonG'0#; structs:
T.pe Aenu6(e# % ssign (&e n #e o) (&e (.pe %"e)ine (&e - ( )ie+-s 0i(&in (&e s(ru'(1 E '& % -e)ini(ion +oo/s +i/e "i# s( (e#en(< 0i(&ou( (&e @"i#@1 7o## n- s S(ring Tex( s S(ring En- T.pe %'+ose (&e -e)ini(ion
&%sta%ce
The T.pe definition is only a pattern or template< not a set of actual *ariables. To ma-e an instance of the type< actual *ariables that can be read and stored< use the "i# s 5e0 statement:
"i# # 6(e# s 5e0 Aenu6(e#
2cope
"s shown in the e9ample below< the T.pe definition may be written at the start of a module :before the first Sub or 8un'(ion;. The definition will then be a*ailable to all routines in the module. "s of #pen#ffice.org .ersion 1.3< unli-e *ariables< there is no way to ma-e the definition accessible outside of the module. "n instance of the new type is a *ariable< and follows the usual rules for *ariable scope :see Scope and Life Span of .ariables;.
3-
Ot&er (nstructions
"n e9ample of how to use the definition< and how to reference the fields within an instance< appears in the section on Ci(&111En- Ci(&.
-ith..."%d -ith
7ua/ifiers
&n general< $asic does not loo- inside a container< such as an 3b:e'(< to see what names might be defined there. &f you want to use such a name< you must tell $asic where to loo-. You do that by using the name of the object as a qualifier. ,rite it before the inner name< and separate it by a period:
A.3b:e'(1So#e5 #e
Since containers may hold other containers< you may need more than one ?ualifier. ,rite the ?ualifiers in order< from outer to inner:
3u(er3b:e'(16nner3b:e'(18 r6nsi-e3b:e'(1So#e5 #e
These names may also be described as< Nconcatenated with the dotGoperator :C.C;N.
!he -ith /ter%ati*e

The Ci(&111En- Ci(& brac-eting statements pro*ide an alternati*e to writing out all the ?ualifiers< e*ery time G and some of the ?ualifiers in the "P& can be ?uite long. You specify the ?ualifiers in the Ci(& statement. 'ntil $asic encounters the En- Ci(& statement< it loo-s for partly-qualified names: names that begin with a period :unary dotGoperator;. The compiler uses the ?ualifiers from the Ci(& as though they were written in front of the partlyG?ualified name.
"1amp/e $6
'ser4defi%ed 2truct
This e9ample shows how you may define and use a struct< and how to reference the items within it< both with and without Ci(&. 6ither way< the names of the data fields :from the T.pe definition; must be ?ualified by the name of the instance :from the "i# statement;.
T.pe Aenu6(e# 7o## n- s S(ring Tex( s S(ring En- T.pe Sub A in %7re (e n ins( n'e o) (&e userH-e)ine- s(ru'(1 % 5o(e (&e /e.0or-< @5e0@1 "i# # 6(e# s 5e0 Aenu6(e# Ci(& # 6(e# 1 7o## n- = @1uno!7op.@ 1 Tex( = @Y7op.@ En- Ci(& Asg2ox En- Sub @7o## n-! @ G # 6(e#1 7o## n- G 7&r(13) _ G @Tex(! @ G # 6(e#1 Tex(
"1amp/e )6 Case stateme%t

&n ells and @anges< the following e9ample has the ?ualifiers in the 7 se statements written out completely< for clarity. You can write it more easily< this way:
"i# "o' $s 3b:e'( "i# S&ee( $s 3b:e'( "i# 7e++ $s 3b:e'(
3/
Ot&er (nstructions
"o' = T&is7o#ponen( S&ee( = "o'1S&ee(s(D) 7e++ = S&ee(1ge(7e++2.Mosi(ion(1<1) 7e++14 +ue = 1DDD Ci(& 'o#1sun1s( r1( b+e17e++7on(en(T.pe Se+e'( 7 se 7e++1T.pe 7 se 1EAMTZ Asg2ox @7on(en(! E#p(.@ 7 se 14$LNE Asg2ox @7on(en(! 4 +ue@ 7 se 1TERT Asg2ox @7on(en(! Tex(@ 7 se 183,ANL$ Asg2ox @7on(en(! 8or#u+ @ En- Se+e'( En- Ci(&
%7e++ @22@ (DHb se-I)
0otice that the Ci(& construct must be entirely outside of the Se+e'( construct.
37
C H
P ! " #
untime Li!rar"
The following sections present the central functions of the runtime library:

on*ersion 5unctions Strings Date and Time 5iles and Directories )essage and &nput $o9es #ther 5unctions
Co%*ersio% 3u%ctio%s
&n many situations< circumstances arise in which a *ariable of one type has to be changed into a *ariable of another type.
&mp/icit a%d "1p/icit !ype Co%*ersio%s

The easiest way to change a *ariable from one type to another is to use an assignment.
"i# $ $s S(ring "i# 2 $s 6n(eger 2 = 1D1 $ = 2
&n this e9ample< *ariable $ is a string< and *ariable 2 is an integer. #pen#ffice.org $asic ensures that *ariable 2 is con*erted to a string during assignment to *ariable $. This con*ersion is much more elaborate than it appears: the integer 2 remains in the wor-ing memory in the form of a twoGbyte long number. $< on the other hand< is a string< and the computer sa*es a oneG or twoGbyte long *alue for each character :each number;. Therefore< before copying the content from 2 to $< 2 has to be con*erted into $Cs internal format. 'nli-e most other programming languages< $asic performs type con*ersion automatically. 7owe*er< this may ha*e fatal conse?uences. 'pon closer inspection< the following code se?uence
"i# $ $s S(ring "i# 2 $s 6n(eger "i# 7 $s 6n(eger 2 = 1 7 = 1 $ = 2 + 7
which at first glance seems straightforward< ultimately pro*es to be something of a trap. The $asic
39
%on#ersion 2unctions
interpreter first calculates the result of the addition process and then con*erts this into a string< which< as its result< produces the string !. &f< on the other hand< the $asic interpreter first con*erts the start *alues 2 and 7 into a string and applies the plus operator to the result< it produces the string 11. The same applies when using *ariant *ariables:
"i# $ "i# 2 "i# 7 2 = 1 7 = @1@ $ = 2 + 7
Since *ariant *ariables may contain both numbers and strings< it is unclear whether *ariable $ is assigned the number ! or the string //. The error sources noted for implicit type con*ersions can only be a*oided by careful programmingM for e9ample< by not using the *ariant data type. To a*oid other errors resulting from implicit type con*ersions< #pen#ffice.org $asic offers a range of con*ersion functions< which you can use to define when the data type of an operation should be con*erted:
CStr(Var)
con*erts any data type into a string.

CInt(Var)
con*erts any data types into an integer *alue.

CLng(Var)
con*erts any data types into a long *alue.

CSng(Var)
con*erts any data types into a single *alue.

CDbl(Var)
con*erts any data types into a double *alue.

CBool(Var)
con*erts any data types into a $oolean *alue.

CDate(Var)
con*erts any data types into a date *alue. You can use these con*ersion functions to define how #pen#ffice.org $asic should perform these type con*ersion operations:
"i# $ $s S(ring "i# 2 $s 6n(eger "i# 7 $s 6n(eger 2 = 1 7 = 1 $ = 7S(r(2 + 7) $ = 7S(r(2) + 7S(r(7)
% % % %
2 n- 7 re --e- (oge(&er )irs(< (&en 'on*er(e- (o (&e s(ring @2@ 2 n- 7 re 'on*er(e- in(o s(ring<(&en 'o#bine- (o pro-u'e (&e s(ring @11@
During the first addition in the e9ample< #pen#ffice.org $asic first adds the integer *ariables and then con*erts the result into a chain of characters. $ is assigned the string 2. &n the second instance< the integer *ariables are first con*erted into two strings and then lin-ed with one another by means of the assignment. $ is therefore assigned the string 11. The numerical 7Sng and 7"b+ con*ersion functions also accept decimal numbers. The symbol defined in the corresponding countryGspecific settings must be used as the decimal point symbol. on*ersely< the 7S(r
40
methods use the currently selected countryGspecific settings when formatting numbers< dates and time details. The 4 + function is different from the 7sng< 7-b+ and 7s(r methods. &t con*erts a string into a numberM howe*er it always e9pects a period to be used as the decimal point symbol.
"i# $ $s S(ring "i# 2 $s "oub+e $ = @2122@ 2 = 4 +($) % 6s 'on*er(e- 'orre'(+. reg r-+ess o) (&e % 'oun(r.Hspe'i)i' se((ings
Chec,i%g the Co%te%t of .ariab/es

&n some instances< the date cannot be con*erted:
"i# $ $s S(ring "i# 2 $s " (e $ = @(es(@ 2 = $ % 7re (es error #ess ge
&n the e9ample shown< the assignment of the (es( string to a date *ariable ma-es no sense< so the $asic interpreter reports an error. The same applies when attempting to assign a string to a $oolean *ariable:
"i# $ $s S(ring "i# 2 $s 2oo+e n $ = @(es(@ 2 = $ % 7re (es error #ess ge
"gain< the basic interpreter reports an error. These error messages can be a*oided by chec-ing the program before an assignment< in order to establish whether the content of the *ariable to be assigned matches the type of the target *ariable. #pen#ffice.org $asic pro*ides the following test functions for this purpose:
IsNumeric(Value)
chec-s whether a *alue is a number.

IsDate(Value)
chec-s whether a *alue is a date.

IsArra (Value)
chec-s whether a *alue is an array. These functions are especially useful when ?uerying user input. 5or e9ample< you can chec- whether a user has typed a *alid number or date.
6) 6s5u#eri'(Nser6npu() T&en 4 +i-6npu( = Nser6npu( E+se 4 +i-6npu( = D Asg2ox @Error #ess ge1@ En- 6)
&n the pre*ious e9ample< if the Nser6npu( *ariable contains a *alid numerical *alue< then this is assigned to the 4 +i-6npu( *ariable. &f Nser6npu( does not contain a *alid number< 4 +i-6npu( is assigned the *alue D and an error message is returned. ,hile test functions e9ist for chec-ing numbers< date details and arrays in #pen#ffice.org $asic< a corresponding function for chec-ing $oolean *alues does not e9ist. The functionality can< howe*er< be imitated by using the 6s2oo+e n function:
8un'(ion 6s2oo+e n(4 +ue $s 4 ri n() $s 2oo+e n 3n Error Go(o Error6s2oo+e n! "i# "u##. $s 2oo+e n "u##. = 4 +ue
%&apter 3 5untime Librar1
41
6s2oo+e n = True 3n Error Go(o D Exi( Sub Error6s2oo+e n! 6s2oo+e n = 8 +se 3n Error Go(o D En- 8un'(ion
The 6s2oo+e n function defines an internal "u##. help *ariable of the $oolean type and tries to assign this to the transferred *alue. &f assignment is successful< the function returns True. &f it fails< a runtime error is produced< the error handler intercepts the error< and the function returns 8 +se. Note VBA : &f a string in #pen#ffice.org $asic contains a nonGnumerical *alue and if this is assigned to a number< #pen#ffice.org $asic does not produce an error message< but stops con*erting the string at the first in*alid character. This procedure differs from .$". There< an error is triggered and program implementation terminated if a corresponding assignment is e9ecuted.
2tri%gs
-or,i%g +ith 2ets of Characters
,hen administering strings< #pen#ffice.org $asic uses the set of 'nicode characters. The $s' and 7&r functions allow the 'nicode *alue belonging to a character to be established and/or the corresponding character to be found for a 'nicode *alue. The following e9pressions assign the *arious 'nicode *alues to the code *ariable:
7o-e = $s'(@$@) 7o-e = $s'(@[@) 7o-e = $s'(@\@) % L (in +e((er $ (Nni'o-eH* +ue 65) % Euro '& r '(er (Nni'o-eH* +ue 8364) % 7.ri++i' +e((er \ (Nni'o-eH* +ue 1D83)
on*ersely< the e9pression )yString O hr:/1; ensures that the A.S(ring string is initialiBed with the *alue of the number 13< which stands for a hard line brea-. The 7&r command is often used in $asic languages to insert control characters in a string. The assignment )yString O hr:+; E NThis is a testN E hr:/1; therefore ensures that the te9t is preceded by a tab character :'nicodeG*alue +; and that a hard line brea- :'nicodeG*alue /1; is added after the te9t.
ccessi%g Parts of a 2tri%g

#pen#ffice.org $asic pro*ides three functions that return partial strings< plus a length function:
Le!t(" String# Length)
returns the first Leng(& characters of A.S(ring.

$ight(" String# Length)
returns the last Leng(& characters of A.S(ring.

"i%(" String# Start# Length)
returns first Leng(& characters of A.S(ring as of the S( r( position.

Len(" String)
returns the number of characters in A.S(ring. 7ere are a few e9ample calls for the named functions:
"i# A.S(ring $s S(ring
4"
!trings
"i# A.,esu+( $s S(ring "i# A.Len $s 6n(eger A.S(ring = @T&is is s# ++ (es(@ A.,esu+( = Le)((A.S(ring<5) % A.,esu+( = ,ig&((A.S(ring< 5) % A.,esu+( = Ai-(A.S(ring< 8< 5) % A.Len = Len(A.S(ring) % Mro*i-es Mro*i-es Mro*i-es Mro*i-es (&e (&e (&e (&e s(ring @T&is @ s(ring @ (es(@ s(ring @ s#@ * +ue 2D
2earch a%d #ep/ace

#pen#ffice.org $asic pro*ides the 6nS(r function for searching for a partial string within another string:
,esu+(S(ring = 6nS(r (A.S(ring< Se r'&S(ring)
The Se r'&S(ring parameter specifies the string to be searched for within A.S(ring. The function returns a number that contains the position at which the Se r'&S(ring first appears within A.S(ringM a return *alue of Bero indicates no match. &f you want to find other matches for the string< the function also pro*ides the opportunity to specify an optional start position from which #pen#ffice.org $asic begins the search. &n this case< the synta9 of the function is:
,esu+(S(ring = 6nS(r(S( r(Mosi(ion< A.S(ring< Se r'&S(ring)
&n the pre*ious e9amples< 6nS(r ignores uppercase and lowercase characters. To change the search so that 6nS(r is case sensiti*e< add the parameter D< as shown in the following e9ample:
,esu+(S(ring = 6nS(r(A.S(ring< Se r'&S(ring< D)
'sing the pre*ious functions for editing strings< programmers can search for and replace one string in another string:
8un'(ion ,ep+ 'e(Sour'e $s S(ring< Se r'& $s S(ring< 5e0M r( $s S(ring) "i# ,esu+( $s S(ring "i# S( r(Mos $s Long "i# 7urren(Mos $s Long ,esu+( = @@ S( r(Mos = 1 7urren(Mos = 1 6) Se r'& = @@ T&en ,esu+( = Sour'e E+se "o C&i+e 7urren(Mos TU D 7urren(Mos = 6nS(r(S( r(Mos< Sour'e< Se r'&) 6) 7urren(Mos TU D T&en ,esu+( = ,esu+( + Ai-(Sour'e< S( r(Mos< _ 7urren(Mos H S( r(Mos) ,esu+( = ,esu+( + 5e0M r( S( r(Mos = 7urren(Mos + Len(Se r'&) E+se ,esu+( = ,esu+( + Ai-(Sour'e< S( r(Mos< Len(Sour'e)) En- 6) % Mosi(ion TU D Loop En- 6) ,ep+ 'e = ,esu+( En- 8un'(ion
The function searches through the transferred Se r'& string in a loop by means of 6nS(r in the original term Sour'e. &f it finds the search term< it ta-es the part before the e9pression and writes it to the ,esu+( return buffer. &t adds the 5e0M r( section at the point of the search term Se r'&. &f no more matches are found for the search term< the function establishes the part of the string still remaining and adds this to the return buffer. &t returns the string produced in this way as the result of the replacement process. Since replacing parts of character se?uences is one of the most fre?uently used functions< the Ai- function in #pen#ffice.org $asic has been e9tended so that this tas- is performed automatically. The following e9ample replaces three characters with the string is from the si9th position of the A.S(ring string.
"i# A.S(ring $s S(ring A.S(ring = @T&is 0 s #. (ex(@ Ai-(A.S(ring< 6< 3< @is@)
43
!trings
-ar%i%g ,hen it is used with 8 arguments< to replace a subGstring in a string< Ai- is an %$s r!c %o$< not a function : it does not return any *alue S
3ormatti%g 2tri%gs
The 8or# ( function formats numbers as a string. To do this< the function e9pects a 8or# ( e9pression to be specified< which is then used as the template for formatting the numbers. 6ach place holder within the template ensures that this item is formatted correspondingly in the output *alue. The fi*e most important place holders within a template are the Bero :D;< pound sign :J;< period :1;< comma :<; and dollar sign :F; characters. The D character within the template ensures that a number is always placed at the corresponding point. &f a number is not pro*ided< 3 is displayed in its place. " 1 stands for the decimal point symbol defined by the operating system in the countryGspecific settings. The e9ample below shows how the D and 1 characters can define the digits after the decimal point in an e9pression:
A.8or# ( A.S(ring A.S(ring A.S(ring A.S(ring = = = = = @D1DD@ 8or# ((H157L18< A.8or# () 8or# ((157L18< A.8or# () 8or# ((D14< A.8or# () 8or# ((D1434< A.8or# () % % % % Mro*i-es Mro*i-es Mro*i-es Mro*i-es @H157L<8D@ @157L<8D@ @D<4D@ @D<43@
&n the same way< Beros can be added in front of a number to achie*e the desired length:
A.8or# ( A.S(ring A.S(ring A.S(ring A.S(ring = = = = = @DDDD1DD@ 8or# ((H157L18< A.8or# () 8or# ((157L18< A.8or# () 8or# ((D14< A.8or# () 8or# ((D1434< A.8or# () % % % % Mro*i-es Mro*i-es Mro*i-es Mro*i-es @H157L<8D@ @157L<8D@ @DDDD<4D@ @DDDD<43@
" < represents the character that the operating system uses for a thousands separator< and the J stands for a digit or place that is only displayed if it is re?uired by the input string.
A.8or# ( A.S(ring A.S(ring A.S(ring A.S(ring = = = = = @J<JJD1DD@ 8or# ((H157L18< A.8or# () 8or# ((157L18< A.8or# () 8or# ((D14< A.8or# () 8or# ((D1434< A.8or# () % % % % Mro*i-es Mro*i-es Mro*i-es Mro*i-es @H1157L<8D@ @1157L<8D@ @D<4D@ @D<43@
&n place of the F place holder< the 8or# ( function displays the rele*ant currency symbol defined by the system :this e9ample assumes a 6uropean locale has been defined;:
A.8or# ( A.S(ring A.S(ring A.S(ring A.S(ring = = = = = @J<JJD1DD F@ 8or# ((H157L18< A.8or# () 8or# ((157L18< A.8or# () 8or# ((D14< A.8or# () 8or# ((D1434< A.8or# () % % % % Mro*i-es Mro*i-es Mro*i-es Mro*i-es @H1157L<8D [@ @1157L<8D [@ @D<4D [@ @D<43 [@
The format instructions used in .$" for formatting date and time details can also be used:
sub # in -i# #." (e s - (e #." (e = @D1OD6OL8@ Tes(S(r = 8or# ((#." (e< @##H--H....@) % D1HD6H1LL8 Asg2ox Tes(S(r en- sub
0ate a%d !ime

#pen#ffice.org $asic pro*ides the " (e data type< which sa*es the date and time details in binary format.
44
6ate and 'ime
2pecificatio% of 0ate a%d !ime 0etai/s +ithi% the Program Code

You can assign a date to a date *ariable through the assignment of a simple string:
"i# A." (e $s " (e A." (e = @241112DD2@
This assignment can function properly because #pen#ffice.org $asic automatically con*erts the date *alue defined as a string into a date *ariable. This type of assignment< howe*er< can cause errors< date and time *alues are defined and displayed differently in different countries. Since #pen#ffice.org $asic uses the countryGspecific settings of the operating system when con*erting a string into a date *alue< the e9pression shown pre*iously only functions correctly if the countryGspecific settings match the string e9pression. To a*oid this problem< the " (eSeri + function should be used to assign a fi9ed *alue to a date *ariable:
"i# A.4 r $s " (e A." (e = " (eSeri + (2DD1< 1< 24)
The function parameter must be in the se?uence: year< month< day. The function ensures that the *ariable is actually assigned the correct *alue regardless of the countryGspecific settings The Ti#eSeri + function formats time details in the same way that the " (eSeri + function formats dates:
"i# A.4 r $s " (e A." (e = Ti#eSeri +(11< 23< 45)
Their parameters should be specified in the se?uence: hours< minutes< seconds.
"1tracti%g 0ate a%d !ime 0etai/s

The following functions form the counterpart to the " (eSeri + and Ti#eSeri + functions:
Da (" Date)
returns the day of the month from A." (e.

"onth(" Date)
returns the month from A." (e.

&ear(" Date)
returns the year from A." (e.

Wee'%a (" Date)
returns the number of the wee-day from A." (e.

(our(" )ime)
returns the hours from A.Ti#e.

"inute(" )ime)
returns the minutes from A.Ti#e.

Secon%(" )ime)
returns the seconds from A.Ti#e. These functions e9tract the date or time sections from a specified " (e *ariable. The following e9ample chec-s whether the date sa*ed in A." (e is in the year !331.
"i# A." (e $s " (e % 111 6ni(i +iX (ion o) A." (e 6) Ze r(A." (e) = 2DD3 T&en % 111 Spe'i)ie- - (e is in (&e .e r 2DD3 En- 6)
4-
6ate and 'ime
&n the same way< the following e9ample chec-s whether A.Ti#e is between /! and /8 hours.
"i# A.Ti#e $s " (e % 111 6ni(i +iX (ion o) A.Ti#e 6) Bour(A.Ti#e) U= 12 $n- Bour(A.Ti#e) T 14 T&en % 111 Spe'i)ie- (i#e is be(0een 12 n- 14 &ours En- 6)
The Cee/- . function returns the number of the wee-day for the transferred date:
"i# A." (e $s " (e "i# A.Cee/- . $s S(ring % 111 ini(i +iXe A." (e Se+e'( 7 se ' se 1 A.Cee/' se 2 A.Cee/' se 3 A.Cee/' se 4 A.Cee/' se 5 A.Cee/' se 6 A.Cee/' se 7 A.Cee/En- Se+e'( Cee/" .(A." (e) . = @Sun- .@ . = @Aon- .@ . = @Tues- .@ . = @Ce-nes- .@ . = @T&urs- .@ . = @8ri- .@ . = @S (ur- .@
Note Sunday is considered the first day of the wee-.
#etrie*i%g 2ystem 0ate a%d !ime

The following functions are a*ailable in #pen#ffice.org $asic to retrie*e the system time and system date:
Date
returns the present date as a string. The format depends on localiBation settings.
)ime
returns the present time as a string.

No*
returns the present point in time :date and time; as a combined *alue of type " (e.
3i/es a%d 0irectories

,or-ing with files is one of the basic tas-s of an application. The #pen#ffice.org "P& pro*ides you with a whole range of objects with which you can create< open and modify #ffice documents. These are presented in detail in the &ntroduction to the #pen#ffice.org "P&. @egardless of this< in some instances you will ha*e to directly access the file system< search through directories or edit te9t files. The runtime library from #pen#ffice.org $asic pro*ides se*eral fundamental functions for these tas-s. Note Some D#SGspecific file and directory functions are no longer pro*ided in #pen#ffice.org< or their function is only limited. 5or e9ample< support for the 7&"ir< 7&"ri*e and 7ur"ir functions is not pro*ided. Some D#SGspecific properties are no longer used in functions that e9pect file properties as parameters :for e9ample< to differentiate from concealed files and system files;. This change became necessary to ensure the greatest possible le*el of platform independence for #pen#ffice.org.
4/
2i,es and 6irectories
dmi%isteri%g 3i/es
Compatibi/ity (ode
The 7o#p (ibi+i(.Ao-e statement and function pro*ide greater compatibility with .$"< by changing the operation of certain functions. The effect on any particular function is described with that function< below. "s a statement< 7o#p (ibi+i(.Ao-e( * +ue ) ta-es a $oolean *alue to set or clear the mode. "s a function< 7o#p (ibi+i(.Ao-e() returns the $oolean *alue of the mode.
7o#p (ibi+i(.Ao-e( True ) %se( #o-e 7o#p (ibi+i(.Ao-e( 8 +se) %'+e r #o-e "i# bAo-e s 2oo+e n bAo-e = 7o#p (ibi+i(.Ao-e()
2earchi%g !hrough 0irectories

The "ir function in #pen#ffice.org $asic is responsible for searching through directories for files and subG directories. ,hen first re?uested< a string containing the path of the directories to be searched must be assigned to "ir as its first parameter. The second parameter of "ir specifies the file or directory to be searched for. #pen#ffice.org $asic returns the name of the first directory entry found. To retrie*e the ne9t entry< the "ir function should be re?uested without parameters. &f the "ir function finds no more entries< it returns an empty string. The following e9ample shows how the "ir function can be used to re?uest all files located in one directory. The procedure sa*es the indi*idual file names in the $++8i+es *ariable and then displays this in a message bo9.
Sub S&o08i+es "i# 5ex(8i+e $s S(ring "i# $++8i+es $s S(ring $++8i+es = @@ 5ex(8i+e = "ir(@7!P@< D) C&i+e 5ex(8i+e TU @@ $++8i+es = $++8i+es G 7&r(13) G 5ex(8i+e = "ir CenAsg2ox $++8i+es En- Sub 5ex(8i+e
The D :Bero; used as the second parameter in the "ir function ensures that "ir only returns the names of files and directories are ignored. The following parameters can be specified here:

D : returns normal files 16 : subGdirectories
The following e9ample is *irtually the same as the preceding e9ample< but the "ir function transfers the *alue /2 as a parameter< which returns the subGdirectories of a folder rather than the file names.
Sub S&o0"irs "i# 5ex("ir $s S(ring "i# $++"irs $s S(ring $++"irs = @@ 5ex("ir = "ir(@7!P@< 16) C&i+e 5ex("ir TU @@ $++"irs = $++"irs G 7&r(13) G 5ex("ir = "ir CenAsg2ox $++"irs En- Sub 5ex("ir
47
Note VBA : ,hen re?uested in #pen#ffice.org $asic< the "ir function< using the parameter /2< only returns the subGdirectories of a folder. &n .$"< the function also returns the names of the standard files so that further chec-ing is needed to retrie*e the directories only. ,hen using the 7o#p (ibi+i(.Ao-e ( (rue ) function< #pen#ffice.org $asic beha*es li-e .$" and the Dir function< using parameter /2< returns subGdirectories and standard files. Note VBA : The options pro*ided in .$" for searching through directories specifically for files with the co$cea#ed< s(s em "%#e< arc)%'ed< and 'o#!me $ame properties does not e9ist in #pen#ffice.org $asic because the corresponding file system functions are not a*ailable on all operating systems. Note VBA : The path specifications listed in "ir may use the T and U place holders in both .$" and #pen#ffice.org $asic. &n #pen#ffice.org $asic< the T place holder may howe*er only be the last character of a file name and/or file e9tension< which is not the case in .$".
Creati%g a%d 0e/eti%g 0irectories

#pen#ffice.org $asic pro*ides the A/"ir function for creating directories.
A/"ir (@7!PSub"ir1@)
This function creates directories and subGdirectories. "ll directories needed within a hierarchy are also created< if re?uired. 5or e9ample< if only the 7!PSub"ir1 directory e9ists< then a call
A/"ir (@7!PSub"ir1PSub"ir2PSub"ir3P@)
creates both the 7!PSub"ir1PSub"ir2 directory and the 7!PSub"ir1PSub"ir2PSub"ir3 directory. The ,#"ir function deletes directories.
,#"ir (@7!PSub"ir1PSub"ir2PSub"ir3P@)
&f the directory contains subGdirectories or files< these are a#so de#e ed. You should therefore be careful when using ,#"ir. Note VBA : &n .$"< the A/"ir and ,#"ir functions only relate to the current directory. &n #pen#ffice.org $asic on the other hand< A/"ir and ,#"ir can be used to create or delete le*els of directories. Note VBA : &n .$"< ,#"ir produces an error message if a directory contains a file. &n #pen#ffice.org $asic< the directory a$d a## % s "%#es are deleted. &f you use the 7o#p (ibi+i(.Ao-e ( (rue ) function< #pen#ffice.org $asic will beha*e li-e .$".
Copyi%g5 #e%ami%g5 0e/eti%g a%d Chec,i%g the "1iste%ce of 3i/es

The following call creates a copy of the Sour'e file under the name of "es(in (ion:
8i+e7op.(Sour'e< "es(in (ion)
,ith the help of the following function you can rename the 3+-5 #e file with 5e05 #e. The $s -eyword synta9< and the fact that a comma is not used< goes bac- to the roots of the $asic language.
5 #e 3+-5 #e $s 5e05 #e
The following call deletes the 8i+en #e file. &f you want to delete directory :including its files; use the ,#"ir function.
Vi++(8i+en #e)
40
The 8i+eExis(s function can be used to chec- whether a file e9ists:

6) 8i+eExis(s(8i+en #e) T&en Asg2ox @)i+e exis(s1@ En- 6)
#eadi%g a%d Cha%gi%g 3i/e Properties

,hen wor-ing with files< it is sometimes important to be able to establish the file properties< the time the file was last changed and the length of the file. The following call returns some properties about a file.
"i# $((r $s 6n(eger $((r = Ge($((r(8i+en #e)
The return *alue is pro*ided as a bit mas- in which the following *alues are possible:

/ : readGonly file /2 : name of a directory
The following e9ample determines the bit mas- of the (es(1(x( file and chec-s whether this is readGonly whether it is a directory. &f neither of these apply< 8i+e"es'rip(ion is assigned the NnormalN string.
"i# 8i+eA s/ $s 6n(eger "i# 8i+e"es'rip(ion $s S(ring 8i+eA s/ = Ge($((r(@(es(1(x(@) 6) (8i+eA s/ $5" 1) U D T&en 8i+e"es'rip(ion = 8i+e"es'rip(ion G @ re -Hon+. @ En- 68 6) (8i+eA s/ $5" 16) U D T&en 8i+e"es'rip(ion = 8i+e"es'rip(ion G @ -ire'(or. @ En- 68 6) 8i+e"es'rip(ion = @@ T&en 8i+e"es'rip(ion = @ nor# + @ En- 68 Asg2ox 8i+e"es'rip(ion
Note VBA : The flags used in .$" for ?uerying the co$cea#ed< s(s em "%#e*arc)%'ed and 'o#!me $ame file properties are not supported in #pen#ffice.org $asic because these are ,indowsGspecific and are not or are only partially a*ailable on other operating systems. The Se($((r function permits the properties of a file to be changed. The following call can therefore be used to pro*ide a file with readGonly status:
Se($((r(@(es(1(x(@< 1)
"n e9isting readGonly status can be deleted with the following call:
Se($((r(@(es(1(x(@< D)
The date and time of the last amendment to a file are pro*ided by the 8i+e" (eTi#e function. The date is formatted here in accordance with the countryGspecific settings used on the system.
8i+e" (eTi#e(@(es(1(x(@) % Mro*i-es - (e n- (i#e o) (&e + s( )i+e #en-#en(1
The 8i+eLen function determines the length of a file in bytes :as long integer *alue;.
8i+eLen(@(es(1(x(@) % Mro*i-es (&e +eng(& o) (&e )i+e in b.(es
-riti%g a%d #eadi%g !e1t 3i/es

#pen#ffice.org $asic pro*ides a whole range of methods for reading and writing files. The following e9planations relate to wor-ing with te9t files :$o te9t documents;.
49
-riti%g !e1t 3i/es

$efore a te9t file is accessed< it must first be opened. To do this< a free "%#e )a$d#e is needed< which clearly identifies the file for subse?uent file access. The 8ree8i+e function is used to create a free file handle:
8i+e5o = 8ree8i+e
8i+e5o is an integer *ariable that recei*es the file handle. The handle is then used as a parameter for the 3pen instruction< which opens the file.
To open a file so that it can be written as a te9t file< the 3pen call is:
3pen 8i+en #e 8or 3u(pu( $s J8i+e5o
8i+en #e is a string containing the name of the file. 8i+e5o is the handle created by the 8ree8i+e
function. #nce the file is opened< the Mrin( instruction can create the file contents< line by line:
Mrin( J8i+e5o< @T&is is (es( +ine1@
8i+e5o also stands for the file handle here. The second parameter specifies the te9t that is to be sa*ed as a
line of the te9t file. #nce the writing process has been completed< the file must be closed using a 7+ose call:
7+ose J8i+e5o
"gain here< the file handle should be specified. The following e9ample shows how a te9t file is opened< written< and closed:
"i# 8i+e5o $s 6n(eger "i# 7urren(Line $s S(ring "i# 8i+en #e $s S(ring 8i+en #e = @'!P- ( 1(x(@ 8i+e5o = 8ree8i+e % "e)ine )i+e n #e % Es( b+is& )ree )i+e & n-+e
3pen 8i+en #e 8or 3u(pu( $s J8i+e5o % 3pen )i+e (0ri(ing #o-e) Mrin( J8i+e5o< @T&is is +ine o) (ex(@ % S *e +ine Mrin( J8i+e5o< @T&is is no(&er +ine o) (ex(@ % S *e +ine 7+ose J8i+e5o % 7+ose )i+e
#eadi%g !e1t 3i/es

Te9t files are read in the same way that they are written. The 3pen instruction used to open the file contains the 8or 6npu( e9pression in place of the 8or 3u(pu( e9pression and< rather than the Print command for writing data< the Line &nput instruction should be used to read the data. 5inally< when calling up a te9t file< the eo) instruction is used to chec- whether the end of the file has been reached:
eo)(8i+e5o)
The following e9ample shows how a te9t file can be read:

"i# "i# "i# "i# 8i+e5o $s 6n(eger 7urren(Line $s S(ring 8i+e $s S(ring Asg s S(ring
% "e)ine )i+en #e 8i+en #e = @'!P- ( 1(x(@ % Es( b+is& )ree )i+e & n-+e 8i+e5o = 8ree)i+e % 3pen )i+e (re -ing #o-e)
-0
3pen 8i+en #e 8or 6npu( $s 8i+e5o % 7&e'/ 0&e(&er )i+e en- & s been re '&e"o C&i+e no( eo)(8i+e5o) % ,e - +ine Line 6npu( J8i+e5o< 7urren(Line 6) 7urren(Line TU@@ (&en Asg = Asg G 7urren(Line G 7&r(13) en- i) Loop % 7+ose )i+e 7+ose J8i+e5o Asgbox Asg
The indi*idual lines are retrie*ed in a "o C&i+e loop< sa*ed in the Asg *ariable< and displayed at the end in a message bo9.
(essage a%d &%put Bo1es

#pen#ffice.org $asic pro*ides the Asg2ox and 6npu(2ox functions for basic user communication.
0isp/ayi%g (essages
Asg2ox displays a basic information bo9< which can ha*e one or more buttons. &n its simplest *ariant the Asg2ox only contains te9t and an #P button:
Asg2ox @T&is is pie'e o) in)or# (ionI@
The appearance of the information bo9 can be changed using a parameter. The parameter pro*ides the option of adding additional buttons< defining the preGassigned button< and adding an information symbol. Note $y con*ention< the symbolic names gi*en below are written in 'PP6@ "S6< to mar- them as predefined< rather than userGdefined. 7owe*er< the names are not caseGsensiti*e. The *alues for selecting the buttons are:

D< A2_3V G #P button 1< A2_3V7$57EL G #P and 2< 3< 4< 5<
ancel button A2_$23,T,ET,Z6G53,E G "bort< @etry< and &gnore buttons A2_ZES537$57EL G Yes< 0o< and ancel buttons A2_ZES53 G Yes and 0o buttons A2_,ET,Z7$57EL G @etry and ancel buttons
To set a button as the default button< add one of the following *alues to the parameter *alue from the list of button selections. 5or e9ample< to create Yes< 0o and ancel buttons :*alue 1; where ancel is the default :*alue 4/!;< the parameter *alue is 1 E 4/! O 4/4. The e9pression A2_ZES537$57EL + A2_"E82NTT353 is harder to write< but easier to understand.

D< A2_"E82NTT351 G 5irst button is default *alue 256< A2_"E82NTT352 G Second button is default *alue 512< A2_"E82NTT353 G Third button is default *alue
5inally< the following information symbols are a*ailable and can also be displayed by adding the rele*ant parameter *alues:

16< A2_6735ST3M G Stop sign 32< A2_6735SNEST635 G >uestion mar48< A2_6735ER7L$A$T635 G 69clamation point
-1
7essage and (nput Bo8es
64< A2_67356583,A$T635 G Tip icon
The following call displays an information bo9 with the Yes and 0o buttons :*alue 8;< of which the second button :0o; is set as the default *alue :*alue !42; and which also recei*es a ?uestion mar- :*alue 1!;< 8E!42E1!O!+!.
Asg2ox @"o .ou 0 n( (o 'on(inue]@< 2L2 % or< Asg2ox @"o .ou 0 n( (o 'on(inue]@< A2_ZES53 + A2_"E82NTT352 + A2_6735SNEST635
Display of the Message Box &f an information bo9 contains se*eral buttons< then a return *alue should be ?ueried to determine which button has been pressed. The following return *alues are a*ailable in this instance:

1< 6"3V G #2< 6"7$57EL G
ancel
3< 6"$23,T G "bort 4< 6",ET,Z G @etry 5 G &gnore 6< 6"ZES G Yes 7< 6"53 G 0o
&n the pre*ious e9ample< chec-ing the return *alues could be as follows:
"i# i2ox s 6n(eger i2ox = A2_ZES53 + A2_"E82NTT352 + A2_6735SNEST635 6) Asg2ox (@"o .ou 0 n( (o 'on(inue]@< i2ox) = 6"ZES T&en % or< 6) Asg2ox (@"o .ou 0 n( (o 'on(inue]@< 2L2) = 6 T&en % Zes bu((on presseE+se % 5o bu((on presseEn- 68
&n addition to the information te9t and the parameter for arranging the information bo9< Asg2ox also permits a third parameter< which defines the te9t for the bo9 title:
Asg2ox @"o .ou 0 n( (o 'on(inue]@< 2L2< @2ox Ti(+e@
&f no bo9 title is specified< the default is VsofficeW.
&%put Bo1 3or 7ueryi%g 2imp/e 2tri%gs

The 6npu(2ox function ?ueries simple strings from the user. &t is therefore a simple alternati*e to configuring dialogs. 6npu(2ox recei*es three standard parameters:

"n information te9t. " bo9 title. " default *alue which can be added within the input area.
6npu(4 + = 6npu(2ox(@M+e se en(er * +ue!@< @Tes(@< @-e) u+( * +ue@)
-"
Display of the Input Box The dimensions of the 6npu(2ox window cannot be changed.
7essage and (nput Bo8es
&f the user clic-s the #P button< the 6npu(2ox returns the string typed by the user :or the default string if it was not changed;. &f the user clic-s the ancel button or closes the window< the 6npu(2ox returns an empty string.
Other 3u%ctio%s
Beep
The 2eep function causes the system to play a sound that can be used to warn the user of an incorrect action. 2eep does not ha*e any parameters:
2eep % 're (es n in)or# (i*e (one
2he//
69ternal programs can be started using the Shell function.
S&e++(M (&n #e< Cin-o0s(.+e< M r #< bS.n')
+a )$ame the path of the program to be e9ecuted. &n )SG,indows< use 7on*er(ToN,L(M (&n #e) otherwise the command will not wor- if M (&n #e contains spaces or national characters. ,%$do-s (#e the window in which the program is started. The following *alues are possible: 3 G The program recei*es the focus and is started in a concealed window. / G The program recei*es the focus and is started in a normalGsiBed window. ! G The program recei*es the focus and is started in a minimiBed window. 1 G The program recei*es the focus and is started in a ma9imiBed window. 8 G The program is started in a normalGsiBed window< without recei*ing the focus. 2 G The program is started in a minimiBed window< the focus remains in the current window. /3 G The program is started in full screen mode. +aram command line parameters to be transferred to the program to be started. ./($c wait for shell command to finish flag
(rue G wait for shell command to finish ) +se G donCt wait for shell command to finish
-ait a%d -ait'%ti/

The C i( statement suspends program e9ecution for a specified time. The waiting period is specified in milliseconds. The command:
-3
Ot&er 2unctions
C i( 2DDD
specifies a delay of ! seconds :!333 milliseconds;. The C i(Nn(i+ statement pro*ides a greater degree of compatibility with .$" parameter usage. C i(Nn(i+ ta-es a parameter of type " (e< with a combined date and time *alue. The command:
C i(Nn(i+ 5o0 + Ti#e4 +ue(@DD!DD!D2@)
specifies the same delay< ! seconds< as the pre*ious e9ample.
"%*iro%
The En*iron function returns the en*ironmental *ariables of the operating system. Depending on the system and configuration< *arious types of data are sa*ed here. The following call determines the en*ironment *ariables of temporary directory of the operating system:
"i# Te#p"ir Te#p"ir=En*iron (@TEAM@)
-4
C H
P ! " #
Introduction to the API
#pen#ffice.org objects and methods< such as paragraphs< spreadsheets< and fonts< are accessible to #pen#ffice.org $asic through the #pen#ffice.org application programming interface< or "P&. Through the "P&< for e9ample< documents can be created< opened< modified and printed. The "P& can be used not only by #pen#ffice.org $asic< but also by other programming languages< such as =a*a and EE. The interface between the "P& and *arious programming languages is pro*ided by something called 0$%'ersa# 1e -ork 2.3ec s :'0#;. This chapter pro*ides a bac-ground on the "P&. $uilding on this bac-ground< the following chapters will show how the "P& can be used to ma-e #pen#ffice.org do what you want it to do.
'%i*ersa/ Net+or, Ob8ects 9'NO:

#pen#ffice.org pro*ides a programming interface in the form of the 'ni*ersal 0etwor- #bjects :'0#;. This is an objectGoriented programming interface which #pen#ffice.org subGdi*ides into *arious objects which for their part ensure programGcontrolled access to the #ffice pac-age. Since #pen#ffice.org $asic is a procedural programming language< se*eral linguistic constructs ha*e had to be added to it which enable the use of '0#. To use a 'ni*ersal 0etwor- #bject in #pen#ffice.org $asic< you will need a *ariable declaration for the associated object. The declaration is made using the "i# instruction :see The Language of #pen#ffice.org $asic;. The 3b:e'( type designation should be used to declare an object *ariable:
"i# 3b: $s 3b:e'(
The call declares an object *ariable named 3b:. The object *ariable created must then be initialiBed so that it can be used. This can be done using the 're (eNnoSer*i'e function:
3b: = 're (eNnoSer*i'e(@'o#1sun1s( r1)r #e1"es/(op@)
This call assigns to the 3b: *ariable a reference to the newly created object. 'o#1sun1s( r1)r #e1"es/(op resembles an object typeM howe*er in '0# terminology it is called a ser*ice rather than a type. &n accordance with '0# philosophy< an #bj is described as a reference to an object which supports the
'o#1sun1s( r1)r #e1"es/(op
ser*ice. The ser*ice term used in #pen#ffice.org $asic therefore corresponds to the type and class terms used in other programming languages. There is< howe*er< one main difference: a 'ni*ersal 0etwor- #bject may support se*eral ser*ices at the
--
9ni#ersa, .et$or* Ob:ects ;9.O<
same time. Some '0# ser*ices in turn support other ser*ices so that< through one object< you are pro*ided with a whole range of ser*ices. 5or e9ample< that the aforementioned object< which is based on the
ser*ice< can also include other ser*ices for loading documents and for ending the program. Note VBA : ,hereas the structure of an object in .$" is defined by the class to which it belongs< in #pen#ffice.org $asic the structure is defined through the ser*ices which it supports. " .$" object is always assigned to precisely one single class. " #pen#ffice.org $asic object can< howe*er< support se*eral ser*ices.
Properties a%d (ethods

"n object in #pen#ffice.org $asic pro*ides a range of properties and methods which can be called by means of the object.
Properties
+roper %es are li-e the properties of an objectM for e9ample< 8i+en #e and Ti(+e for a "o'u#en( object. The properties are set by means of a simple assignment:
"o'u#en(1Ti(+e = @3pen3))i'e1org 2 si' Mrogr ##er%s Gui-e@ "o'u#en(18i+en #e = @b sgui-e1o-(@
" property< just li-e a normal *ariable< has a type that defines which *alues it can record. The preceding 8i+en #e and Ti(+e properties are of the string type.
#ea/ Properties a%d &mitated Properties

)ost of the properties of an object in #pen#ffice.org $asic are defined as such in the '0# description of the ser*ice. &n addition to these NrealN properties< there are also properties in #pen#ffice.org $asic which consist of two methods at the '0# le*el. #ne of these is used to ?uery the *alue of the property and the other is issued to set it :ge( and se( methods;. The property has been *irtually imitated from two methods. haracter objects in '0#< for e9ample< pro*ide the ge(Mosi(ion and se(Mosi(ion methods through which the associated -ey point can be called up and changed. The #pen#ffice.org $asic programmer can access the *alues through the Mosi(ion property. @egardless of this< the original methods are also a*ailable :in our e9ample< ge(Mosi(ion and se(Mosi(ion;.
(ethods
)ethods can be understood as functions that relate directly to an object and through which this object is called. The preceding "o'u#en( object could< for e9ample< pro*ide a S *e method< which can be called as follows:
"o'u#en(1S *e()
)ethods< just li-e functions< may contain parameters and return *alues. The synta9 of such method calls is oriented towards classic functions. The following call also specifies the True parameter for the document object when re?uesting the Sa*e method.
3/ = "o'u#en(1S *e(True)
#nce the method has been completed< S *e sa*es a return *alue in the 3/ *ariable.
-/
7odu,es= !er#ices and (nterfaces
(odu/es5 2er*ices a%d &%terfaces

#pen#ffice.org pro*ides hundreds of ser*ices. To pro*ide an o*er*iew of these ser*ices< they ha*e been combined into modules. The modules are of no other functional importance for #pen#ffice.org $asic programmers. ,hen specifying a ser*ice name< it is only the module name which is of any importance because this must be also listed in the name. The complete name of a ser*ice consists of the 'o#1sun1s( r e9pression< which specifies that it is a #pen#ffice.org ser*ice< followed by the module name< such as )r #e< and finally the actual ser*ice name< such as "es/(op. The complete name in the named e9ample would be:
&n addition to the module and ser*ice terms< '0# introduces the term 4%$ er"aceC. ,hile this term may be familiar to =a*a programmers< it is not used in $asic. "n interface combines se*eral methods. &n the strictest sense of the word< a ser*ice in '0# does not support methods< but rather interfaces< which in turn pro*ide different methods. &n other words< the methods are assigned :as combinations; to the ser*ice in interfaces. This detail may be of interest in particular to =a*aG or EE programmers< since in these languages< the interface is needed to re?uest a method. &n #pen#ffice.org $asic< this is irrele*ant. 7ere< the methods are called directly by means of the rele*ant object. 5or an understanding of the "P&< it is< howe*er< useful to ha*e the assignment of methods to *arious interfaces handy< since many interfaces are used in the different ser*ices. &f you are familiar with an interface< then you can transfer your -nowledge from one ser*ice to another. Some central interfaces are used so fre?uently< triggered by different ser*ices< that they are shown again at the end of this chapter.
!oo/s for -or,i%g +ith 'NO

The ?uestion remains as to which objects A or ser*ices if we are going to remain with '0# terminology A support which properties< methods and interfaces and how these can be determined. &n addition to this guide< you can get more information about objects from the following sources: the suppor(sSer*i'e method< the debug methods as well as the De*eloperCs Duide< and the "P& reference.
!he supports2er*ice (ethod

" number of '0# objects support the suppor(sSer*i'e method< with which you can establish whether an object supports a particular ser*ice. The following call< for e9ample< determines whether the Tex(E+e#en( object supports the com.sun.star.te9t.Paragraph ser*ice.
3/ = Tex(E+e#en(1suppor(sSer*i'e(@'o#1sun1s( r1(ex(1M r gr p&@)
0ebug Properties
6*ery '0# object -nows what properties< methods and interfaces it already contains. #pen#ffice.org $asic pro*ides properties that return these in the form of a string containing a list. The corresponding properties are:
DB+,properties
returns a string containing all properties of an object

DB+,metho%s
returns a string containing all methods of an object

%&apter 4 (ntroduction to t&e AP( -7
'oo,s for )or*ing $it& 9.O
DB+,supporte%Inter!aces
returns a string containing all interfaces which support an object. The following program code shows how "2G_proper(ies and "2G_#e(&o-s can be used in realGlife applications. &t first creates the com.sun.star.frame.Des-top ser*ice and then displays the supported properties and methods in message bo9es.
"i# 3b: $s 3b:e'( 3b: = 're (eNnoSer*i'e(@'o#1sun1s( r1)r #e1"es/(op@) Asg2ox 3b:1"2G_Mroper(ies Asg2ox 3b:1"2G_#e(&o-s
,hen using "2G_proper(ies< note that the function returns all properties that the ser*ices offered by the object can theoretically support. 0o assurances are< howe*er< pro*ided for whether these can also be used by the object in ?uestion. &n *ery rare cases< before calling up some property< use the 6sE#p(. function to chec- whether it is actually a*ailable.
0ebuggi%g too/s
'sing the "2G_ properties is a *ery crude method to disco*er the contents of an "P& objects. The watch window of the $asic &D6 can display the properties of a 'no object :but not the methods< not the interfaces;. To display all information a*ailable from an object and lin- to the corresponding "P& documentation< use instead 5ra( oo# or 6&7 oo#. Note VBA : #pen#ffice.org $asic does $o pro*ide code completion. #nly at runGtime can you find out which properties or methods are a*ailable for an object. "ll the abo*e debug tools wor- on a running program.
P& #efere%ce
)ore information about the a*ailable ser*ices< and their interfaces< methods and properties can be found in the reference for the #pen#ffice.org "P&.
O*er*ie+ of Ce%tra/ &%terfaces

Some interfaces of #pen#ffice.org can be found in many parts of the #pen#ffice.org "P&. They define sets of methods for abstract tas-s which can be applied to *arious problems. 7ere< you will find an o*er*iew of the most common of these interfaces. The origin of the objects is e9plained at a later point in this guide. "t this point< only some of the abstract aspects of objects< for which the #pen#ffice.org "P& pro*ides some central interfaces< are discussed.
Creati%g Co%te1t40epe%de%t Ob8ects

The #pen#ffice.org "P& pro*ides two options for creating objects. #ne can be found in the 're (eNnoSer*i'e function mentioned at the start of this chapter. 're (eNnoSer*i'e creates an object which can be used uni*ersally. Such objects and ser*ices are also -nown as conte9tGindependent ser*ices. &n addition to conte9tGindependent ser*ices< there are also conte9tGdependent ser*ices whose objects are
-0 LibreOffice 3.4 Basic Programmer's Guide !eptember "011
O#er#ie$ of %entra, (nterfaces
only useful when used in conjunction with another object. " drawing object for a spreadsheet document< for e9ample< can therefore only e9ist in conjunction with this one document.
com.su%.star./a%g.;(u/ti2er*ice3actory &%terface
onte9tGdependent objects are usually created by means of an object method< on which the object depends. The 're (e6ns( n'e method< which is defined in the RAu+(iSer*i'e8 '(or. interface< is used in particular in the document objects. The drawing object can< for e9ample< be created as follows using a spreadsheet object:
"i# ,e'( ng+eS& pe $s 3b:e'( ,e'( ng+eS& pe = _ Spre -s&ee(1're (e6ns( n'e(@'o#1sun1s( r1-r 0ing1,e'( ng+eS& pe@)
" paragraph template in a te9t document is created in the same way:

"i# S(.+e s 3b:e'( S(.+e = Tex(-o'u#en(1're (e6ns( n'e(@'o#1sun1s( r1s(.+e1M r gr p&S(.+e@)
Named ccess to 2ubordi%ate Ob8ects

The R5 #e$''ess and R5 #e7on( iner interfaces are used in objects that contain subordinate objects< which can be addressed using a natural language name. ,hile R5 #e-$''ess permits access to the indi*idual objects< R5 #e7on( iner ta-es on the insertion< modification and deletion of elements.
com.su%.star.co%tai%er.;Name ccess &%terface

"n e9ample of the use of R5 #e$''ess is pro*ided by the s&ee(s object of a spreadsheet. &t combines all the pages within the spreadsheet. The indi*idual pages are accessed from the s&ee(s object< by using the ge(2.5 #e method from R5 #e$''ess:
"i# S&ee(s $s 3b:e'( "i# S&ee( $s 3b:e'( S&ee(s = Spre -s&ee(1S&ee(s S&ee( = S&ee(s1ge(2.5 #e(@S&ee(1@)
The ge(E+e#en(5 #es method pro*ides an o*er*iew of the names of all elements. "s a result< it returns a data field containing the names. The following e9ample shows how all element names of a spreadsheet can thereby be determined and displayed in a loop:
"i# S&ee(s $s 3b:e'( "i# S&ee(5 #es "i# 6 $s 6n(eger S&ee(s = Spre -s&ee(1S&ee(s S&ee(5 #es = S&ee(s1ge(E+e#en(5 #es 8or 6=L2oun-(S&ee(5 #es) To N2oun-(S&ee(5 #es) Asg2ox S&ee(5 #es(6) 5ex( 6
The & s2.5 #e method of the R5 #e$''ess interface re*eals whether a subordinate object with a particular name e9ists within the basic object. The following e9ample therefore displays a message that informs the user whether the Spre -s&ee( object contains a page of the name S&ee(1.
"i# S&ee(s $s 3b:e'( S&ee(s = Spre -s&ee(1S&ee(s 6) S&ee(s1B s2.5 #e(@S&ee(1@) T&en Asg2ox @ S&ee(1 * i+ b+e@ E+se Asg2ox @S&ee(1 no( * i+ b+e@ En- 6)
%&apter 4 (ntroduction to t&e AP(
-9
com.su%.star.co%tai%er.;NameCo%tai%er &%terface
The R5 #e7on( iner interface ta-es on the insertion< deletion and modification of subordinate elements in a basic object. The functions responsible are inser(2.5 #e< re#o*e2.5 #e and rep+ 'e2.5 #e. The following is a practical e9ample of this. &t calls a te9t document< which contains a S(.+e8 #i+ies object and uses this to in turn ma-e the paragraph templates :ParagraphStyles; of the document a*ailable.
"i# S(.+e8 #i+ies $s 3b:e'( "i# M r gr p&S(.+es $s 3b:e'( "i# 5e0S(.+e $s 3b:e'( S(.+e8 M r gr M r gr M r gr M r gr #i+ies = Tex(-o'1S(.+e8 #i+ies p&S(.+es = S(.+e8 #i+ies1ge(2.5 #e(@M r gr p&S(.+es@) p&S(.+es1inser(2.5 #e(@5e0S(.+e@< 5e0S(.+e) p&S(.+es1rep+ 'e2.5 #e(@7& ngingS(.+e@< 5e0S(.+e) p&S(.+es1re#o*e2.5 #e(@3+-S(.+e@)
The inser(2.5 #e line inserts the 5e0S(.+e style under the name of the same name in the M r gr p&S(.+es object. The rep+ 'e2.5 #e line changes the object behind 7& ngingS(.+e into 5e0S(.+e. 5inally< the re#o*e2.5 #e call remo*es the object behind 3+-S(.+e from M r gr p&S(.+es.
&%de14Based ccess to 2ubordi%ate Ob8ects

The R6n-ex$''ess and R6n-ex7on( iner interfaces are used in objects which contain subordinate objects and which can be addressed using an inde9.
R6n-ex$''ess pro*ides the methods for accessing indi*idual objects. R6n-ex7on( iner pro*ides methods
for inserting and remo*ing elements.
com.su%.star.co%tai%er.;&%de1 ccess &%terface

R6n-ex$''ess pro*ides the ge(2.6n-ex and ge(7oun( methods for calling the subordinate objects. ge(2.6n-ex pro*ides an object with a particular inde9. ge(7oun( returns how many objects are a*ailable.
"i# S&ee(s $s 3b:e'( "i# S&ee( $s 3b:e'( "i# 6 $s 6n(eger S&ee(s = Spre -s&ee(1S&ee(s 8or 6 = D (o S&ee(s1ge(7oun(() H 1 S&ee( = S&ee(s1ge(2.6n-ex(6) % E-i(ing s&ee( 5ex( 6
The e9ample shows a loop that runs through all sheet elements one after another and sa*es a reference to each in the S&ee( object *ariable. ,hen wor-ing with the inde9es< note that ge(7oun( returns the number of elements. The elements in ge(2.6n-ex howe*er are numbered beginning with 3. The counting *ariable of the loop therefore runs from 3 to ge(7oun(()H1.
com.su%.star.co%tai%er.;&%de1Co%tai%er &%terface
The R6n-ex7on( iner interface pro*ides the inser(2.6n-ex and re#o*e2.6n-ex functions. The parameters are structured in the same way as the corresponding functions in R5 #e7on( iner.
/0
&terati*e ccess to 2ubordi%ate Ob8ects

&n some instances< an object may contain a list of subordinate objects that cannot be addressed by either a name or an inde9. &n these situations< the REnu#er (ion and Renu#er (ion$''ess interfaces are appropriate. They pro*ide a mechanism through which all subordinate elements of an objects can be passed< step by step< without ha*ing to use direct addressing.
com.su%.star.co%tai%er.;"%umeratio% a%d ;e%umeratio% ccess &%terfaces

The basic object must pro*ide the REnu#er (ion$''ess interface< which contains only a 're (eEnu#er (ion method. This returns an au9iliary object< which in turn pro*ides the REnu#er (ion interface with the & sAoreE+e#en(s and nex(E+e#en( methods. Through these< you then ha*e access to the subordinate objects. The following e9ample steps through all the paragraphs of a te9t:
"i# M r gr p&Enu#er (ion $s 3b:e'( "i# M r gr p& $s 3b:e'( M r gr p&Enu#er (ion = Tex(-o'1Tex(1're (eEnu#er (ion C&i+e M r gr p&Enu#er (ion1& sAoreE+e#en(s() M r gr p& = M r gr p&Enu#er (ion1nex(E+e#en(() Cen-
The e9ample first creates a M r gr p&Enu#er (ion au9iliary object. This gradually returns the indi*idual paragraphs of the te9t in a loop. The loop is terminated as soon as the & sAoreE+e#en(s method returns the 8 +se *alue< signaling that the end of the te9t has been reached.
%&apter 4 (ntroduction to t&e AP(
/1
C H
P ! " #
<
%or&ing 'ith (ocuments
The #pen#ffice.org "P& has been structured so that as many of its parts as possible can be used uni*ersally for different tas-s. This includes the interfaces and ser*ices for creating< opening< sa*ing< con*erting< and printing documents and for template administration. Since these function areas are a*ailable in all types of documents< they are e9plained first in this chapter.

The StarDes-top Styles and Templates
!he curre%t docume%t

&n pre*ious *ersions of the $asic Programming Duide these instructions were used to obtain the current document :
"i# "o' $s 3b:e'( "o' = S( r"es/(op17urren(7o#ponen(
This correct code has a drawbac- : it does not wor- if the macro is started from the &D6 because it then refers to the &D6< not the document. This code wor-s only if the macro is started from the document itselfS You should instead use $asic object T&is7o#ponen(. &t returns the document object on which the macro is run. &f you start the macro from the &D6< T&is7o#ponen( will still find and return your document.
"i# "o' $s 3b:e'( "o' = T&is7o#ponen( % re'o##en-e- 'o-ing )or 2 si'
!he 2tar0es,top
,hen wor-ing with documents< two ser*ices are used most fre?uently: The com.sun.star.frame.Des-top ser*ice< which is similar to the core ser*ice of #pen#ffice.org. &t pro*ides the functions for the frame object of #pen#ffice.org< under which all document windows are classified. Documents can also be created< opened and imported using this ser*ice. The basic functionality for the indi*idual document objects is pro*ided by the com.sun.star.document.#fficeDocument ser*ice. This pro*ides the methods for sa*ing< e9porting and printing documents.
The com.sun.star.frame.Des-top ser*ice is created automatically when #pen#ffice.org is started. This ser*ice can be addressed in #pen#ffice.org $asic using the global name S( r"es/(op. The most important interface of the S( r"es/(op is com.sun.star.frame.X omponentLoader. This basically
/3
'&e !tar6es*top
co*ers the +o -7o#ponen(8ro#N,L method< which is responsible for creating< importing< and opening documents. Note / ar2""%ce 5 : The name of the S( r"es/(op object dates bac- to Star#ffice 4< in which all document windows were embedded in one common application called S( r"es/(op. &n the present *ersion of #pen#ffice.org< a *isible S( r"es/(op is no longer used. The name S( r"es/(op was< howe*er< retained for the frame object of #pen#ffice.org because it clearly indicates that this is a basic object for the entire application. The S( r"es/(op object replaces the $pp+i' (ion object of Star#ffice 4 which pre*iously applied as a root object. 7owe*er< unli-e the old $pp+i' (ion object< S( r"es/(op is primarily responsible for opening new documents. The functions resident in the old $pp+i' (ion object for controlling the onGscreen depiction of #pen#ffice.org :for e9ample< 8u++S'reen< 8un'(ion2 r4isib+e< Beig&(< Ci-(&< Top< 4isib+e; are no longer used. Note VBA : ,hereas the acti*e document in ,ord is accessed through $pp+i' (ion1$'(i*e"o'u#en( and in 69cel through $pp+i' (ion1$'(i*eCor/boo/< in #pen#ffice.org< the S( r"es/(op is responsible for this tas-. The acti*e document object is accessed in #pen#ffice.org through the S( r"es/(op17urren(7o#ponen( property< or through T&is7o#ponen(.
!hisCompo%e%t
The global name T&is7o#ponen( generally returns the same object as S( r"es/(op17urren(7o#ponen(< with one significant ad*antage. &f you are running from within the $asic &D6< debugging or e9ploring< then S( r"es/(op returns the $asic &D6 itself. This is probably not what you want. T&is7o#ponen( returns the last pre*iously acti*e document.
Basic &%formatio% about 0ocume%ts i% Ope%Office.org

,hen wor-ing with #pen#ffice.org documents< it is useful to deal with some of the basic issues of document administration in #pen#ffice.org. This includes the way in which file names are structured for #pen#ffice.org documents< as well as the format in which files are sa*ed.
3i/e Names i% '#L Notatio%

Since #pen#ffice.org is a platformGindependent application< it uses '@L notation :which is independent of any operating system;< as defined in the &nternet Standard @5 /%1( for file names. Standard file names using this system begin with the prefi9 )i+e!OOO followed by the local path. &f the file name contains subG directories< then these are separated by a single forward slash< not with a bac-slash usually used under ,indows. The following path references the (es(1o-( file in the doc directory on the : dri*e.
)i+e!OOO7!O-o'O(es(1o-(
To con*ert local file names into an '@L< #pen#ffice.org pro*ides the 7on*er(ToNr+ function. To con*ert a '@L into a local file name< #pen#ffice.org pro*ides the 7on*er(8ro#Nr+ function:
Asg2ox 7on*er(ToNr+(@7!P-o'P(es(1o-(@) % supp+ies )i+e!OOO7!O-o'O(es(1o-( Asg2ox 7on*er(8ro#Nr+(@)i+e!OOO7!O-o'O(es(1o-(@) % supp+ies (un-er Cin-o0s) '!P-o'P(es(1o-(
The e9ample con*erts a local file name into a '@L and displays it in a message bo9. &t then con*erts a '@L into a local file name and also displays this. The &nternet Standard @5 /%1(< upon which this is based< permits use of the DHL< HX< and $H^ characters. "ll other characters are inserted as escape coding in the '@Ls. To do this< they are con*erted into their he9adecimal *alue in the 'T5G( set of characters and are preceded by a percent sign. " space in a local file name therefore< for e9ample< becomes a E2D in the '@L.
/4
'&e !tar6es*top
;(L 3i/e 3ormat

#pen#ffice.org documents are based on the X)L file format. X)LGbased files can be opened and edited with other programs.
Compressio% of 3i/es
Since X)L is based on standard te9t files< the resultant files are usually *ery large. #pen#ffice.org therefore compresses the files and sa*es them as a Y&P file. $y means of a s(ore$sN,L method option< the user can sa*e the original X)L files directly. See store"s'@L )ethod #ptions< below.
Creati%g5 Ope%i%g a%d &mporti%g 0ocume%ts

Documents are opened< imported and created using the method StarDes-top.load omponent5rom'@L:'@L< 5rame< Search5lags< 5ileProperties; The first parameter of +o -7o#ponen(8ro#N,L specifies the '@L of the associated file. "s the second parameter< +o -7o#ponen(8ro#N,L e9pects a name for the frame object of the window that #pen#ffice.org creates internally for its administration. The predefined _b+ n/ name is usually specified here< and this ensures that #pen#ffice.org creates a new window. 'sing these parameters< the user can open a #pen#ffice.org document< since place holders :dummy *alues; can be assigned to the last two parameters:
"i# "o' $s 3b:e'( "i# Nr+ $s S(ring "i# "u##.() %$n (e#p(.) rr . o) Mroper(.4 +ues
Nr+ = @)i+e!OOO7!O(es(1o-(@ "o' = S( r"es/(op1+o -7o#ponen(8ro#N,L(Nr+< @_b+ n/@< D< "u##.)
The preceding call opens the (es(1o-( file and displays this in a new window. "ny number of documents can be opened in this way in #pen#ffice.org $asic and then edited using the returned document objects. Note / ar2""%ce 5 : S( r"es/(op1+o -7o#ponen(8ro#N,L supersedes the "o'u#en(s1$-- and "o'u#en(s13pen methods from the old #pen#ffice.org "P&.
#ep/aci%g the Co%te%t of the 0ocume%t -i%do+

The named _b+ n/ *alue for the 8r #e parameter ensures that #pen#ffice.org creates a new window for e*ery call from +o -7o#ponen(8ro#N,L. &n some situations< it is useful to replace the content of an e9isting window. &n this case< the frame object of the window should contain an e9plicit name. 0ote that this name must not begin with an underscore. 5urthermore< the Se r'&8+ gs parameter must be set so that the corresponding framewor- is created< if it does not already e9ist. The corresponding constant for Se r'&8+ gs is:
Se r'&8+ gs = 'o#1sun1s( r1)r #e18r #eSe r'&8+ g17,E$TE + _ 'o#1sun1s( r1)r #e18r #eSe r'&8+ g1$LL
The following e9ample shows how the content of an opened window can be replaced with the help of the frame parameter and Se r'&8+ gs:
"i# "i# "i# "i# "o' $s 3b:e'( "u##.() Nr+ $s S(ring Se r'&8+ gs $s Long
Se r'&8+ gs = 'o#1sun1s( r1)r #e18r #eSe r'&8+ g17,E$TE + _ 'o#1sun1s( r1)r #e18r #eSe r'&8+ g1$LL
%&apter - )or*ing $it& 6ocuments
/-
'&e !tar6es*top
Nr+ = @)i+e!OOO7!O(es(1o-(@ "o' = S( r"es/(op1+o -7o#ponen(8ro#N,L(Nr+< @A.8r #e@< Se r'&8+ gs< "u##.) Asg2ox @Mress 3V (o -isp+ . (&e se'on- -o'u#en(1@ Nr+ = @)i+e!OOO7!O(es(21o-(@ "o' = S( r"es/(op1+o -7o#ponen(8ro#N,L(Nr+< @A.8r #e@< _ Se r'&8+ gs< "u##.)
The e9ample first opens the (es(1o-( file in a new window with the frame name of A.8r #e. #nce the message bo9 has been confirmed< it replaces the content of the window with the (es(21o-( file.
/oadCompo%e%t3rom'#L (ethod Optio%s

The fourth parameter of the +o -7o#ponen(8ro#N,L function is a Mroper(.4 +ue data field. which pro*ides #pen#ffice.org with *arious options for opening and creating documents. The data field must pro*ide a Mroper(.4 +ue structure for each option in which the name of the option is sa*ed as a string as well as the associated *alue.
+o -7o#ponen(8ro#N,L supports the following options: As)emplate (Boolean)
if true< loads a new< untitled document from the gi*en '@L. &f is false< template files are loaded for editing.
CharacterSet (String)
defines which set of characters a document is based on.

-ilterName (String)
specifies a special filter for the +o -7o#ponen(8ro#N,L function. The filter names a*ailable are defined in the Ps& reP'on)igPregis(r.Pins( n'ePorgPopeno))i'ePo))i'ePT.pe"e(e'(ion1x#+ file.
-ilterData (String)
defines additional options for filters.

-ilter.ptions (String)
defines additional options :used by old filters;.

(i%%en (Boolean)
*alue true loads the document in in*isible mode.

/ump"ar' (String)
once a document has been opened< jumps to the position defined in =ump)ar-.
"acro01ecution"o%e (Integer)
indicates if document macros may be e9ecuted. .alues : see com.sun.star.document.)acro69ec)ode

2ass*or% (String)
transfers a password for a protected file.

$ea%.nl (Boolean)
*alue true loads a document in readGonly mode.

Up%ateDoc"o%e (Integer)
indicates how/if lin-s will be updated. .alues : see com.sun.star.document.'pdateDoc)ode The following e9ample shows how a te9t file separated by a comma in #pen#ffice.org alc can be opened using the 8i+(er5 #e option.
"i# "o' $s 3b:e'( "i# 8i+eMroper(ies(1) $s 5e0 'o#1sun1s( r1be ns1Mroper(.4 +ue "i# Nr+ $s S(ring Nr+ = @)i+e!OOO7!O-o'1's*@
//
'&e !tar6es*top
8i+eMroper(ies(D)15 8i+eMroper(ies(D)14 8i+eMroper(ies(1)15 8i+eMroper(ies(1)1*
#e = @8i+(er5 #e@ +ue =@Tex( H (x( H 's* (S( r7 +')@ #e = @8i+(er3p(ions@ +ue = @44<34<D<1@
"o' = S( r"es/(op1+o -7o#ponen(8ro#N,L(Nr+< @_b+ n/@< D< 8i+eMroper(ies())
The 8i+eMroper(ies array has two elements< one for each option used. The 8i+(ern #e property defines whether #pen#ffice.org uses a #pen#ffice.org alc te9t filter to open files. The 8i+(er3p(ions property contains the description of the synta9 of the cs* file.
Creati%g Ne+ 0ocume%ts

#pen#ffice.org automatically creates a new document if the document specified in the '@L is a template. "lternati*ely< if only an empty document without any adaptation is needed< a pri* (e!) '(or. '@L can be specified:
"i# "u##.() "i# Nr+ $s S(ring "i# "o' $s 3b:e'( Nr+ = @pri* (e!) '(or.Os0ri(er@ "o' = S( r"es/(op1+o -7o#ponen(8ro#N,L(Nr+< @_b+ n/@< D< "u##.())
The call creates an empty #pen#ffice.org writer document.
0ocume%t Ob8ects
The +o -7o#ponen(8ro#N,L function introduced in the pre*ious section returns a document object. This supports the com.sun.star.document.#fficeDocument ser*ice< which in turn pro*ides two central interfaces:

The com.sun.star.frame.XStorable interface< which is responsible for sa*ing documents. The com.sun.star.*iew.XPrintable interface< which contains the methods for printing documents.
2a*i%g a%d "1porti%g 0ocume%ts

#pen#ffice.org documents are sa*ed directly through the document object. The s(ore method of the com.sun.star.frame.XStorable interface is a*ailable for this purpose:
"o'1s(ore()
This call functions pro*ided that the document has already been assigned a memory space. This is not the case for new documents. &n this instance< the s(ore$sN,L method is used. This method is also defined in com.sun.star.frame.XStorable and can be used to define the location of the document:
"i# N,L $s S(ring "i# "u##.() Nr+ = @)i+e!OOO7!O(es(31o-(@ "o'1s(ore$sN,L(N,L< "u##.())
&n addition to the preceding methods< com.sun.star.frame.XStorable also pro*ides some help methods which are useful when sa*ing documents. These are:
hasLocation()
specifies whether the document has already been assigned a '@L.

is$ea%onl ()
specifies whether a document has readGonly protection.

is"o%i!ie%()
specifies whether a document has been modified since it was last sa*ed.
/7
'&e !tar6es*top
The code for sa*ing a document can be e9tended by these options so that the document is only sa*ed if the object has actually been modified and the file name is only ?ueried if it is actually needed:
6) ("o'1isAo-i)ie-) T&en 6) ("o'1& sLo' (ion $n- (5o( "o'1is,e -3n+.)) T&en "o'1s(ore() E+se "o'1s(ore$sN,L(N,L< "u##.()) En- 6) En- 6)
The e9ample first chec-s whether the rele*ant document has been modified since it was last sa*ed. &t only continues with the sa*ing process if this is the case. &f the document has already been assigned a '@L and is not a readGonly document< it is sa*ed under the e9isting '@L. &f it does not ha*e a '@L or was opened in its readGonly status< it is sa*ed under a new '@L.
store s'#L (ethod Optio%s

"s with the +o -7o#ponen(8ro#N,L method< some options can also be specified in the form of a Mroper(.4 +ue data field using the s(ore$sN,L method. These determine the procedure #pen#ffice.org uses when sa*ing a document. s(ore$sN,L pro*ides the following options:
CharacterSet (String)
defines which set of characters a document is based on.

-ilterName (String)
specifies a special filter for the +o -7o#ponen(8ro#N,L function. The filter names a*ailable are defined in the Ps& reP'on)igPregis(r.Pins( n'ePorgPopeno))i'ePo))i'ePT.pe"e(e'(ion1x#+ file.
-ilterData (String)
defines additional options for filters.

-ilter.ptions (String)
defines additional options :used by old filters;.

.3er*rite (Boolean)
allows a file which already e9ists to be o*erwritten without a ?uery.

2ass*or% (String)
transfers the password for a protected file.

Unpac'e% (Boolean)
sa*es the document :not compressed; in subGdirectories. The possibility to store documents in unpac-ed way is not currently supported< the N'npac-edN property is just ignored< see &ssue 28128 . The following e9ample shows how the 3*er0ri(e option can be used in conjunction with s(ore$sN,L:
"i# "o' $s 3b:e'( "i# 8i+eMroper(ies(D) $s 5e0 'o#1sun1s( r1be ns1Mroper(.4 +ue "i# Nr+ $s S(ring % 111 6ni(i +iXe "o' Nr+ = @)i+e!OOO'!O(es(31o-(@ 8i+eMroper(ies(D)15 #e = @3*er0ri(e@ 8i+eMroper(ies(D)14 +ue = True "o'1s(ore$sN,L(Nr+< 8i+eMroper(ies())
The e9ample then sa*es "o' under the specified file name if a file already e9ists under the name.
/0
'&e !tar6es*top
Pri%ti%g 0ocume%ts
Similar to sa*ing< documents are printed out directly by means of the document object. The Mrin( method of the com.sun.star.*iew.Xprintable interface is pro*ided for this purpose. &n its simplest form< the print call is:
"i# "u##.() "o'1prin(("u##.())
"s in the case of the +o -7o#ponen(8ro#N,L method< the Dummy parameter is a Mroper(.4 +ue data field through which #pen#ffice.org can specify se*eral options for printing.
!he optio%s of the pri%t method

The prin( method e9pects a Mroper(.4 +ue data field as a parameter< which reflects the settings of the print dialog of #pen#ffice.org:
Cop Count (Integer)
specifies the number of copies to be printed.

-ileName (String)
prints the document in the specified file.

Collate (Boolean)
ad*ises the printer to collate the pages of the copies.

Sort (Boolean)
sorts the pages when printing out se*eral copies :7op.7oun( Z /;.
2ages (String)
contains the list of the pages to be printed :synta9 as specified in print dialog;.
Wait (Boolean)
if set to True the print method will return after the job is stored on the waiting list for the printer. 'se this option if you want to close the document after print. The following e9ample shows how se*eral pages of a document can be printed out using the M ges option:
"i# "o' $s 3b:e'( "i# Mrin(Mroper(ies(1) $s 5e0 'o#1sun1s( r1be ns1Mroper(.4 +ue Mrin(Mroper(ies(D)15 #e=@M ges@ Mrin(Mroper(ies(D)14 +ue=@1H3_ 7_ L@ Mrin(Mroper(ies(1)15 #e=@C i(@ Mrin(Mroper(ies(1)14 +ue=True "o'1prin((Mrin(Mroper(ies())
Pri%ter se/ectio% a%d setti%gs

The com.sun.star.*iew.XPrintable interface pro*ides the Mrin(er property< which selects the printer. This property recei*es a Mroper(.4 +ue data field with the following settings:
Name (String)
specifies the name of printer.

2aper.rientation (0num)
specifies the paper orientation :com.sun.star.*iew.Paper#rientation.P#@T@"&T *alue for portrait format< com.sun.star.*iew.Paper#rientation.L"0DS "P6 for landscape format;.
2aper-ormat (0num)
specifies the paper format :for e9ample< com.sun.star.*iew.Paper5ormat."8 for D&0 "8 or com.sun.star.*iew.Paper5ormat.Letter for 'S letters;.
/9
'&e !tar6es*top
2aperSi4e (Si4e)
specifies the paper siBe in hundredths of a millimeter. The following e9ample shows how a printer can be changed and the paper siBe set with the help of the Mrin(er property.
"i# "o' $s 3b:e'( "i# Mrin(erMroper(ies(1) $s 5e0 'o#1sun1s( r1be ns1Mroper(.4 +ue "i# M perSiXe $s 5e0 'o#1sun1s( r1 0(1SiXe M perSiXe1Ci-(& = 2DDDD % 'orrespon-s (o 2D '# M perSiXe1Beig&( = 2DDDD % 'orrespon-s (o 2D '# Mrin(erMroper(ies (D)15 #e=@5 #e@ Mrin(erMroper(ies (D)14 +ue=@A. BM L ser:e(@ Mrin(erMroper(ies (1)15 #e=@M perSiXe@ Mrin(erMroper(ies (1)14 +ue=M perSiXe "o'1Mrin(er = Mrin(erMroper(ies()
The e9ample defines an object named M perSiXe with the com.sun.star.awt.SiBe type. This is needed to specify the paper siBe. 5urthermore< it creates a data field for two Mroper(.4 +ue entries named Mrin(erMroper(ies. This data field is then initialiBed with the *alues to be set and assigned the Mrin(er property. 5rom the standpoint of '0#< the printer is not a real property but an imitated one.
2ty/es a%d !emp/ates

2ty/es
Styles are named lists containing formatting attributes. They wor- in all applications of #pen#ffice.org and help to significantly simplify formatting. &f the user changes one of the attributes of a style< then #pen#ffice.org automatically adjusts all document sections depending on the attribute. The user can therefore< for e9ample< change the font type of all le*el one headers by means of a central modification in the document.
2ty/e !ypes
Depending on the rele*ant document types< #pen#ffice.org recogniBes a whole range of different types of styles. #pen#ffice.org ,riter supports the following types of styles:

haracter styles Paragraph styles 5rame styles Page styles 0umbering styles
#pen#ffice.org alc supports the following types of styles:

ell styles Page styles haracter element styles Presentation styles
#pen#ffice.org &mpress supports the following types of styles:

&n #pen#ffice.org terminology< the different types of styles are called S(.+e8 #i+ies in accordance with the com.sun.star.style.Style5amily ser*ice on which they are based. The S(.+e8 #i+ies are accessed by means of the document object:
70
!t1,es and 'emp,ates
"i# "i# "i# "i#
"o' $s 3b:e'( S&ee( $s 3b:e'( S(.+e8 #i+ies $s 3b:e'( 7e++S(.+es $s 3b:e'(
"o' = T&is7o#ponen( S(.+e8 #i+ies = "o'1S(.+e8 #i+ies 7e++S(.+es = S(.+e8 #i+ies1ge(2.5 #e(@7e++S(.+es@)
The e9ample uses the S(.+e8 #i+ies property of a spreadsheet document to establish a list containing all a*ailable cell styles. The indi*idual styles can be accessed directly by means of an inde9:
"i# "i# "i# "i# "i# "i# "o' $s 3b:e'( S&ee( $s 3b:e'( S(.+e8 #i+ies $s 3b:e'( 7e++S(.+es $s 3b:e'( 7e++S(.+e $s 3b:e'( 6 $s 6n(eger
"o' = T&is7o#ponen( S(.+e8 #i+ies = "o'1S(.+e8 #i+ies 7e++S(.+es = S(.+e8 #i+ies1ge(2.5 #e(@7e++S(.+es@) 8or 6 = D To 7e++S(.+es17oun( H 1 7e++S(.+e = 7e++S(.+es(6) Asg2ox 7e++S(.+e15 #e 5ex( 6
The loop added since the pre*ious e9ample displays the names of all cell styles one after another in a message bo9. Note The reference 7e++S(.+es(6) corresponds to the method ge(2.6n-ex()< which is optional for these style container objects. &t may not be a*ailable in all types of documents. The method ge(2.5 #e() is mandatory< and should always be a*ailable.
0etai/s about *arious formatti%g optio%s

6ach type of style pro*ides a whole range of indi*idual formatting properties. 7ere is an o*er*iew of the most important formatting properties and the points at which they are e9plained:

haracter properties< com.sun.star.style. haracterProperties ser*ice Paragraph properties< com.sun.star.te9t.Paragraph ser*ice ell properties< com.sun.star.table. ellProperties ser*ice Page properties< com.sun.star.style.PageProperties ser*ice haracter element properties< .arious ser*ices
The format properties are by no means restricted to the applications in which these are e9plained< but instead can be used uni*ersally. 5or e9ample< most of the page properties described in Spreadsheets can therefore be used not only in #pen#ffice.org alc< but also in #pen#ffice.org ,riter. )ore information about wor-ing with styles can be found in the 8e"a!# 'a#!es "or c)arac er a$d paragrap) proper %es section in Te9t Documents.
!emp/ates
Templates are au9iliary documents. They pro*ide a *ery con*enient way to store< maintain< and distribute styles< macros< boilerGplate te9t< and other useful things.
0ocume%t a%d !emp/ate !ypes

6ach major type of #pen#ffice.org document has its own associated template type. &n general< and for
71
!t1,es and 'emp,ates
styles in particular< you can access information within a template in the same way you would access the same information in the associated document type. &n other words< code :li-e the abo*e e9amples; that wor-s in a particular document type should also wor- for the associated template type.
utomatic 'pdate
)ost template types F Draw templates are the e9ception F ha*e an automaticGupdate feature. &f a style in the template has been changed< and you open a document created with that template< you will see a message as-ing whether to update the styles in the document. &f you clic- on 9es< the new or changed styles will be copied into the document. Styles deleted from the template are not remo*ed from documents. " problem may arise if you clic- on 1o: the styles will not be updated< and the automaticGupdate feature will be turned off. "s of #pen#ffice.org .ersion 1./< this status does not show in the D'&< nor is there any D'& way to reGenable the feature. :5or ,riter documents only< you can use the Template hanger e9tension to set this feature again.; The following subroutine< adapted from the Template hanger e9tension< will reGenable the update feature for all document types.
Sub 8ixNp- (e "i# o"o'Se((ings s 3b:e'( o"o'Se((ings = T&is7o#ponen(1're (e6ns( n'e( @'o#1sun1s( r1-o'u#en(1Se((ings@ ) o"o'Se((ings1Np- (e8ro#Te#p+ (e = True En- Sub %8ixNp- (e
7"
C H
P ! " #
Te*t (ocuments
&n addition to pure strings< te9t documents also contain formatting information. These may appear at any point in the te9t. The structure is further complicated by tables. These include not only singleGdimensional strings< but also twoGdimensional fields. )ost word processing programs now finally pro*ide the option of placing drawing objects< te9t frames and other objects within a te9t. These may be outside the flow of te9t and can be positioned anywhere on the page. This chapter presents the central interfaces and ser*ices of te9t documents.

The Structure of Te9t Documents 6diting Te9t Documents )ore than =ust Te9t
The first section deals with the anatomy of te9t documents and concentrates on how a #pen#ffice.org $asic program can be used to ta-e iterati*e steps through a #pen#ffice.org document. &t focuses on paragraphs< paragraph portions and their formatting. The second section focuses on efficiently wor-ing with te9t documents. 5or this purpose< #pen#ffice.org pro*ides se*eral help objects< such as the Tex(7ursor object< which e9tend beyond those specified in the first section. The third section mo*es beyond wor- with te9ts. &t concentrates on tables< te9t frames< te9t fields< boo-mar-s< content directories and more. &nformation about how to create< open< sa*e and print documents is described in ,or-ing with Documents< because it can be used not only for te9t documents< but also for other types of documents.
!he 2tructure of !e1t 0ocume%ts

" te9t document can essentially contain four types of information:

The actual te9t Templates for formatting characters< paragraphs< and pages 0onGte9t elements such as tables< graphics and drawing objects Dlobal settings for the te9t document
This section concentrates on the te9t and associated formatting options.
73
'&e !tructure of 'e8t 6ocuments
Paragraphs a%d Paragraph Portio%s

The core of a te9t document consists of a se?uence of paragraphs. These are neither named nor inde9ed and there is therefore no possible way of directly accessing indi*idual paragraphs. The paragraphs can howe*er be se?uentially tra*ersed with the help of the Enu#er (ion object described in &ntroduction to the "P&. This allows the paragraphs to be edited. ,hen wor-ing with the Enu#er (ion object< one special scenario should< howe*er< be noted: it not only returns paragraphs< but also tables :strictly spea-ing< in #pen#ffice.org ,riter< a table is a special type of paragraph;. $efore accessing a returned object< you should therefore chec- whether the returned object supports the com.sun.star.te9t.Paragraph ser*ice for paragraphs or the com.sun.star.te9t.Te9tTable ser*ice for tables. The following e9ample tra*erses the contents of a te9t document in a loop and uses a message in each instance to inform the user whether the object in ?uestion is a paragraph or table.
"i# "o' $s 3b:e'( "i# Enu# $s 3b:e'( "i# Tex(E+e#en( $s 3b:e'( % 7re (e -o'u#en( ob:e'( "o' = T&is7o#ponen( % 7re (e enu#er (ion ob:e'( Enu# = "o'1Tex(1're (eEnu#er (ion % +oop o*er ++ (ex( e+e#en(s C&i+e Enu#1& sAoreE+e#en(s Tex(E+e#en( = Enu#1nex(E+e#en( 6) Tex(E+e#en(1suppor(sSer*i'e(@'o#1sun1s( r1(ex(1Tex(T b+e@) T&en Asg2ox @T&e 'urren( b+o'/ 'on( ins ( b+e1@ En- 6) 6) Tex(E+e#en(1suppor(sSer*i'e(@'o#1sun1s( r1(ex(1M r gr p&@) T&en Asg2ox @T&e 'urren( b+o'/ 'on( ins p r gr p&1@ En- 6) Cen-
The e9ample creates a "o' document object which references the current #pen#ffice.org document. ,ith the aid of "o'< the e9ample then creates an Enu#er (ion object that tra*erses through the indi*idual parts of the te9t :paragraphs and tables; and assigns the current element to Tex(E+e#en( object. The e9ample uses the suppor(sSer*i'e method to chec- whether the Tex(E+e#en( is a paragraph or a table.
Paragraphs
The com.sun.star.te9t.Paragraph ser*ice grants access to the content of a paragraph. The te9t in the paragraph can be retrie*ed and modified using the String property:
"i# "o' $s 3b:e'( "i# Enu# $s 3b:e'( "i# Tex(E+e#en( $s 3b:e'( "o' = T&is7o#ponen( Enu# = "o'1Tex(1're (eEnu#er (ion C&i+e Enu#1& sAoreE+e#en(s Tex(E+e#en( = Enu#1nex(E+e#en( 6) Tex(E+e#en(1suppor(sSer*i'e(@'o#1sun1s( r1(ex(1M r gr p&@) T&en Tex(E+e#en(1S(ring = ,ep+ 'e(Tex(E+e#en(1S(ring< @.ou@< @N@) Tex(E+e#en(1S(ring = ,ep+ 'e(Tex(E+e#en(1S(ring< @(oo@< @2@) Tex(E+e#en(1S(ring = ,ep+ 'e(Tex(E+e#en(1S(ring< @)or@< @4@) En- 6) Cen-
The e9ample opens the current te9t document and passes through it with the help of the 6numeration object. &t uses the Tex(E+e#en(1S(ring property in all paragraphs to access the rele*ant paragraphs and replaces the .ou< (oo n- )or strings with the N< 2 n- 4 characters. The ,ep+ 'e function used for replacing
74 LibreOffice 3.4 Basic Programmer's Guide !eptember "011
does not fall within the standard linguistic scope of #pen#ffice.org $asic. This is an instance of the e9ample function described in Search and @eplace. Note VBA : The content of the procedure described here for accessing the paragraphs of a te9t is comparable with the Paragraphs listing used in .$"< which is pro*ided in the , nge and "o'u#en( objects a*ailable there. ,hereas in .$" the paragraphs are accessed by their number :for e9ample< by the M r gr p&(1) call;< in #pen#ffice.org $asic< the Enu#er (ion object described pre*iously should be used. There is no direct counterpart in #pen#ffice.org $asic for the 7& r '(ers< Sen(en'es and Cor-s lists pro*ided in .$". You do< howe*er< ha*e the option of switching to a Tex(7ursor which allows for na*igation at the le*el of characters< sentences and words.
Paragraph Portio%s
The pre*ious e9ample may change the te9t as re?uested< but it may sometimes also destroy the formatting. This is because a paragraph in turn consists of indi*idual subGobjects. 6ach of these subGobjects contains its own formatting information. &f the center of a paragraph< for e9ample< contains a word printed in bold< then it will be represented in #pen#ffice.org by three paragraph portions: the portion before the bold type< then the word in bold< and finally the portion after the bold type< which is again depicted as normal. &f the te9t of the paragraph is now changed using the paragraphCs S(ring property< then #pen#ffice.org first deletes the old paragraph portions and inserts a new paragraph portion. The formatting of the pre*ious sections is then lost. To pre*ent this effect< the user can access the associated paragraph portions rather than the entire paragraph. Paragraphs pro*ide their own Enu#er (ion object for this purpose. The following e9ample shows a double loop which passes o*er all paragraphs of a te9t document and the paragraph portions they contain and applies the replacement processes from the pre*ious e9ample:
"i# "i# "i# "i# "i# "o' $s 3b:e'( Enu#1 $s 3b:e'( Enu#2 $s 3b:e'( Tex(E+e#en( $s 3b:e'( Tex(Mor(ion $s 3b:e'(
"o' = T&is7o#ponen( Enu#1 = "o'1Tex(1're (eEnu#er (ion % +oop o*er ++ p r gr p&s C&i+e Enu#11& sAoreE+e#en(s Tex(E+e#en( = Enu#11nex(E+e#en( 6) Tex(E+e#en(1suppor(sSer*i'e(@'o#1sun1s( r1(ex(1M r gr p&@) T&en Enu#2 = Tex(E+e#en(1're (eEnu#er (ion % +oop o*er ++ subHp r gr p&s C&i+e Enu#21& sAoreE+e#en(s Tex(Mor(ion = Enu#21nex(E+e#en( Asg2ox @%@ G Tex(Mor(ion1S(ring G @%@ Tex(Mor(ion1S(ring = ,ep+ 'e(Tex(Mor(ion1S(ring< @.ou@< @N@) Tex(Mor(ion1S(ring = ,ep+ 'e(Tex(Mor(ion1S(ring< @(oo@< @2@) Tex(Mor(ion1S(ring = ,ep+ 'e(Tex(Mor(ion1S(ring< @)or@< @4@) CenEn- 6) Cen-
The e9ample runs through a te9t document in a double loop. The outer loop refers to the paragraphs of the te9t. The inner loop processes the paragraph portions in these paragraphs. The e9ample code modifies the content in each of these paragraph portions using the S(ring property of the string. as is the case in the pre*ious e9ample for paragraphs. Since howe*er< the paragraph portions are edited directly< their formatting information is retained when replacing the string.
%&apter / 'e8t 6ocuments
7-
3ormatti%g
There are *arious ways of formatting te9t. The easiest way is to assign the format properties directly to the te9t se?uence. This is called direct formatting. Direct formatting is used in particular with short documents because the formats can be assigned by the user with the mouse. You can< for e9ample< highlight a certain word within a te9t using bold type or center a line. &n addition to direct formatting< you can also format te9t using templates. This is called indirect formatting. ,ith indirect formatting< the user assigns a preGdefined template to the rele*ant te9t portion. &f the layout of the te9t is changed at a later date< the user only needs to change the template. #pen#ffice.org then changes the way in which all te9t portions which use this template are depicted. Note VBA : &n .$"< the formatting properties of an object are usually spread o*er a range of subG objects :for e9ample< , nge18on(< , nge12or-ers< , nge1S& -ing< , nge1M r gr p&8or# (;. The properties are accessed by means of cascading e9pressions :for e9ample< , nge18on(1$++7 ps;. &n #pen#ffice.org $asic< the formatting properties on the other hand are a*ailable directly< using the rele*ant objects :Tex(7ursor< M r gr p&< and so on;. You will find an o*er*iew of the character and paragraph properties a*ailable in #pen#ffice.org in the following two sections. Note The formatting properties can be found in each object :M r gr p&< Tex(7ursor< and so on; and can be applied directly.
Character Properties
Those format properties that refer to indi*idual characters are described as character properties. These include bold type and the font type. #bjects that allow character properties to be set ha*e to support the com.sun.star.style. haracterProperties ser*ice. #pen#ffice.org recogniBes a whole range of ser*ices that support this ser*ice. These include the pre*iously described com.sun.star.te9t.Paragraph ser*ices for paragraphs as well as the com.sun.star.te9t.Te9tPortion ser*ices for paragraph portions. The com.sun.star.style. haracterProperties ser*ice does not pro*ide any interfaces< but instead offers a range of properties through which character properties can be defined and called. " complete list of all character properties can be found in the #pen#ffice.org "P& reference. The following list describes the most important properties:
Char-ontName (String)
name of font type selected.

CharColor (Long)
te9t color.
Char(eight (-loat)
character height in points :pt;.

CharUn%erline (Constant group)
type of underscore :constants in accordance with com.sun.star.awt.5ont'nderline;.

CharWeight (Constant group)
font weight :constants in accordance with com.sun.star.awt.5ont,eight;.

CharBac'Color (Long)
bac-ground color.
Char5eep)ogether (Boolean)
suppression of automatic line brea-.
7/
CharSt leName (String)
name of character template.
Paragraph Properties
5ormatting information that does not refer to indi*idual characters< but to the entire paragraph is considered to be a paragraph property. This includes the distance of the paragraph from the edge of the page as well as line spacing. The paragraph properties are a*ailable through the com.sun.star.style.ParagraphProperties ser*ice. 6*en the paragraph properties are a*ailable in *arious objects. "ll objects that support the com.sun.star.te9t.Paragraph ser*ice also pro*ide support for the paragraph properties in com.sun.star.style.ParagraphProperties. " complete list of the paragraph properties can be found in the #pen#ffice.org "P& reference. The most common paragraph properties are:
2araA%6ust (enum)
*ertical te9t orientation :constants in accordance with com.sun.star.style.Paragraph"djust;.

2araLineSpacing (struct)
line spacing :structure in accordance with com.sun.star.style.LineSpacing;.

2araBac'Color (Long)
bac-ground color.
2araLe!t"argin (Long)
left margin in /33ths of a millimeter.

2ara$ight"argin (Long)
right margin in /33ths of a millimeter.

2ara)op"argin (Long)
top margin in /33ths of a millimeter.

2araBottom"argin (Long)
bottom margin in /33ths of a millimeter.

2ara)abStops (Arra o! struct)
type and position of tabs :array with structures of the type com.sun.star.style.TabStop;.
2araSt leName (String)
name of the paragraph template.
"1amp/e6 simp/e H!(L e1port

The following e9ample demonstrates how to wor- with formatting information. &t iterates through a te9t document and creates a simple 7T)L file. 6ach paragraph is recorded in its own 7T)L element TMU for this purpose. Paragraph portions displayed in bold type are mar-ed using a T2U 7T)L element when e9porting.
"i# "i# "i# "i# 8i+e5o $s 6n(eger< 8i+en #e $s S(ring< 7urLine $s S(ring "o' $s 3b:e'( Enu#1 $s 3b:e'(< Enu#2 $s 3b:e'( Tex(E+e#en( $s 3b:e'(< Tex(Mor(ion $s 3b:e'(
8i+en #e = @'!P(ex(1&(#+@ 8i+e5o = 8ree)i+e 3pen 8i+en #e 8or 3u(pu( $s J8i+e5o Mrin( J8i+e5o< @TBTALUT23"ZU@
77
"o' = T&is7o#ponen( Enu#1 = "o'1Tex(1're (eEnu#er (ion % +oop o*er ++ p r gr p&s C&i+e Enu#11& sAoreE+e#en(s Tex(E+e#en( = Enu#11nex(E+e#en( 6) Tex(E+e#en(1suppor(sSer*i'e(@'o#1sun1s( r1(ex(1M r gr p&@) T&en Enu#2 = Tex(E+e#en(1're (eEnu#er (ion 7urLine = @TMU@ % +oop o*er ++ p r gr p& por(ions C&i+e Enu#21& sAoreE+e#en(s Tex(Mor(ion = Enu#21nex(E+e#en( 6) Tex(Mor(ion17& rCeig&( = 'o#1sun1s( r1 0(18on(Ceig&(123L" TBE5 7urLine = 7urLine G @T2U@ G Tex(Mor(ion1S(ring G @TO2U@ E+se 7urLine = 7urLine G Tex(Mor(ion1S(ring En- 6) Cen% ou(pu( (&e +ine 7urLine = 7urLine G @TOMU@ Mrin( J8i+e5o< 7urLine En- 6) Cen% 0ri(e BTAL )oo(er Mrin( J8i+e5o< @TO23"ZUTOBTALU@ 7+ose J8i+e5o
The basic structure of the e9ample is oriented towards the e9amples for running though the paragraph portions of a te9t already discussed pre*iously. The functions for writing the 7T)L file< as well as a test code that chec-s the font weight of the corresponding te9t portions and pro*ides paragraph portions in bold type with a corresponding 7T)L tag< ha*e been added.
0efau/t *a/ues for character a%d paragraph properties

8%rec formatting always ta-es priority o*er %$d%rec formatting. &n other words< formatting using templates is assigned a lower priority than direct formatting in a te9t. 6stablishing whether a section of a document has been directly or indirectly formatted is not easy. The symbol bars pro*ided by #pen#ffice.org show the common te9t properties such as font type< weight and siBe. 7owe*er< whether the corresponding settings are based on template or direct formatting in the te9t is still unclear. #pen#ffice.org $asic pro*ides the ge(Mroper(.S( (e method< with which programmers can chec- how a certain property was formatted. "s a parameter< this ta-es the name of the property and returns a constant that pro*ides information about the origin of the formatting. The following responses< which are defined in the com.sun.star.beans.PropertyState enumeration< are possible:
com.sun.star.beans.2ropert State.DI$0C),VALU0
the property is defined directly in the te9t :direct formatting;

com.sun.star.beans.2ropert State.D0-AUL),VALU0
the property is defined by a template :indirect formatting;

com.sun.star.beans.2ropert State.A"BI+U.US,VALU0
the property is unclear. This status arises< for e9ample< when ?uerying the bold type property of a paragraph< which includes both words depicted in bold and words depicted in normal font. The following e9ample shows how format properties can be edited in #pen#ffice.org. &t searches through a te9t for paragraph portions which ha*e been depicted as bold type using direct formatting. &f it encounters a corresponding paragraph portion< it deletes the direct formatting using the se(Mroper(.To"e) u+( method and assigns a A.2o+- character template to the corresponding paragraph portion.
70
"i# "i# "i# "i# "i#
"o' $s 3b:e'( Enu#1 $s 3b:e'( Enu#2 $s 3b:e'( Tex(E+e#en( $s 3b:e'( Tex(Mor(ion $s 3b:e'(
"o' = T&is7o#ponen( Enu#1 = "o'1Tex(1're (eEnu#er (ion % +oop o*er ++ p r gr p&s C&i+e Enu#11& sAoreE+e#en(s Tex(E+e#en( = Enu#11nex(E+e#en( 6) Tex(E+e#en(1suppor(sSer*i'e(@'o#1sun1s( r1(ex(1M r gr p&@) T&en Enu#2 = Tex(E+e#en(1're (eEnu#er (ion % +oop o*er ++ p r gr p& por(ions C&i+e Enu#21& sAoreE+e#en(s Tex(Mor(ion = Enu#21nex(E+e#en( 6) Tex(Mor(ion17& rCeig&( = _ 'o#1sun1s( r1 0(18on(Ceig&(123L" $5" _ Tex(Mor(ion1ge(Mroper(.S( (e(@7& rCeig&(@) = _ 'o#1sun1s( r1be ns1Mroper(.S( (e1"6,E7T_4$LNE T&en Tex(Mor(ion1se(Mroper(.To"e) u+((@7& rCeig&(@) Tex(Mor(ion17& rS(.+e5 #e = @A.2o+-@ En- 6) CenEn- 6) Cen-
"diti%g !e1t 0ocume%ts

The pre*ious section has already discussed a whole range of options for editing te9t documents< focusing on the com.sun.star.te9t.Te9tPortion and com.sun.star.te9t.Paragraph ser*ices< which grant access to paragraph portions as well as paragraphs. These ser*ices are appropriate for applications in which the content of a te9t is to be edited in one pass through a loop. 7owe*er< this is not sufficient for many problems. #pen#ffice.org pro*ides the com.sun.star.te9t.Te9t ursor ser*ice for more complicated tas-s< including na*igating bac-ward within a document or na*igating based on sentences and words rather than Tex(Mor(ions.
!he !e1tCursor
" Tex(7ursor in the #pen#ffice.org "P& is comparable with the *isible cursor used in a #pen#ffice.org document. &t mar-s a certain point within a te9t document and can be na*igated in *arious directions through the use of commands. The Tex(7ursor objects a*ailable in #pen#ffice.org $asic should not< howe*er< be confused with the *isible cursor. These are two *ery different things. Note VBA : Terminology differs from that used in .$": &n terms of scope of function< the @ange object from .$" can be compared with the Te9t ursor object in #pen#ffice.org and not A as the name possibly suggests A with the @ange object in #pen#ffice.org. The Te9t ursor object in #pen#ffice.org< for e9ample< pro*ides methods for na*igating and changing te9t which are included in the @ange object in .$" :for e9ample< )o*eStart< )o*e6nd< &nsert$efore< &nsert"fter;. The corresponding counterparts of the Te9t ursor object in #pen#ffice.org are described in the following sections.
Na*igati%g +ithi% a !e1t

The Tex(7ursor object in #pen#ffice.org $asic acts independently from the *isible cursor in a te9t document. " programGcontrolled position change of a Tex(7ursor object has no impact whatsoe*er on the
79
3diting 'e8t 6ocuments
*isible cursor. Se*eral Tex(7ursor objects can e*en be opened for the same document and used in *arious positions< which are independent of one another. " Tex(7ursor object is created using the 're (eTex(7ursor call:
"i# "o' $s 3b:e'( "i# 7ursor $s 3b:e'( "o' = T&is7o#ponen( 7ursor = "o'1Tex(1're (eTex(7ursor()
The ursor object created in this way supports the 'o#1sun1s( r1(ex(1Tex(7ursor ser*ice< which in turn pro*ides a whole range of methods for na*igating within te9t documents. The following e9ample first mo*es the Tex(7ursor ten characters to the left and then three characters to the right:
7ursor1goLe)((1D< 8 +se) 7ursor1go,ig&((3< 8 +se)
" Tex(7ursor can highlight a complete area. This can be compared with highlighting a point in the te9t using the mouse. The 8 +se parameter in the pre*ious function call specifies whether the area passed o*er with the cursor mo*ement is highlighted. 5or e9ample< the Tex(7ursor in the following e9ample
7ursor1go,ig&((1D< 8 +se) 7ursor1goLe)((3< True)
first mo*es ten characters to the right without highlighting< and then mo*es bac- three characters and highlights this. The area highlighted by the Tex(7ursor therefore begins after the se*enth character in the te9t and ends after the tenth character. 7ere are the central methods that the com.sun.star.te9t.Te9t ursor ser*ice pro*ides for na*igation:
goLe!t (Count# 01pan%)
jumps ount characters to the left.

go$ight (Count# 01pan%)
jumps ount characters to the right.

gotoStart (01pan%)
jumps to the start of the te9t document.

goto0n% (01pan%)
jumps to the end of the te9t document.

goto$ange ()e1t$ange# 01pan%)
jumps to the specified Tex(, ngeG#bject.

gotoStart.!Wor% (01pan%)
jumps to the start of the current word.

goto0n%.!Wor% (01pan%)
jumps to the end of the current word.

gotoNe1tWor% (01pan%)
jumps to the start of the ne9t word.

goto2re3iousWor% (01pan%)
jumps to the start of the pre*ious word.

isStart.!Wor% ()
returns True if the Tex(7ursor is at the start of a word.

is0n%.!Wor% ()
returns True if the Tex(7ursor is at the end of a word.

gotoStart.!Sentence (01pan%)
jumps to the start of the current sentence.
00
goto0n%.!Sentence (01pan%)
jumps to the end of the current sentence.

gotoNe1tSentence (01pan%)
jumps to the start of the ne9t sentence.

goto2re3iousSentence (01pan%)
jumps to the start of the pre*ious sentence.

isStart.!Sentence ()
returns True if the Tex(7ursor is at the start of a sentence.

is0n%.!Sentence ()
returns True if the Tex(7ursor is at the end of a sentence.

gotoStart.!2aragraph (01pan%)
jumps to the start of the current paragraph.

goto0n%.!2aragraph (01pan%)
jumps to the end of the current paragraph.

gotoNe1t2aragraph (01pan%)
jumps to the start of the ne9t paragraph.

goto2re3ious2aragraph (01pan%)
jumps to the start of the pre*ious paragraph.

isStart.!2aragraph ()
returns True if the Tex(7ursor is at the start of a paragraph.

is0n%.!2aragraph ()
returns True if the Tex(7ursor is at the end of a paragraph. The te9t is di*ided into sentences on the basis of sentence symbols. Periods are< for e9ample< interpreted as symbols indicating the end of sentences. :&n 6nglish< at least< they must be followed by a space< tab< or return for this to wor-.; The Exp n- parameter is a $oolean *alue which specifies whether the area passed o*er during na*igation is to be highlighted. "ll na*igation methods furthermore return a $oolean parameter which specifies whether the na*igation was successful or whether the action was terminated for lac- of te9t. The following is a list of se*eral methods for editing highlighted areas using a Tex(7ursor and which also support the com.sun.star.te9t.Te9t ursor ser*ice:
collapse)oStart ()
resets the highlighting and positions the Tex(7ursor at the start of the pre*iously highlighted area.
collapse)o0n% ()
resets the highlighting and positions the Tex(7ursor at the end of the pre*iously highlighted area.
isCollapse% ()
returns True if the Tex(7ursor does not co*er any highlighting at present.
3ormatti%g !e1t +ith !e1tCursor

The com.sun.star.te9t.Te9t ursor ser*ice supports all the character and paragraph properties that were presented at the start of this chapter. The following e9ample shows how these can be used in conjunction with a Tex(7ursor. &t passes through a complete document and formats the first word of e*ery sentence in bold type.
%&apter / 'e8t 6ocuments 01
"i# "o' $s 3b:e'( "i# 7ursor $s 3b:e'( "i# Mro'ee- $s 2oo+e n "o' = T&is7o#ponen( 7ursor = "o'1Tex(1're (eTex(7ursor "o 7ursor1go(oEn-3)Cor-(True) 7ursor17& rCeig&( = 'o#1sun1s( r1 0(18on(Ceig&(123L" Mro'ee- = 7ursor1go(o5ex(Sen(en'e(8 +se) 7ursor1go(o5ex(Cor-(8 +se) Loop C&i+e Mro'ee-
The e9ample first creates a document object for the te9t that has just been opened. Then it iterates through the entire te9t< sentence by sentence< and highlights each of the first words and formats this in bold.
#etrie*i%g a%d (odifyi%g !e1t Co%te%ts

&f a Tex(7ursor contains a highlighted area< then this te9t is a*ailable by means of the S(ring property of the Tex(7ursor object. The following e9ample uses the S(ring property to display the first words of a sentence in a message bo9:
"i# "o' $s 3b:e'( "i# 7ursor $s 3b:e'( "i# Mro'ee- $s 2oo+e n "o' = T&is7o#ponen( 7ursor = "o'1Tex(1're (eTex(7ursor "o 7ursor1go(oEn-3)Cor-(True) Asg2ox 7ursor1S(ring Mro'ee- = 7ursor1go(o5ex(Sen(en'e(8 +se) 7ursor1go(o5ex(Cor-(8 +se) Loop C&i+e Mro'ee-
The first word of each sentence can be modified in the same way using the S(ring property:
"i# "o' $s 3b:e'( "i# 7ursor $s 3b:e'( "i# Mro'ee- $s 2oo+e n "o' = T&is7o#ponen( 7ursor = "o'1Tex(1're (eTex(7ursor "o 7ursor1go(oEn-3)Cor-(True) 7ursor1S(ring = @Nps@ Mro'ee- = 7ursor1go(o5ex(Sen(en'e(8 +se) 7ursor1go(o5ex(Cor-(8 +se) Loop C&i+e Mro'ee-
&f the Tex(7ursor contains a highlighted area< an assignment to the S(ring property replaces this with the new te9t. &f there is no highlighted area< the te9t is inserted at the present Tex(7ursor position.
&%serti%g Co%tro/ Codes

&n some situations< it is not the actual te9t of a document< but rather its structure that needs modifying. #pen#ffice.org pro*ides control codes for this purpose. These are inserted in the te9t and influence its structure. The control codes are defined in the com.sun.star.te9t. ontrol haracter group of constants. The following control codes are a*ailable in #pen#ffice.org:
2A$A+$A2(,B$0A5
paragraph brea-.
LIN0,B$0A5
line brea- within a paragraph.
0"
S.-),(&2(0N
possible point for syllabification.

(A$D,(&2(0N
obligatory point for syllabification.

(A$D,S2AC0
protected space that is not spread out or compressed in justified te9t. To insert the control codes< you need not only the cursor but also the associated te9t document objects. The following e9ample inserts a paragraph after the !3th character of a te9t:
"i# "o' $s 3b:e'( "i# 7ursor $s 3b:e'( "i# Mro'ee- $s 2oo+e n "o' = T&is7o#ponen( 7ursor = "o'1Tex(1're (eTex(7ursor 7ursor1go,ig&((2D< 8 +se) "o'1Tex(1inser(7on(ro+7& r '(er(7ursor< _ 'o#1sun1s( r1(ex(17on(ro+7& r '(er1M$,$G,$MB_2,E$V< 8 +se)
The 8 +se parameter in the call of the inser(7on(ro+7& r '(er method ensures that the area currently highlighted by the Tex(7ursor remains after the insert operation. &f the True parameter is passed here< then inser(7on(ro+7& r '(er replaces the current te9t.
2earchi%g for !e1t Portio%s

&n many instances< it is the case that a te9t is to be searched for a particular term and the corresponding point needs to be edited. "ll #pen#ffice.org documents pro*ide a special interface for this purpose< and this interface always functions in accordance with the same principle: $efore a search process< what is commonly referred to as a Se r'&"es'rip(or must first be created. This defines what #pen#ffice.org searches for in a document. " Se r'&"es'rip(or is an object which supports the 'o#1sun1s( r1u(i+1 Se r'&"es'rip(or ser*ice and can be created by means of the 're (eSe r'&"es'rip(or method of a document:
"i# Se r'&"es' $s 3b:e'( Se r'&"es' = "o'1're (eSe r'&"es'rip(or
#nce the Se r'&"es'rip(or has been created< it recei*es the te9t to be searched for:
Se r'&"es'1se r'&S(ring=@ n. (ex(@
&n terms of its function< the Se r'&"es'rip(or is best compared with the search dialog from #pen#ffice.org. &n a similar way to the search window< the settings needed for a search can be set in the Se r'&"es'rip(or object. The properties are pro*ided by the com.sun.star.util.SearchDescriptor ser*ice:
SearchBac'*ar%s (Boolean)
searches through the te9t bac-ward rather than forward.

SearchCaseSensiti3e (Boolean)
ta-es uppercase and lowercase characters into consideration during the search.
Search$egular01pression (Boolean)
treats the search e9pression li-e a regular e9pression.

SearchSt les (Boolean)
searches through the te9t for the specified paragraph template.

SearchWor%s (Boolean)
only searches for complete words.
03
The #pen#ffice.org Se r'&Si#i+ ri(. :or VfuBBy matchW; function is also a*ailable in #pen#ffice.org $asic. ,ith this function< #pen#ffice.org searches for an e9pression that may be similar to but not e9actly the same as the search e9pression. The number of additional< deleted and modified characters for these e9pressions can be defined indi*idually. 7ere are the associated properties of the 'o#1sun1s( r1u(i+1Se r'&"es'rip(or ser*ice:
SearchSimilarit (Boolean)
performs a similarity search.

SearchSimilarit A%% (Short)
number of characters which may be added for a similarity search.

SearchSimilarit 01change (Short)
number of characters which may be replaced as part of a similarity search.

SearchSimilarit $emo3e (Short)
number of characters which may be remo*ed as part of a similarity search.

SearchSimilarit $ela1 (Boolean)
ta-es all de*iation rules into consideration at the same time for the search e9pression. #nce the Se r'&"es'rip(or has been prepared as re?uested< it can be applied to the te9t document. The #pen#ffice.org documents pro*ide the )in-8irs( and )in-5ex( methods for this purpose:
8oun- = "o'1)in-8irs( (Se r'&"es') "o Nn(i+ 6s5u++(8oun-) % E-i( se r'& resu+(s111 8oun- = "o'1)in-5ex(( 8oun-1En-< Se r'&"es') Loop
The e9ample finds all matches in a loop and returns a Tex(, nge object< which refers to the found te9t passage.
"1amp/e6 2imi/arity 2earch

This e9ample shows how a te9t can be searched for the word Nturno*erN and the results formatted in bold type. " similarity search is used so that not only the word Vturno*erW< but also the plural form Nturno*ersN and declinations such as Nturno*erCsN are found. The found e9pressions differ by up to two letters from the search e9pression:
"i# Se r'&"es' $s 3b:e'( "i# "o' $s 3b:e'( "o' = T&is7o#ponen( Se r'&"es' = "o'1're (eSe r'&"es'rip(or Se r'&"es'1Se r'&S(ring=@(urno*er@ Se r'&"es'1Se r'&Si#i+ ri(. = True Se r'&"es'1Se r'&Si#i+ ri(.$-- = 2 Se r'&"es'1Se r'&Si#i+ ri(.Ex'& nge = 2 Se r'&"es'1Se r'&Si#i+ ri(.,e#o*e = 2 Se r'&"es'1Se r'&Si#i+ ri(.,e+ x = 8 +se 8oun- = "o'1)in-8irs( (Se r'&"es') "o Nn(i+ 6s5u++(8oun-) 8oun-17& rCeig&( = 'o#1sun1s( r1 0(18on(Ceig&(123L" 8oun- = "o'1)in-5ex(( 8oun-1En-< Se r'&"es') Loop
Note VBA : The basic idea of search and replace in #pen#ffice.org is comparable to that used in .$". $oth interfaces pro*ide you with an object< through which the properties for searching and replacing can be defined. This object is then applied to the re?uired te9t area in order to perform the action. ,hereas the responsible au9iliary object in .$" can be reached through the 5ind property of the @ange object< in #pen#ffice.org $asic it is created by the 're (eSe r'&"es'rip(or or 're (e,ep+ 'e"es'rip(or call of the document object. 6*en the search properties and methods a*ailable differ.
04
"s in the old "P& from #pen#ffice.org< searching and replacing te9t in the new "P& is also performed using the document object. ,hereas pre*iously there was an object called Se r'&Se((ings especially for defining the search options< in the new object searches are now performed using a Se r'&"es'rip(or or ,ep+ 'e"es'rip(or object for automatically replacing te9t. These objects co*er not only the options< but also the current search te9t and< if necessary< the associated te9t replacement. The descriptor objects are created using the document object< completed in accordance with the rele*ant re?uests< and then transferred bac- to the document object as parameters for the search methods.
#ep/aci%g !e1t Portio%s

=ust as with the search function< the replacement function from #pen#ffice.org is also a*ailable in #pen#ffice.org $asic. The two functions are handled identically. " special object which records the parameters for the process is also first needed for a replacement process. &t is called a ,ep+ 'e"es'rip(or and supports the com.sun.star.util.@eplaceDescriptor ser*ice. "ll the properties of the Se r'&"es'rip(or described in the pre*ious paragraph are also supported by ,ep+ 'e"es'rip(or1 5or e9ample< during a replacement process< case sensiti*ity can also be acti*ated and deacti*ated< and similarity searches can be performed. The following e9ample demonstrates the use of ,ep+ 'e"es'rip(ors for a search within a #pen#ffice.org document.
"i# "i# "i# "i# "i# 6 $s Long "o' $s 3b:e'( ,ep+ 'e $s 3b:e'( 2ri(is&Cor-s(5) $s S(ring NSCor-s(5) $s S(ring
2ri(is&Cor-s() = $rr .(@'o+our@< @neig&bour@< @'en(re@< @be& *iour@< _ @#e(re@< @(&roug&@) NSCor-s() = $rr .(@'o+or@< @neig&bor@< @'en(er@< @be& *ior@< _ @#e(er@< @(&ru@) "o' = T&is7o#ponen( ,ep+ 'e = "o'1're (e,ep+ 'e"es'rip(or 8or 6 = D To 5 ,ep+ 'e1Se r'&S(ring = 2ri(is&Cor-s(6) ,ep+ 'e1,ep+ 'eS(ring = NSCor-s(6) "o'1rep+ 'e$++(,ep+ 'e) 5ex( 6
The e9pressions for searching and replacing are set using the Se r'&S(ring and ,ep+ 'eS(ring properties of the ,ep+ 'e"es'rip(ors. The actual replacement process is finally implemented using the rep+ 'e$++ method of the document object< which replaces all occurrences of the search e9pression.
"1amp/e6 searchi%g a%d rep/aci%g te1t +ith regu/ar e1pressio%s

The replacement function of #pen#ffice.org is particularly effecti*e when used in conjunction with regular e9pressions. These pro*ide the option of defining a *ariable search e9pression with place holders and special characters rather than a fi9ed *alue. The regular e9pressions supported by #pen#ffice.org are described in detail in the online help section for #pen#ffice.org. 7ere are a few e9amples: " period within a search e9pression stands for any character. The search e9pression sh.rt therefore can stand for both for s&ir( and for s&or(. The character [ mar-s the start of a paragraph. "ll occurrences of the name Me(er that are at the start of a paragraph can therefore be found using the search e9pression QMe(er. The character R mar-s a paragraph end. "ll occurrences of the name Me(er that are at the end of a paragraph can therefore be found using the search e9pression Me(erF. " T indicates that the preceding character may be repeated any number of times. &t can be combined with the period as a place holder for any character. The (e#per1*e e9pression< for e9ample< can stand for the e9pressions (e#per n'e and (e#per (ure.
0-
The following e9ample shows how all empty lines in a te9t document can be remo*ed with the help of the regular e9pression [R:
"i# "o' $s 3b:e'( "i# ,ep+ 'e $s 3b:e'( "i# 6 $s Long "o' = T&is7o#ponen( ,ep+ 'e = "o'1're (e,ep+ 'e"es'rip(or ,ep+ 'e1Se r'&,egu+ rExpression = True ,ep+ 'e1Se r'&S(ring = @QF@ ,ep+ 'e1,ep+ 'eS(ring = @@ "o'1rep+ 'e$++(,ep+ 'e)
(ore !ha% >ust !e1t

So far< this chapter has only dealt with te9t paragraphs and their portions. $ut te9t documents may also contain other objects. These include tables< drawings< te9t fields and directories. "ll of these objects can be anchored to any point within a te9t. Than-s to these common features< all of these objects in #pen#ffice.org support a common basic ser*ice called com.sun.star.te9t.Te9t ontent. This pro*ides the following properties:
Anchor) pe (0num)
determines the anchor type of a Tex(7on(en( object :default *alues in accordance with com.sun.star.te9t.Te9t ontent"nchorType enumeration;.
Anchor) pes (se7uence o! 0num)
enumeration of all $n'&orT.pes which support a special Tex(7on(en( object.

)e1tWrap (0num)
determines the te9t wrap type around a Tex(7on(en( object :default *alues in accordance with com.sun.star.te9t.,rapTe9t)ode enumeration;. The Tex(7on(en( objects also share some methods F in particular< those for creating< inserting and deleting objects.

" new Tex(7on(en( object is crea ed using the 're (e6ns( n'e method of the document object. "n object is %$ser ed using the inser(Tex(7on(en( method of the te9t object. Tex(7on(en( objects are de#e ed using the re#o*eTex(7on(en( method.
You will find a range of e9amples which use these methods in the following sections.
!ab/es
The following e9ample creates a table with the help of the create&nstance method described pre*iously.
"i# "o' $s 3b:e'( "i# T b+e $s 3b:e'( "i# 7ursor $s 3b:e'( "o' = T&is7o#ponen( 7ursor = "o'1Tex(1're (eTex(7ursor() T b+e = "o'1're (e6ns( n'e(@'o#1sun1s( r1(ex(1Tex(T b+e@) T b+e1ini(i +iXe(5< 4) "o'1Tex(1inser(Tex(7on(en((7ursor< T b+e< 8 +se)
#nce created< the table is set to the number of rows and columns re?uested using an ini(i +iXe call and then inserted in the te9t document using inser(Tex(7on(en(1
0/
7ore '&an >ust 'e8t
"s can be seen in the e9ample< the inser(Tex(7on(en( method e9pects not only the 7on(en( object to be inserted< but two other parameters:

a 7ursor object which determines the insert position a $oolean *ariable which specifies whether the 7on(en( object is to replace the current selection of the cursor :True *alue; or is to be inserted before the current selection in the te9t :8 +se;
Note VBA : ,hen creating and inserting tables in a te9t document< objects similar to those a*ailable in .$" are used in #pen#ffice.org $asic: The document object and a Tex(7ursor object in #pen#ffice.org $asic< or the , nge object as the .$" counterpart. ,hereas the "o'u#en(1T b+es1$-- method ta-es on the tas- of creating and setting the table in .$"< this is created in #pen#ffice.org $asic in accordance with the pre*ious e9ample using 're (e6ns( n'e< initialiBed< and inserted in the document through inser(Tex(7on(en(. The tables inserted in a te9t document can be determined using a simple loop. The method ge(Tex(T b+es() of the te9t document object is used for this purpose:
"i# "o' $s 3b:e'( "i# Tex(T b+es $s 3b:e'( "i# T b+e $s 3b:e'( "i# 6 $s 6n(eger "o' = T&is7o#ponen( Tex(T b+es = "o'1ge(Tex(T b+es() 8or 6 = D (o Tex(T b+es1'oun( H 1 T b+e = Tex(T b+es(6) % E-i(ing ( b+e 5ex( 6
Note Te9t tables are a*ailable in #pen#ffice.org through the Tex(T b+es list of the document object. The pre*ious e9ample shows how a te9t table can be created. The options for accessing te9t tables are described in the following section.
"diti%g !ab/es
" table consists of indi*idual rows. These in turn contain the *arious cells. Strictly spea-ing< there are no table columns in #pen#ffice.org. These are produced implicitly by arranging the rows :one under another; ne9t to one another. To simplify access to the tables< #pen#ffice.org< howe*er< pro*ides some methods which operate using columns. These are useful if no cells ha*e been merged in the table. Let us first ta-e the properties of the table itself. These are defined in the com.sun.star.te9t.Te9tTable ser*ice. 7ere is an list of the most important properties of the table object:
Bac'Color (Long)
bac-ground color of table.

Bottom"argin (Long)

Le!t"argin (Long)

$ight"argin (Long)

)op"argin (Long)

$epeat(ea%line (Boolean)
table header is repeated on e*ery page.
07
7ore '&an >ust 'e8t
Wi%th (Long)
absolute width of the table in /33ths of a millimeter.
#o+s
" table consists of a list containing rows. The following e9ample shows how the rows of a table can be retrie*ed and formatted.
"i# "i# "i# "i# "i# "i# "o' $s 3b:e'( T b+e $s 3b:e'( 7ursor $s 3b:e'( ,o0s $s 3b:e'( ,o0 $s 3b:e'( 6 $s 6n(eger
"o' = T&is7o#ponen( 7ursor = "o'1Tex(1're (eTex(7ursor() T b+e = "o'1're (e6ns( n'e(@'o#1sun1s( r1(ex(1Tex(T b+e@) T b+e1ini(i +iXe(5< 4) "o'1Tex(1inser(Tex(7on(en((7ursor< T b+e< 8 +se) ,o0s = T b+e1ge(,o0s 8or 6 = D To ,o0s1ge(7oun(() H 1 ,o0 = ,o0s1ge(2.6n-ex(6) ,o012 '/7o+or = GB88DD88 5ex(
The e9ample first creates a list containing all rows using a T b+e1ge(,o0s call. The ge(7oun( and ge(2.6n-ex methods allow the list to be further processed and belongs to the 'o#1sun1s( r1( b+e1R( b+e,o0s interface. The ge(2.6n-ex method returns a row object< which supports the com.sun.star.te9t.Te9tTable@ow ser*ice. 7ere are the central methods of the com.sun.star.table.Xtable@ows interface:
getB In%e1(Integer)
returns a row object for the specified inde9.

getCount()
returns the number of row objects.

insertB In%e1(In%e1# Count)
inserts ount rows in the table as of the 6n-ex position.

remo3eB In%e1(In%e1# Count)
deletes ount rows from the table as of the 6n-ex position. ,hereas the ge(2.6n-ex and ge(7oun( methods are a*ailable in all tables< the inser(2.6n-ex and re#o*e2.6n-ex methods can only be used in tables that do not contain merged cells. The com.sun.star.te9t.Te9tTable@ow ser*ice pro*ides the following properties:
Bac'Color (Long)
bac-ground color of row.

(eight (Long)
height of line in /33ths of a millimeter.

IsAuto(eight (Boolean)
table height is dynamically adapted to the content.

Vert.rient (const)
*ertical orientation of the te9t frame A details on *ertical orientation of the te9t within the table :*alues in accordance with com.sun.star.te9t..ert#rientation;
00
7ore '&an >ust 'e8t
Co/um%s
olumns are accessed in the same way as rows< using the ge(2.6n-ex< ge(7oun(< inser(2.6n-ex< and re#o*e2.6n-ex methods on the 7o+u#n object< which is reached through ge(7o+u#ns. They can< howe*er< only be used in tables that do not contain merged table cells. ells cannot be formatted by column in #pen#ffice.org $asic. To do so< the method of formatting indi*idual table cells must be used.
Ce//s
6ach cell of a #pen#ffice.org document has a uni?ue name. &f the cursor of #pen#ffice.org is in a cell< then the name of that cell can be seen in the status bar. The top left cell is usually called "/ and the bottom right row is usually called Rn< where R stands for the letters of the top column and n for the numbers of the last row. The cell objects are a*ailable through the ge(7e++2.5 #e() method of the table object. The following e9ample shows a loop that passes through all the cells of a table and enters the corresponding row and column numbers into the cells.
"i# "i# "i# "i# "i# "i# "i# "i# "i# "o' $s 3b:e'( T b+e $s 3b:e'( 7ursor $s 3b:e'( ,o0s $s 3b:e'( ,o06n-ex $s 6n(eger 7o+s $s 3b:e'( 7o+6n-ex $s 6n(eger 7e++5 #e $s S(ring 7e++ $s 3b:e'(
"o' = T&is7o#ponen( 7ursor = "o'1Tex(1're (eTex(7ursor() T b+e = "o'1're (e6ns( n'e(@'o#1sun1s( r1(ex(1Tex(T b+e@) T b+e1ini(i +iXe(5< 4) "o'1Tex(1inser(Tex(7on(en((7ursor< T b+e< 8 +se) ,o0s = T b+e1ge(,o0s 7o+s = T b+e1ge(7o+u#ns 8or ,o06n-ex = 1 To ,o0s1ge(7oun(() 8or 7o+6n-ex = 1 To 7o+s1ge(7oun(() 7e++5 #e = 7&r($s'(@$@) H 1 + 7o+6n-ex) G ,o06n-ex 7e++ = T b+e1ge(7e++2.5 #e(7e++5 #e) 7e++1S(ring = @ro0! @ G 7S(r(,o06n-ex) + @< 'o+u#n! @ G 7S(r(7o+6n-ex) 5ex( 5ex(
" table cell is comparable with a standard te9t. &t supports the 're (eTex(7ursor interface for creating an associated Tex(7ursor object.
7e++7ursor = 7e++1're (eTex(7ursor()
"ll formatting options for indi*idual characters and paragraphs are therefore automatically a*ailable. The following e9ample searches through all tables of a te9t document and applies the rightGalign format to all cells with numerical *alues by means of the corresponding paragraph property.
"i# "i# "i# "i# "i# "i# "i# "i# "o' $s 3b:e'( Tex(T b+es $s 3b:e'( T b+e $s 3b:e'( 7e++5 #es 7e++ $s 3b:e'( 7e++7ursor $s 3b:e'( 6 $s 6n(eger W $s 6n(eger
"o' = T&is7o#ponen( Tex(T b+es = "o'1ge(Tex(T b+es() 8or 6 = D (o Tex(T b+es1'oun( H 1 T b+e = Tex(T b+es(6) 7e++5 #es = T b+e1ge(7e++5 #es() 8or W = D (o N2oun-(7e++5 #es) 7e++ = T b+e1ge(7e++2.5 #e(7e++5 #es(W))
09
7ore '&an >ust 'e8t
6) 6s5u#eri'(7e++1S(ring) T&en 7e++7ursor = 7e++1're (eTex(7ursor() 7e++7ursor1p r $-:us( = 'o#1sun1s( r1s(.+e1M r gr p&$-:us(1,6GBT En- 6) 5ex( 5ex(
The e9ample creates a Tex(T b+es list containing all tables of a te9t that are tra*ersed in a loop. #pen#ffice.org then creates a list of the associated cell names for each of these tables. There are passed through in turn in a loop. &f a cell contains a numerical *alue< then the e9ample changes the formatting correspondingly. To do this< it first creates a Tex(7ursor object which ma-es reference to the content of the table cell and then adapts the paragraph properties of the table cell.
!e1t 3rames
Te9t frames are considered to be Tex(7on(en( objects< just li-e tables and graphs. They may essentially consist of standard te9t< but can be placed at any position on a page and are not included in the te9t flow. "s with all Tex(7on(en( objects< a distinction is also made with te9t frames between the actual creation and insertion in the document.
"i# "i# "i# "i# "o' $s 3b:e'( Tex(T b+es $s 3b:e'( 7ursor $s 3b:e'( 8r #e $s 3b:e'(
"o' = T&is7o#ponen( 7ursor = "o'1Tex(1're (eTex(7ursor() 8r #e = "o'1're (e6ns( n'e(@'o#1sun1s( r1(ex(1Tex(8r #e@) "o'1Tex(1inser(Tex(7on(en((7ursor< 8r #e< 8 +se)
The te9t frame is created using the 're (e6ns( n'e method of the document object. The te9t frame created in this way can then be inserted in the document using the inser(Tex(7on(en( method of the Tex( object. &n so doing< the name of the proper com.sun.star.te9t.Te9t5rame ser*ice should be specified. The te9t frameCs insert position is determined by a 7ursor object< which is also e9ecuted when inserted. Note VBA : Te9t frames are #pen#ffice.orgCs counterpart to the position frame used in ,ord. ,hereas .$" uses the "o'u#en(18r #es1$-- method for this purpose< creation in #pen#ffice.org $asic is performed using the pre*ious procedure with the aid of a Tex(7ursor as well as the 're (e6ns( n'e method of the document object. Te9t frame objects pro*ide a range of properties with which the position and beha*ior of the frame can be influenced. The majority of these properties are defined in the com.sun.star.te9t.$ase5rameProperties ser*ice< which is also supported by each Tex(8r #e ser*ice. The central properties are:
Bac'Color (Long)
bac-ground color of the te9t frame.

Bottom"argin (Long)

Le!t"argin (Long)

$ight"argin (Long)

)op"argin (Long)

(eight (Long)
height of te9t frame in /33ths of a millimeter.
90
7ore '&an >ust 'e8t
Wi%th (Long)
width of te9t frame in /33ths of a millimeter.

(ori.rient (const)
horiBontal orientation of te9t frame :in accordance with com.sun.star.te9t.7ori#rientation;.

Vert.rient (const)
*ertical orientation of te9t frame :in accordance with com.sun.star.te9t..ert#rientation;. The following e9ample creates a te9t frame using the properties described pre*iously:
"i# "i# "i# "i# "o' $s 3b:e'( Tex(T b+es $s 3b:e'( 7ursor $s 3b:e'( 8r #e $s 3b:e'(
"o' = T&is7o#ponen( 7ursor = "o'1Tex(1're (eTex(7ursor() 7ursor1go(o5ex(Cor-(8 +se) 8r #e = "o'1're (e6ns( n'e(@'o#1sun1s( r1(ex(1Tex(8r #e@) 8r 8r 8r 8r 8r 8r 8r 8r 8r 8r #e1Ci-(& = 3DDD #e1Beig&( = 1DDD #e1$n'&orT.pe = 'o#1sun1s( r1(ex(1Tex(7on(en($n'&orT.pe1$S_7B$,$7TE, #e1TopA rgin = D #e12o((o#A rgin = D #e1Le)(A rgin = D #e1,ig&(A rgin = D #e12or-er"is( n'e = D #e1Bori3rien( = 'o#1sun1s( r1(ex(1Bori3rien( (ion1535E #e14er(3rien( = 'o#1sun1s( r1(ex(14er(3rien( (ion1L65E_T3M
"o'1Tex(1inser(Tex(7on(en((7ursor< 8r #e< 8 +se)
The e9ample creates a Tex(7ursor as the insertion mar- for the te9t frame. This is positioned between the first and second word of the te9t. The te9t frame is created using "o'1're (e6ns( n'e. The properties of the te9t frame objects are set to the starting *alues re?uired. The interaction between the $n'&orT.pe :from the Tex(7on(en( Ser*ice; and 4er(3rien( :from the 2 se8r #eMroper(ies Ser*ice; properties should be noted here. $n'&orT.pe recei*es the $S_7B$,$7TE, *alue. The te9t frame is therefore inserted directly in the te9t flow and beha*es li-e a character. &t can< for e9ample< be mo*ed into the ne9t line if a line brea- occurs. The L65E_T3M *alue of the 4er(3rien( property ensures that the upper edge of the te9t frame is at the same height as the upper edge of the character. #nce initialiBation is complete< the te9t frame is finally inserted in the te9t document using a call from inser(Tex(7on(en(. To edit the content of a te9t frame< the user uses the Tex(7ursor< which has already been mentioned numerous times and is also a*ailable for te9t frames.
"i# "i# "i# "i# "i# "o' $s 3b:e'( Tex(T b+es $s 3b:e'( 7ursor $s 3b:e'( 8r #e $s 3b:e'( 8r #e7ursor $s 3b:e'(
"o' = T&is7o#ponen( 7ursor = "o'1Tex(1're (eTex(7ursor() 8r #e = "o'1're (e6ns( n'e(@'o#1sun1s( r1(ex(1Tex(8r #e@) 8r #e1Ci-(& = 3DDD 8r #e1Beig&( = 1DDD "o'1Tex(1inser(Tex(7on(en((7ursor< 8r #e< 8 +se) 8r 8r 8r 8r #e7ursor = 8r #e1're (eTex(7ursor() #e7ursor1'& rCeig&( = 'o#1sun1s( r1 0(18on(Ceig&(123L" #e7ursor1p r $-:us( = 'o#1sun1s( r1s(.+e1M r gr p&$-:us(17E5TE, #e7ursor1S(ring = @T&is is s# ++ Tes(I@
The e9ample creates a te9t frame< inserts this in the current document and opens a Tex(7ursor for the te9t
91
7ore '&an >ust 'e8t
frame. This cursor is used to set the frame font to bold type and to set the paragraph orientation to centered. The te9t frame is finally assigned the VThis is a small testSW string.
!e1t 3ie/ds
Te9t fields are Tex(7on(en( objects because they pro*ide additional logic e9tending beyond pure te9t. Te9t fields can be inserted in a te9t document using the same methods as those used for other Tex(7on(en( objects:
"i# "o' $s 3b:e'( "i# " (eTi#e8ie+- $s 3b:e'( "i# 7ursor $s 3b:e'( "o' = T&is7o#ponen( 7ursor = "o'1Tex(1're (eTex(7ursor() " (eTi#e8ie+- = "o'1're (e6ns( n'e(@'o#1sun1s( r1(ex(1(ex()ie+-1" (eTi#e@) " (eTi#e8ie+-16s8ixe- = 8 +se " (eTi#e8ie+-16s" (e = True "o'1Tex(1inser(Tex(7on(en((7ursor< " (eTi#e8ie+-< 8 +se)
The e9ample inserts a te9t field with the current date at the start of the current te9t document. The True *alue of the 6s" (e property results in only the date and not time being displayed. The 8 +se *alue for 6s8ixe- ensures that the date is automatically updated when the document is opened. Note VBA : ,hile the type of a field in .$" is specified by a parameter of the "o'u#en(18ie+-s1$-method< the name of the ser*ice that is responsible for the field type in ?uestion defines it in #pen#ffice.org $asic. Note / ar2""%ce 5 : &n the past< te9t fields were accessed using a whole range of methods that #pen#ffice.org made a*ailable in the old Se+e'(ion object :for e9ample 6nser(8ie+-< "e+e(eNser8ie+-< Se(7ur8ie+-). &n #pen#ffice.org< the fields are administered using an objectGoriented concept. To create a te9t field< a te9t field of the type re?uired should first be created and initialiBed using the properties re?uired. The te9t field is then inserted in the document using the inser(Tex(7on(en( method. " corresponding source te9t can be seen in the pre*ious e9ample. The most important field types and their properties are described in the following sections. &n addition to inserting te9t fields< searching a document for the fields can also be an important tas-. The following e9ample shows how all te9t fields of a te9t document can be tra*ersed in a loop and chec-ed for their rele*ant type.
"i# "i# "i# "i# "o' $s 3b:e'( Tex(8ie+-Enu# $s 3b:e'( Tex(8ie+- $s 3b:e'( 6 $s 6n(eger
"o' = T&is7o#ponen( Tex(8ie+-Enu# = "o'1ge(Tex(8ie+-s1're (eEnu#er (ion C&i+e Tex(8ie+-Enu#1& sAoreE+e#en(s() Tex(8ie+- = Tex(8ie+-Enu#1nex(E+e#en(() 6) Tex(8ie+-1suppor(sSer*i'e(@'o#1sun1s( r1(ex(1(ex()ie+-1" (eTi#e@) T&en Asg2ox @" (eO(i#e@ E+se6) Tex(8ie+-1suppor(sSer*i'e(@'o#1sun1s( r1(ex(1(ex()ie+-1$nno( (ion@) T&en Asg2ox @$nno( (ion@ E+se Asg2ox @un/no0n@ En- 6) Cen-
The starting point for establishing the te9t fields present is the Tex(8ie+-s list of the document object. The e9ample creates an Enu#er (ion object on the basis of this list< with which all te9t fields can be ?ueried in
9" LibreOffice 3.4 Basic Programmer's Guide !eptember "011
7ore '&an >ust 'e8t
turn in a loop. The te9t fields found are chec-ed for the ser*ice supported using the suppor(sSer*i'e method. &f the field pro*es to be a date/time field or an annotation< then the corresponding field type is displayed in an information bo9. &f on the other hand< the e9ample encounters another field< then it displays the information Vun-nownW. $elow< you will find a list of the most important te9t fields and their associated properties. " complete list of all te9t fields is pro*ided in the "P& reference in the 'o#1sun1s( r1(ex(1(ex()ie+- module. :,hen listing the ser*ice name of a te9t field< uppercase and lowercase characters should be used in #pen#ffice.org $asic< as in the pre*ious e9ample.;
Number of Pages5 -ords a%d Characters

The te9t fields

com.sun.star.te9t.te9tfield.Page ount com.sun.star.te9t.te9tfield.,ord ount com.sun.star.te9t.te9tfield. haracter ount
return the number of pages< words< or characters of a te9t. They support the following property:
Numbering) pe (const)
numbering format :guidelines in accordance with constants from com.sun.star.style.0umberingType;.
Curre%t Page
The number of the current page can be inserted in a document using the com.sun.star.te9t.te9tfield.Page0umber te9t field. The following properties can be specified:
Numbering) pe (const)
number format :guidelines in accordance with constants from com.sun.star.style.0umberingType;.

.!!set (short)
offset added to the number of pages :negati*e specification also possible;. The following e9ample shows how the number of pages can be inserted into the footer of a document.
"i# "i# "i# "i# "i# "i# "o' $s 3b:e'( " (eTi#e8ie+- $s 3b:e'( M geS(.+es $s 3b:e'( S(-M ge $s 3b:e'( 8oo(er7ursor $s 3b:e'( M ge5u#ber $s 3b:e'(
"o' = T&is7o#ponen( M ge5u#ber = "o'1're (e6ns( n'e(@'o#1sun1s( r1(ex(1(ex()ie+-1M ge5u#ber@) M ge5u#ber15u#beringT.pe = 'o#1sun1s( r1s(.+e15u#beringT.pe1$,$267 M geS(.+es = "o'1S(.+e8 #i+ies1ge(2.5 #e(@M geS(.+es@) S(-M ge = M geS(.+es(@"e) u+(@) S(-M ge18oo(er6s3n = True 8oo(er7ursor = S(-M ge18oo(erTex(Le)(1Tex(1're (eTex(7ursor() S(-M ge18oo(erTex(Le)(1Tex(1inser(Tex(7on(en((8oo(er7ursor< M ge5u#ber< 8 +se)
The e9ample first creates a te9t field which supports the com.sun.star.te9t.te9tfield.Page0umber ser*ice. Since the header and footer lines are defined as part of the page templates of #pen#ffice.org< this is initially established using the list of all M geS(.+es. To ensure that the footer line is *isible< the 8oo(er6s3n property is set to True. The te9t field is then inserted in the document using the associated te9t object of the leftGhand footer line.
93
7ore '&an >ust 'e8t
%%otatio%s
"nnotation fields :com.sun.star.te9t.te9tfield."nnotation; can be seen by means of a small yellow symbol in the te9t. lic-ing on this symbol opens a te9t field< in which a comment on the current point in the te9t can be recorded. "n annotation field has the following properties.
Author (String)
name of author.
Content (String)
comment te9t.
Date (Date)
date on which annotation is written.
0ate ? !ime
" date / time field :com.sun.star.te9t.te9tfield.DateTime; represents the current date or the current time. &t supports the following properties:
Is-i1e% (Boolean)
if True< the time details of the insertion remain unchanged< if 8 +se< these are updated each time the document is opened.
IsDate (Boolean)
if True< the field displays the current date< otherwise the current time.
Date)imeValue (struct)
current content of field :com.sun.star.util.DateTime structure;

Number-ormat (const)
format in which the time or date is depicted.
Chapter Name ? Number

The name of the current chapter is a*ailable through a te9t field of the com.sun.star.te9t.te9tfield. hapter type. The form can be defined using two properties.
Chapter-ormat (const)
determines whether the chapter name or the chapter number is depicted :in accordance with com.sun.star.te9t. hapter5ormat;
Le3el (Integer)
determines the chapter le*el whose name and/or chapter number is to be displayed. The *alue 3 stands for highest le*el a*ailable.
Boo,mar,s
$oo-mar-s :Ser*ice com.sun.star.te9t.$oo-mar-; are Tex(7on(en( objects. $oo-mar-s are created and inserted using the concept already described pre*iously:
"i# "o' $s 3b:e'( "i# 2oo/# r/ $s 3b:e'( "i# 7ursor $s 3b:e'( "o' = T&is7o#ponen( 7ursor = "o'1Tex(1're (eTex(7ursor() 2oo/# r/ = "o'1're (e6ns( n'e(@'o#1sun1s( r1(ex(12oo/# r/@)
94
7ore '&an >ust 'e8t
2oo/# r/15 #e = @A. boo/# r/s@ "o'1Tex(1inser(Tex(7on(en((7ursor< 2oo/# r/< True)
The e9ample creates a 7ursor< which mar-s the insert position of the boo-mar- and then the actual boo-mar- object :2oo/# r/;. The boo-mar- is then assigned a name and is inserted in the document through inser(Tex(7on(en( at the cursor position. The boo-mar-s of a te9t are accessed through a list called 2oo/# r/s. The boo-mar-s can either be accessed by their number or their name. The following e9ample shows how a boo-mar- can be found within a te9t< and a te9t inserted at its position.
"i# "o' $s 3b:e'( "i# 2oo/# r/ $s 3b:e'( "i# 7ursor $s 3b:e'( "o' = T&is7o#ponen( 2oo/# r/ = "o'12oo/# r/s1ge(2.5 #e(@A. boo/# r/s@) 7ursor = "o'1Tex(1're (eTex(7ursor2., nge(2oo/# r/1$n'&or) 7ursor1S(ring = @Bere is (&e boo/# r/@
&n this e9ample< the ge(2.5 #e method is used to find the boo-mar- re?uired by means of its name. The 're (eTex(7ursor2., nge call then creates a 7ursor< which is positioned at the anchor position of the boo-mar-. The cursor then inserts the te9t re?uired at this point.
9-
C H
P ! " #
Spreadsheet (ocuments
#pen#ffice.org $asic pro*ides an e9tensi*e interface for programGcontrolled creation and editing of spreadsheets. This chapter describes how to control the rele*ant ser*ices< methods and properties of spreadsheet documents:

The Structure of Spreadsheets 6diting Spreadsheet Documents
The first section addresses the basic structure of spreadsheet documents and shows you how to access and to edit the contents of indi*idual cells. The second section concentrates on how to edit spreadsheets efficiently by focusing on cell areas and the options for searching and replacing cell contents. Note / ar2""%ce 5 : The , nge object allows you to address any table area and has been e9tended in the new "P&.
!he 2tructure of 2preadsheets

The document object of a spreadsheet is based on the com.sun.star.sheet.SpreadsheetDocument ser*ice. 6ach of these documents may contain se*eral spreadsheets. &n this guide< a tableGbased document or spreadsheet document is the entire document< whereas a spreadsheet :or sheet for short; is a sheet :table; in the document. Note VBA : Different terminology for spreadsheets and their content is used in .$" and #pen#ffice.org $asic. ,hereas the document object in .$" is called a ,or-boo- and its indi*idual pages ,or-sheets< they are called SpreadsheetDocument and Sheet in #pen#ffice.org $asic.
2preadsheets
You can access the indi*idual sheets of a spreadsheet document through the S&ee(s list. The following e9amples show you how to access a sheet either through its number or its name. :xamp#e 1: access .( mea$s o" )e $!m.er ;$!m.er%$g .eg%$s -% ) 0<
"i# "o' $s 3b:e'( "i# S&ee( $s 3b:e'(
97
'&e !tructure of !preads&eets
"o' = T&is7o#ponen( S&ee( = "o'1S&ee(s (D)
Note T&is7o#ponen( returns the currently acti*e document. The e9pression "o'1S&ee(s(D) is a $asic simplification of the "P& call : "o'1ge(S&ee(s1ge(2.6n-ex(D) :xamp#e 2: access .( mea$s o" )e $ame
"i# "o' $s 3b:e'( "i# S&ee( $s 3b:e'( "o' = T&is7o#ponen( S&ee( = "o'1S&ee(s1ge(2.5 #e(@S&ee( 1@)
&n the first e9ample< the sheet is accessed by its number :counting begins at 3;. &n the second e9ample< the sheet is accessed by its name and the ge(2.5 #e method. The S&ee( object that is obtained by the ge(2.5 #e method supports the com.sun.star.sheet.Spreadsheet ser*ice. &n addition to pro*iding se*eral interfaces for editing the content< this ser*ice pro*ides the following properties:
IsVisible (Boolean)
*alue True if the spreadsheet is *isible.

2ageSt le (String)
name of the page template for the spreadsheet.
#e%ami%g 2heets
" sheet pro*ides methods ge(5 #e and se(5 #e to read and modify its name. $asic can handle both methods li-e a property 5 #e. 7ere we rename the first sheet of the spreadsheet document.
"i# "o' $s 3b:e'( "i# S&ee( $s 3b:e'( "o' = T&is7o#ponen( S&ee( = "o'1S&ee(s(D) S&ee(15 #e = @8irs(@
Creati%g a%d 0e/eti%g 2heets

The S&ee(s container of a spre -s&ee( document is also used to create and delete indi*idual sheets. The following e9ample uses the & s2.5 #e method to chec- if a sheet called 6(/)ee e9ists. &f it does< the method determines a corresponding object reference by using the ge(2.5 #e method and then sa*es the reference in a *ariable in S&ee(. &f the corresponding sheet does not e9ist< it is created by the 're (e6ns( n'e call and inserted in the spreadsheet document by the inser(2.5 #e method.
"i# "o' $s 3b:e'( "i# S&ee( $s 3b:e'( "o' = T&is7o#ponen( 6) "o'1S&ee(s1& s2.5 #e(@A.S&ee(@) T&en S&ee( = "o'1S&ee(s1ge(2.5 #e(@A.S&ee(@) E+se S&ee( = "o'1're (e6ns( n'e(@'o#1sun1s( r1s&ee(1Spre -s&ee(@) "o'1S&ee(s1inser(2.5 #e(@A.S&ee(@< S&ee() En- 6)
The & s2.5 #e< ge(2.5 #e and inser(2.5 #e methods are obtained from the com.sun.star.container.X0ame ontainer interface as described in &ntroduction to the "P&. The interface com.sun.star.sheet.Spreadsheets pro*ides a better method to create a new sheet: inser(5e02.5 #e. &t inserts a new sheet with the name specified by the first argument< at the position specified by the second argument.
"i# "o' $s 3b:e'(
90
"o' = T&is7o#ponen( "o'1S&ee(s1inser(5e02.5 #e(@3(&erS&ee(@< 2)
The same interface pro*ides methods #o*e2.5 #e and 'op.2.5 #e. The com.sun.star.container.X0ame ontainer interface pro*ides a method to remo*e a sheet of a gi*en name:
"i# "o' $s 3b:e'( "o' = T&is7o#ponen( "o'1S&ee(s1re#o*e2.5 #e(@3(&erS&ee(@)
#o+s a%d Co/um%s

6ach sheet contains a list of its rows and columns. These are a*ailable through the ,o0s and 7o+u#ns properties of the spreadsheet object and support the com.sun.star.table.Table olumns and/or com.sun.star.table.Table@ows ser*ices. The following e9ample creates two objects that reference the first row and the first column of a sheet and stores the references in the 8irs(7o+ and 8irs(,o0 object *ariables.
"i# "i# "i# "i# "o' $s 3b:e'( S&ee( $s 3b:e'( 8irs(,o0 $s 3b:e'( 8irs(7o+ $s 3b:e'(
"o' = T&is7o#ponen( S&ee( = "o'1S&ee(s(D) 8irs(7o+ = S&ee(17o+u#ns(D) 8irs(,o0 = S&ee(1,o0s(D)
The column objects support the com.sun.star.table.Table olumn ser*ice that has the following properties:
Wi%th (long)
width of a column in hundredths of a millimeter.

.ptimalWi%th (Boolean)
sets a column to its optimum width.

IsVisible (Boolean)
displays a column.
IsStart.!Ne*2age (Boolean)
when printing< creates a page brea- before a column. The width of a column is only optimiBed when the 3p(i# +Ci-(& property is set to True. &f the width of an indi*idual cell is changed< the width of the column that contains the cell is not changed. &n terms of functionality< 3p(i# +Ci-(& is more of a method than a property. The row objects are based on the com.sun.star.table.Table@ow ser*ice that has the following properties:
(eight (long)
height of the row in /33ths of a millimeter.

.ptimal(eight (Boolean)
sets the row to its optimum height.

IsVisible (Boolean)
displays the row.
%&apter 7 !preads&eet 6ocuments
99
IsStart.!Ne*2age (Boolean)
when printing< creates a page brea- before the row. &f the 3p(i# +Beig&( property of a row is set to the True< the row height changes automatically when the height of a cell in the row is changed. "utomatic optimiBation continues until the row is assigned an absolute height through the Beig&( property. The following e9ample acti*ates the automatic height optimiBation for the first fi*e rows in the sheet and ma-es the second column in*isible.
"i# "i# "i# "i# "i# "o' $s 3b:e'( S&ee( $s 3b:e'( ,o0 $s 3b:e'( 7o+ $s 3b:e'( 6 $s 6n(eger
"o' = T&is7o#ponen( S&ee( = "o'1S&ee(s(D) 8or 6 = D To 4 ,o0 = S&ee(1,o0s(6) ,o013p(i# +Beig&( = True 5ex( 6 7o+ = S&ee(17o+u#ns(1) 7o+16s4isib+e = 8 +se
Note The ,o0s and 7o+u#ns lists can be accessed through an inde9 in #pen#ffice.org $asic. The real "P& call is : S&ee(1ge(7o+u#ns1ge(2.6n-ex(1) Note VBA : 'nli-e in .$"< the first column has the inde9 3 and not the inde9 /.
&%serti%g a%d 0e/eti%g #o+s a%d Co/um%s

The ,o0s and 7o+u#ns objects of a sheet can access e9isting rows and columns as well as insert and delete them.
"i# "o' $s 3b:e'( "i# S&ee( $s 3b:e'( "i# 5e07o+u#n $s 3b:e'( "o' = T&is7o#ponen( S&ee( = "o'1S&ee(s(D) S&ee(17o+u#ns1inser(2.6n-ex(3< 1) S&ee(17o+u#ns1re#o*e2.6n-ex(5< 1)
This e9ample uses the inser(2.6n-ex method to insert a new column into the fourth column position in the sheet :inde9 1 G numbering starts at 3;. The second parameter specifies the number of columns to be inserted :in this e9ample: one;. The re#o*e2.6n-ex method deletes the si9th column :inde9 4;. "gain< the second parameter specifies the number of columns that you want to delete. The methods for inserting and deleting rows use the ,o0s object function in the same way as the methods shown for editing columns using the 7o+u#ns object.
Ce//s a%d #a%ges

" spreadsheet consists of a twoGdimensional list containing cells. 6ach cell is defined by its X and YG position with respect to the top left cell which has the position :3<3;.
100
ddressi%g a%d "diti%g &%di*idua/ Ce//s

The following e9ample creates an object that references the top left cell and inserts a te9t in the cell:
"i# "o' $s 3b:e'( "i# S&ee( $s 3b:e'( "i# 7e++ $s 3b:e'( "o' = T&is7o#ponen( S&ee( = "o'1S&ee(s(D) 7e++ = S&ee(1ge(7e++2.Mosi(ion(D< D) 7e++1S(ring = @Tes(@
&n addition to numerical coordinates< each cell in a sheet has a name< for e9ample< the top left cell :3<3; of a spreadsheet is called $1. The letter $ stands for the column and the number / for the row. &t is important that the $ame and pos% %o$ of a cell are not confused because row counting for names begins with / but the counting for position begins with 3. &f the position of the cell is fi9ed< it is more clear to use the following code:
"i# "o' $s 3b:e'( "i# S&ee( $s 3b:e'( "i# 7e++ $s 3b:e'( "o' = T&is7o#ponen( S&ee( = "o'1S&ee(s(D) 7e++ = S&ee(1ge(7e++, nge2.5 #e(@$1@) 7e++1S(ring = @Tes(@
The abo*e code also wor-s with a named cell. &n #pen#ffice.org< a table cell can be empty or contain te9t< numbers< or formulas. The cell type is not determined by the content that is sa*ed in the cell< but rather the object property which was used for its entry. 0umbers can be inserted and called up with the 4 +ue property< te9t with the S(ring property< and formulas with the 8or#u+ property.
"i# "o' $s 3b:e'( "i# S&ee( $s 3b:e'( "i# 7e++ $s 3b:e'( "o' = T&is7o#ponen( S&ee( = "o'1S&ee(s(D) 7e++ = S&ee(1ge(7e++2.Mosi(ion(D< D) 7e++14 +ue = 1DD 7e++ = S&ee(1ge(7e++2.Mosi(ion(D< 1) 7e++1S(ring = @Tes(@ 7e++ = S&ee(1ge(7e++2.Mosi(ion(D< 2) 7e++18or#u+ = @=$1@
The e9ample inserts one number< one te9t< and one formula in the fields "/ to "1. Note / ar2""%ce 5 : The 4 +ue< S(ring< and 8or#u+ properties supersede the old Mu(7e++ method of Star#ffice 4 for setting the *alues of a table cell. #pen#ffice.org treats cell content that is entered using the S(ring property as te9t< e*en if the content is a number. 0umbers are leftGaligned in the cell instead of rightGaligned. You should also note the difference between te9t and numbers when you use formulas:
"i# "o' $s 3b:e'( "i# S&ee( $s 3b:e'( "i# 7e++ $s 3b:e'( "o' = T&is7o#ponen( S&ee( = "o'1S&ee(s(D) 7e++ = S&ee(1ge(7e++2.Mosi(ion(D< D) 7e++14 +ue = 1DD 7e++ = S&ee(1ge(7e++2.Mosi(ion(D< 1)
101
7e++1S(ring = 1DDD 7e++ = S&ee(1ge(7e++2.Mosi(ion(D< 2) 7e++18or#u+ = @=$1+$2@ Asg2ox 7e++14 +ue
"lthough cell "/ contains the *alue /33 and cell "! contains the *alue /333< the "/E"! formula returns the *alue /33. This is because the contents of cell "! were entered as a string and not as a number. To chec- if the contents of a cell contains a number or a string< use the T.pe property:
"i# "o' $s 3b:e'( "i# S&ee( $s 3b:e'( "i# 7e++ $s 3b:e'( "o' = T&is7o#ponen( S&ee( = "o'1S&ee(s(D) 7e++ = S&ee(1ge(7e++2.Mosi(ion(1<1) 7e++14 +ue = 1DDD Se+e'( 7 se 7e++1T.pe 7 se 'o#1sun1s( r1( b+e17e++7on(en(T.pe1EAMTZ Asg2ox @7on(en(! E#p(.@ 7 se 'o#1sun1s( r1( b+e17e++7on(en(T.pe14$LNE Asg2ox @7on(en(! 4 +ue@ 7 se 'o#1sun1s( r1( b+e17e++7on(en(T.pe1TERT Asg2ox @7on(en(! Tex(@ 7 se 'o#1sun1s( r1( b+e17e++7on(en(T.pe183,ANL$ Asg2ox @7on(en(! 8or#u+ @ En- Se+e'(
The 7e++1T.pe property returns a *alue for the com.sun.star.table. ell ontentType enumeration which identifies the contents type of a cell. The possible *alues are:
0"2)&
no *alue
VALU0
number
)08)
strings
-.$"ULA
formula
&%serti%g5 0e/eti%g5 Copyi%g a%d (o*i%g Ce//s

&n addition to directly modifying cell content< #pen#ffice.org alc also pro*ides an interface that allows you to insert< delete< copy< or merge cells. The interface :com.sun.star.sheet.X@ange)o*ement; is a*ailable through the spreadsheet object and pro*ides four methods for modifying cell content. The inser(7e++ method is used to insert cells into a sheet.
"i# "o' $s 3b:e'( "i# S&ee( $s 3b:e'( "i# 7e++, nge$--ress $s 5e0 'o#1sun1s( r1( b+e17e++, nge$--ress "o' = T&is7o#ponen( S&ee( = "o'1S&ee(s(D) 7e++, 7e++, 7e++, 7e++, 7e++, nge$--ress1S&ee( = D nge$--ress1S( r(7o+u#n = 1 nge$--ress1S( r(,o0 = 1 nge$--ress1En-7o+u#n = 2 nge$--ress1En-,o0 = 2
S&ee(1inser(7e++s(7e++, nge$--ress< 'o#1sun1s( r1s&ee(17e++6nser(Ao-e1"3C5)
10"
This e9ample inserts a cells range that is two rows by two columns in siBe into the second column and row :each bear the number /; of the first sheet :number 3; in the spreadsheet. "ny e9isting *alues in the specified cell range are mo*ed below the range. To define the cell range that you want to insert< use the com.sun.star.table. ell@ange"ddress structure. The following *alues are included in this structure:
Sheet (short)
number of the sheet :numbering begins with 3;.

StartColumn (long)
first column in the cell range :numbering begins with 3;.

Start$o* (long)
first row in the cell range :numbering begins with 3;.

0n%Column (long)
final column in the cell range :numbering begins with 3;.

0n%$o* (long)
final row in the cell range :numbering begins with 3;. The completed 7e++, nge$--ress structure must be passed as the first parameter to the inser(7e++s method. The second parameter of inser(7e++s contains a *alue of the com.sun.star.sheet. ell&nsert)ode enumeration and defines what is to be done with the *alues that are located in front of the insert position. The 7e++6nser(Ao-e enumeration recogniBes the following *alues:
N.N0
the current *alues remain in their present position.

D.WN
the cells at and under the insert position are mo*ed downwards.
$I+()
the cells at and to the right of the insert position are mo*ed to the right.
$.WS
the rows after the insert position are mo*ed downwards.

C.LU"NS
the columns after the insert position are mo*ed to the right. The re#o*e, nge method is the counterpart to the inser(7e++s method. This method deletes the range that is defined in the 7e++, nge$--ress structure from the sheet.
"i# "o' $s 3b:e'( "i# S&ee( $s 3b:e'( "i# 7e++, nge$--ress $s 5e0 'o#1sun1s( r1( b+e17e++, nge$--ress "o' = T&is7o#ponen( S&ee( = "o'1S&ee(s(D) 7e++, 7e++, 7e++, 7e++, 7e++, nge$--ress1S&ee( = D nge$--ress1S( r(7o+u#n = 1 nge$--ress1S( r(,o0 = 1 nge$--ress1En-7o+u#n = 2 nge$--ress1En-,o0 = 2
S&ee(1re#o*e, nge(7e++, nge$--ress< 'o#1sun1s( r1s&ee(17e++"e+e(eAo-e1NM)
This e9ample remo*es the 22!73 cell range from the sheet and then shifts the underlying cells up by two rows. The type of remo*al is defined by one of the following *alues from the com.sun.star.sheet. ellDelete)ode enumeration:
N.N0
the current *alues remain in their current position.

%&apter 7 !preads&eet 6ocuments 103
U2
the cells at and below the insert position are mo*ed upwards.
L0-)
the cells at and to the right of the insert position are mo*ed to the left.
$.WS
the rows after the insert position are mo*ed upwards.

C.LU"NS
the columns after the insert position are mo*ed to the left. The R, ngeAo*e#en( interface pro*ides two additional methods for mo*ing :#o*e, nge; or copying :'op., nge; cell ranges. The following e9ample mo*es the 22!73 range so that the range starts at position $6:
"i# "i# "i# "i# "o' $s 3b:e'( S&ee( $s 3b:e'( 7e++, nge$--ress $s 5e0 'o#1sun1s( r1( b+e17e++, nge$--ress 7e++$--ress $s 5e0 'o#1sun1s( r1( b+e17e++$--ress
"o' = T&is7o#ponen( S&ee( = "o'1S&ee(s(D) 7e++, 7e++, 7e++, 7e++, 7e++, nge$--ress1S&ee( = D nge$--ress1S( r(7o+u#n = 1 nge$--ress1S( r(,o0 = 1 nge$--ress1En-7o+u#n = 2 nge$--ress1En-,o0 = 2
7e++$--ress1S&ee( = D 7e++$--ress17o+u#n = D 7e++$--ress1,o0 = 5 S&ee(1#o*e, nge(7e++$--ress< 7e++, nge$--ress)
&n addition to the 7e++, nge$-ress structure< the #o*e, nge method e9pects a com.sun.star.table. ell"ddress structure to define the origin of the mo*eCs target region. The 7e++$--ress method pro*ides the following *alues:
Sheet (short)
number of the spreadsheet :numbering begins with 3;.

Column (long)
number of the addressed column :numbering begins with 3;.

$o* (long)
number of the addressed row :numbering begins with 3;. The cell contents in the target range are always o*erwritten by the #o*e, nge method. 'nli-e in the 6nser(7e++s method < a parameter for performing automatic mo*es is not pro*ided in the re#o*e, nge method. The 'op., nge method functions in the same way as the #o*e, nge method< e9cept that 'op., nge inserts a copy of the cell range instead of mo*ing it. Note VBA : &n terms of their function< the #pen#ffice.org $asic inser(7e++< re#o*e, nge< and 'op., nge methods are comparable with the .$" , nge16nser(< , nge1"e+e(e <and , nge17op. methods. ,hereas in .$"< the methods are applied to the corresponding , nge object< in #pen#ffice.org $asic they are applied to the associated S&ee( object.
104
3ormatti%g 2preadsheet 0ocume%ts

" spreadsheet document pro*ides properties and methods for formatting cells and pages.
Ce// Properties
There are numerous options for formatting cells< such as specifying the font type and siBe for te9t. 6ach cell supports the com.sun.star.style. haracterProperties and com.sun.star.style.ParagraphProperties ser*ices< the main properties of which are described in Te9t Documents. Special cell formatting is handled by the com.sun.star.table. ellProperties ser*ice. The main properties of this ser*ice are described in the following sections. You can apply all of the named properties to indi*idual cells and to cell ranges. Note VBA : The 7e++Mroper(ies object in the #pen#ffice.org "P& is comparable with the 6n(erior object from .$" which also defines cellGspecific properties.
Bac,grou%d Co/or a%d 2hado+s

The com.sun.star.table. ellProperties ser*ice pro*ides the following properties for defining bac-ground colors and shadows:
CellBac'Color (Long)
bac-ground color of the table cell

IsCellBac'groun%)ransparent (Boolean)
sets the bac-ground color to transparent

Sha%o*-ormat (struct)
specifies the shadow for cells :structure in accordance with com.sun.star.table.Shadow5ormat; The com.sun.star.table.Shadow5ormat structure and the detailed specifications for cell shadows ha*e the following structure:
Location (enum)
position of shadow :*alue from the com.sun.star.table.ShadowLocation structure;.

Sha%o*Wi%th (Short)
siBe of shadow in hundredths of a millimeter

Is)ransparent (Boolean)
sets the shadow to transparent

Color (Long)
color of shadow The following e9ample writes the number /333 to the $! cell< changes the bac-ground color to red using the 7e++2 '/7o+or property< and then creates a light gray shadow for the cell that is mo*ed / mm to the left and down.
"i# "i# "i# "i# "o' $s 3b:e'( S&ee( $s 3b:e'( 7e++ $s 3b:e'( S& -o08or# ( $s 5e0 'o#1sun1s( r1( b+e1S& -o08or# (
"o' = T&is7o#ponen( S&ee( = "o'1S&ee(s(D) 7e++ = S&ee(1ge(7e++2.Mosi(ion(1<1) 7e++14 +ue = 1DDD
10-
7e++17e++2 '/7o+or = ,G2(255< D< D) S& -o08or# (1Lo' (ion = 'o#1sun1s( r1( b+e1S& -o0Lo' (ion123TT3A_,6GBT S& -o08or# (1S& -o0Ci-(& = 1DD S& -o08or# (17o+or = ,G2(16D< 16D< 16D) 7e++1S& -o08or# ( = S& -o08or# (
>ustificatio%
#pen#ffice.org pro*ides *arious functions that allow you to change the justification of a te9t in a table cell. The following properties define the horiBontal and *ertical justification of a te9t:
(ori/usti! (enum)
horiBontal justification of the te9t :*alue from com.sun.star.table. ell7ori=ustify;

Vert/usti! (enum)
*ertical justification of the te9t :*alue from com.sun.star.table. ell.ert=ustify;

.rientation (enum)
orientation of te9t :*alue in accordance with com.sun.star.table. ell#rientation;

Is)e1tWrappe% (Boolean)
permits automatic line brea-s within the cell

$otateAngle (Long)
angle of rotation of te9t in hundredths of a degree The following e9ample shows how you can Nstac-N the contents of a cell so that the indi*idual characters are printed one under another in the top left corner of the cell. The characters are not rotated.
"i# "o' $s 3b:e'( "i# S&ee( $s 3b:e'( "i# 7e++ $s 3b:e'( "o' = T&is7o#ponen( S&ee( = "o'1S&ee(s(D) 7e++ = S&ee(1ge(7e++2.Mosi(ion(1<1) 7e++14 +ue = 1DDD 7e++1BoriWus(i). = 'o#1sun1s( r1( b+e17e++BoriWus(i).1LE8T 7e++14er(Wus(i). = 'o#1sun1s( r1( b+e17e++4er(Wus(i).1T3M 7e++13rien( (ion = 'o#1sun1s( r1( b+e17e++3rien( (ion1ST$7VE"
Number5 0ate a%d !e1t 3ormat

#pen#ffice.org pro*ides a whole range of predefined date and time formats. 6ach of these formats has an internal number that is used to assign the format to cells using the 5u#ber8or# ( property. #pen#ffice.org pro*ides the ?uer.Ve. and --5e0 methods so that you can access e9isting number formats as well as create your own number formats. The methods are accessed through the following object call:
5u#ber8or# (s = "o'15u#ber8or# (s
" format is specified using a format string that is structured in a similar way to the format function of #pen#ffice.org $asic. 7owe*er there is one major difference: whereas the command format e9pects 6nglish abbre*iations and decimal points or characters as thousands separators< the countryGspecified abbre*iations must be used for the structure of a command format for the 5u#ber8or# (s object. The following e9ample formats the $! cell so that numbers are displayed with three decimal places and use commas as a thousands separator.
"i# "o' $s 3b:e'( "i# S&ee( $s 3b:e'( "i# 7e++ $s 3b:e'(
10/
"i# "i# "i# "i#
5u#ber8or# (s $s 3b:e'( 5u#ber8or# (S(ring $s S(ring 5u#ber8or# (6- $s Long Lo' +Se((ings $s 5e0 'o#1sun1s( r1+ ng1Lo' +e
"o' = T&is7o#ponen( S&ee( = "o'1S&ee(s(D) 7e++ = S&ee(1ge(7e++2.Mosi(ion(1<1) 7e++14 +ue = 234DD13523565 Lo' +Se((ings1L ngu ge = @en@ Lo' +Se((ings17oun(r. = @us@ 5u#ber8or# (s = "o'15u#ber8or# (s 5u#ber8or# (S(ring = @J<JJD1DDD@ 5u#ber8or# (6- = 5u#ber8or# (s1?uer.Ve.(5u#ber8or# (S(ring< Lo' +Se((ings< True) 6) 5u#ber8or# (6- = H1 T&en 5u#ber8or# (6- = 5u#ber8or# (s1 --5e0(5u#ber8or# (S(ring< Lo' +Se((ings) En- 6) Asg2ox 5u#ber8or# (67e++15u#ber8or# ( = 5u#ber8or# (6-
The =orma >e##s dialog in #pen#ffice.org alc pro*ides an o*er*iew of the different formatting options for cells.
Page Properties
Page properties are the formatting options that position document content on a page as well as *isual elements that are repeated page after page. These include

Paper formats Page margins 7eaders and footers.
The procedure for defining page formats differs from other forms of formatting. ,hereas cell< paragraph< and character elements can be formatted directly< page formats can also be defined and indirectly applied using page styles. 5or e9ample< headers or footers are added to the page style. The following sections describe the main formatting options for spreadsheet pages. )any of the styles that are described are also a*ailable for te9t documents. The page properties that are *alid for both types of documents are defined in the com.sun.star.style.PageProperties ser*ice. The page properties that only apply to spreadsheet documents are defined in the com.sun.star.sheet.TablePageStyle ser*ice. Note VBA : The page properties :page margins< borders< and so on; for a )icrosoft #ffice document are defined by means of a M geSe(up object at the Cor/s&ee( object :69cel; or "o'u#en( object :,ord; le*el. &n #pen#ffice.org< these properties are defined using a page style which in turn is lin-ed to the associated document.
Page Bac,grou%d
The com.sun.star.style.PageProperties ser*ice defines the following properties of a pages bac-ground:
Bac'Color (long)
color of bac-ground
Bac'+raphicU$L (String)
'@L of the bac-ground graphics that you want to use

Bac'+raphic-ilter (String)
name of the filter for interpreting the bac-ground graphics
107
Bac'+raphicLocation (0num)
position of the bac-ground graphics :*alue according to enumeration;

Bac')ransparent (Boolean)
ma-es the bac-ground transparent
Page 3ormat
The page format is defined using the following properties of the com.sun.star.style.PageProperties ser*ice:
IsLan%scape (Boolean)
landscape format
Wi%th (long)
width of page in hundredths of a millimeter

(eight (long)
height of page in hundredths of a millimeter

2rinter2aper)ra (String)
name of the printer paper tray that you want to use The following e9ample sets the page siBe of the NDefaultN page style to the D&0 "4 landscape format :height /8.( cm< width !/ cm;:
"i# "i# "i# "i# "i# "o' $s 3b:e'( S&ee( $s 3b:e'( S(.+e8 #i+ies $s 3b:e'( M geS(.+es $s 3b:e'( "e)M ge $s 3b:e'(
"o' = T&is7o#ponen( S(.+e8 #i+ies = "o'1S(.+e8 #i+ies M geS(.+es = S(.+e8 #i+ies1ge(2.5 #e(@M geS(.+es@) "e)M ge = M geS(.+es1ge(2.5 #e(@"e) u+(@) "e)M ge16sL n-s' pe = True "e)M ge1Ci-(& = 21DDD "e)M ge1Beig&( = 148DD
Page (argi%5 Border5 a%d 2hado+

The com.sun.star.style.PageProperties ser*ice pro*ides the following properties for adjusting page margins as well as borders and shadows:
Le!t"argin (long)
width of the left hand page margin in hundredths of a millimeter

$ight"argin (long)
width of the right hand page margin in hundredths of a millimeter

)op"argin (long)
width of the top page margin in hundredths of a millimeter

Bottom"argin (long)
width of the bottom page margin in hundredths of a millimeter

Le!tBor%er (struct)
specifications for leftGhand line of page border :com.sun.star.table.$orderLine structure;

$ightBor%er (struct)
specifications for rightGhand line of page border :com.sun.star.table.$orderLine structure;
100
)opBor%er (struct)
specifications for top line of page border :com.sun.star.table.$orderLine structure;

BottomBor%er (struct)
specifications for bottom line of page border :com.sun.star.table.$orderLine structure;

Le!tBor%erDistance (long)
distance between leftGhand page border and page content in hundredths of a millimeter
$ightBor%erDistance (long)
distance between rightGhand page border and page content in hundredths of a millimeter
)opBor%erDistance (long)
distance between top page border and page content in hundredths of a millimeter
BottomBor%erDistance (long)
distance between bottom page border and page content in hundredths of a millimeter
Sha%o*-ormat (struct)
specifications for shadow of content area of page :com.sun.star.table.Shadow5ormat structure; The following e9ample sets the left and rightGhand borders of the NDefaultN page style to / centimeter.
"i# "i# "i# "i# "i# "o' $s 3b:e'( S&ee( $s 3b:e'( S(.+e8 #i+ies $s 3b:e'( M geS(.+es $s 3b:e'( "e)M ge $s 3b:e'(
"o' = T&is7o#ponen( S(.+e8 #i+ies = "o'1S(.+e8 #i+ies M geS(.+es = S(.+e8 #i+ies1ge(2.5 #e(@M geS(.+es@) "e)M ge = M geS(.+es1ge(2.5 #e(@"e) u+(@) "e)M ge1Le)(A rgin = 1DDD "e)M ge1,ig&(A rgin = 1DDD
Headers a%d 3ooters

The headers and footers of a document form part of the page properties and are defined using the com.sun.star.style.PageProperties ser*ice. The properties for formatting headers are:
(ea%erIs.n (Boolean)
header is acti*ated
(ea%erLe!t"argin (long)
distance between header and leftGhand page margin in hundredths of a millimeter

(ea%er$ight"argin (long)
distance between header and rightGhand page margin in hundredths of a millimeter

(ea%erBo% Distance (long)
distance between header and main body of document in hundredths of a millimeter

(ea%er(eight (long)
height of header in hundredths of a millimeter

(ea%erIsD namic(eight (Boolean)
height of header is automatically adapted to content

(ea%erLe!tBor%er (struct)
details of the leftGhand border of frame around header :com.sun.star.table.$orderLine structure;
109
(ea%er$ightBor%er (struct)
details of the rightGhand border of frame around header :com.sun.star.table.$orderLine structure;

(ea%er)opBor%er (struct)
details of the top line of the border around header :com.sun.star.table.$orderLine structure;
(ea%erBottomBor%er (struct)
details of the bottom line of the border around header :com.sun.star.table.$orderLine structure;
(ea%erLe!tBor%erDistance (long)
distance between leftGhand border and content of header in hundredths of a millimeter

(ea%er$ightBor%erDistance (long)
distance between rightGhand border and content of header in hundredths of a millimeter

(ea%er)opBor%erDistance (long)
distance between top border and content of header in hundredths of a millimeter

(ea%erBottomBor%erDistance (long)
distance between bottom border and content of header in hundredths of a millimeter

(ea%erIsShare% (Boolean)
headers on e*en and odd pages ha*e the same content :refer to Be -erTex( < Be -erTex(Le)(< and
Be -erTex(,ig&( ; (ea%erBac'Color (long)
bac-ground color of header

(ea%erBac'+raphicU$L (String)

(ea%erBac'+raphic-ilter (String)
name of the filter for interpreting the bac-ground graphics for the header
(ea%erBac'+raphicLocation (0num)
position of the bac-ground graphics for the header :*alue according to com.sun.star.style.DraphicLocation enumeration;
(ea%erBac')ransparent (Boolean)
shows the bac-ground of the header as transparent

(ea%erSha%o*-ormat (struct)
details of shadow of header :com.sun.star.table.Shadow5ormat structure; The properties for formatting footers are:
-ooterIs.n (Boolean)
footer is acti*ated
-ooterLe!t"argin (long)
distance between footer and leftGhand page margin in hundredths of a millimeter

-ooter$ight"argin (long)
distance between footer and rightGhand page margin in hundredths of a millimeter

-ooterBo% Distance (long)
distance between footer and main body of document in hundredths of a millimeter

-ooter(eight (long)
height of footer in hundredths of a millimeter
110
-ooterIsD namic(eight (Boolean)
height of footer is adapted automatically to the content

-ooterLe!tBor%er (struct)
details of leftGhand line of border around footer :com.sun.star.table.$orderLine structure;

-ooter$ightBor%er (struct)
details of rightGhand line of border around footer :com.sun.star.table.$orderLine structure;

-ooter)opBor%er (struct)
details of top line of border around footer :com.sun.star.table.$orderLine structure;

-ooterBottomBor%er (struct)
details of bottom line of border around footer :com.sun.star.table.$orderLine structure;

-ooterLe!tBor%erDistance (long)
distance between leftGhand border and content of footer in hundredths of a millimeter

-ooter$ightBor%erDistance (long)
distance between rightGhand border and content of footer in hundredths of a millimeter

-ooter)opBor%erDistance (long)
distance between top border and content of footer in hundredths of a millimeter

-ooterBottomBor%erDistance (long)
distance between bottom border and content of footer in hundredths of a millimeter

-ooterIsShare% (Boolean)
the footers on the e*en and odd pages ha*e the same content :refer to 8oo(erTex(< 8oo(erTex(Le)(< and 8oo(erTex(,ig&( ;
-ooterBac'Color (long)
bac-ground color of footer

-ooterBac'+raphicU$L (String)

-ooterBac'+raphic-ilter (String)
name of the filter for interpreting the bac-ground graphics for the footer
-ooterBac'+raphicLocation (0num)
position of bac-ground graphics for the footer :*alue according to com.sun.star.style.DraphicLocation enumeration;
-ooterBac')ransparent (Boolean)
shows the bac-ground of the footer as transparent

-ooterSha%o*-ormat (struct)
details of shadow of footer :com.sun.star.table.Shadow5ormat structure;
Cha%gi%g the !e1t of Headers a%d 3ooters

The content of headers and footers in a spreadsheet is accessed through the following properties:
Le!t2age(ea%erContent (.b6ect)
content of headers for e*en pages :com.sun.star.sheet.7eader5ooter ontent ser*ice;

$ight2age(ea%erContent (.b6ect)
content of headers for odd pages :com.sun.star.sheet.7eader5ooter ontent ser*ice;
111
Le!t2age-ooterContent (.b6ect)
content of footers for e*en pages :com.sun.star.sheet.7eader5ooter ontent ser*ice;

$ight2age-ooterContent (.b6ect)
content of footers for odd pages :com.sun.star.sheet.7eader5ooter ontent ser*ice; &f you do not need to distinguish between headers or footers for odd and e*en pages :the 8oo(er6sS& reproperty is 8 +se;< then set the properties for headers and footers on odd pages. "ll the named objects return an object that supports the com.sun.star.sheet.7eader5ooter ontent ser*ice. $y means of the :nonGgenuine; properties Le)(Tex(< 7en(erTex(< and ,ig&(Tex(< this ser*ice pro*ides three te9t elements for the headers and footers of #pen#ffice.org alc. The following e9ample writes the N=ust a Test.N *alue in the leftGhand te9t field of the header from the NDefaultN template.
"i# "o' $s 3b:e'( "i# S&ee( $s 3b:e'( "i# S(.+e8 #i+ies $s 3b:e'( "i# M geS(.+es $s 3b:e'( "i# "e)M ge $s 3b:e'( "i# BTex( $s 3b:e'( "i# B7on(en( $s 3b:e'( "o' = T&is7o#ponen( S(.+e8 #i+ies = "o'1S(.+e8 #i+ies M geS(.+es = S(.+e8 #i+ies1ge(2.5 #e(@M geS(.+es@) "e)M ge = M geS(.+es1ge(2.5 #e(@"e) u+(@) "e)M ge1Be -er6s3n = True B7on(en( = "e)M ge1,ig&(M geBe -er7on(en( BTex( = B7on(en(1Le)(Tex( BTex(1S(ring = @Wus( Tes(1@ "e)M ge1,ig&(M geBe -er7on(en( = B7on(en(
0ote the last line in the e9ample: #nce the te9t is changed< the Tex(7on(en( object must be assigned to the header again so that the change is effecti*e. "nother mechanism for changing the te9t of headers and footers is a*ailable for te9t documents :#pen#ffice.org ,riter; because these consist of a single bloc- of te9t. The following properties are defined in the com.sun.star.style.PageProperties ser*ice:
(ea%er)e1t (.b6ect)
te9t object with content of the header :com.sun.star.te9t.XTe9t ser*ice;

(ea%er)e1tLe!t (.b6ect)
te9t object with content of headers on leftGhand pages :com.sun.star.te9t.XTe9t ser*ice;

(ea%er)e1t$ight (.b6ect)
te9t object with content of headers on rightGhand pages :com.sun.star.te9t.XTe9t ser*ice;

-ooter)e1t (.b6ect)
te9t object with content of the footer :com.sun.star.te9t.XTe9t ser*ice;

-ooter)e1tLe!t (.b6ect)
te9t object with content of footers on leftGhand pages :com.sun.star.te9t.XTe9t ser*ice;

-ooter)e1t$ight (.b6ect)
te9t object with content of footers on rightGhand pages :com.sun.star.te9t.XTe9t ser*ice; The following e9ample creates a header in the NDefaultN page style for te9t documents and adds the te9t N=ust a TestN to the header.
"i# "i# "i# "i# "i# "i# "o' $s 3b:e'( S&ee( $s 3b:e'( S(.+e8 #i+ies $s 3b:e'( M geS(.+es $s 3b:e'( "e)M ge $s 3b:e'( BTex( $s 3b:e'(
11"
"o' = T&is7o#ponen( S(.+e8 #i+ies = "o'1S(.+e8 #i+ies M geS(.+es = S(.+e8 #i+ies1ge(2.5 #e(@M geS(.+es@) "e)M ge = M geS(.+es1ge(2.5 #e(@"e) u+(@) "e)M ge1Be -er6s3n = True BTex( = "e)M ge1Be -erTex( BTex(1S(ring = @Wus( Tes(1@
&n this instance< access is pro*ided directly through the Be -erTex( property of the page style rather than the Be -er8oo(er7on(en( object.
Ce%teri%g 92preadsheets O%/y:

The com.sun.star.sheet.TablePageStyle ser*ice is only used in #pen#ffice.org alc page styles and allows cell ranges that you want printed to be centered on the page. This ser*ice pro*ides the following properties:
Center(ori4ontall (Boolean)
table content is centered horiBontally

CenterVerticall (Boolean)
table content is centered *ertically
0efi%itio% of "/eme%ts to be Pri%ted 92preadsheets O%/y:

,hen you format sheets< you can define whether page elements are *isible. 5or this purpose< the com.sun.star.sheet.TablePageStyle ser*ice pro*ides the following properties:
2rintAnnotations (Boolean)
prints cell comments

2rint+ri% (Boolean)
prints the cell gridlines

2rint(ea%ers (Boolean)
prints the row and column headings

2rintCharts (Boolean)
prints charts contained in a sheet

2rint.b6ects (Boolean)
prints embedded objects

2rintDra*ing (Boolean)
prints draw objects

2rintDo*n-irst (Boolean)
if the contents of a sheet e9tend across se*eral pages< they are first printed in *ertically descending order< and then down the rightGhand side.
2rint-ormulas (Boolean)
prints the formulas instead of the calculated *alues

2rint9eroValues (Boolean)
prints the Bero *alues
113
3diting !preads&eet 6ocuments
"diti%g 2preadsheet 0ocume%ts

,hereas the pre*ious section described the main structure of spreadsheet documents< this section describes the ser*ices that allow you to easily access indi*idual cells or cell ranges.
Ce// #a%ges
&n addition to an object for indi*idual cells :com.sun.star.table. ell ser*ice;< #pen#ffice.org also pro*ides objects that represent cell ranges. Such 7e++, nge objects are created using the ge(7e++, nge2.5 #e call of the spreadsheet object:
"i# "o' $s 3b:e'( "i# S&ee( $s 3b:e'( "i# 7e++, nge $s 3b:e'( "o' = T&is7o#ponen( S&ee( = "o'1S&ee(s1ge(2.5 #e(@S&ee( 1@) 7e++, nge = S&ee(1ge(7e++, nge2.5 #e(@$1!715@)
" colon ::; is used to specify a cell range in a spreadsheet document. 5or e9ample< "/: /4 represents all the cells in rows / to /4 in columns "< $< and . &f the position of the cell range is only -nown at runtime< use the following code:
"i# "o' $s 3b:e'( "i# S&ee( $s 3b:e'( "i# 7e++, nge $s 3b:e'( "o' = T&is7o#ponen( S&ee( = "o'1S&ee(s1ge(2.5 #e(@S&ee( 1@) 7e++, nge = S&ee(1ge(7e++, nge2.Mosi(ion(D< D<
2< 14)
The arguments of ge(7e++, nge2.Mosi(ion are the position of the upper left cell of the range< followed by the position of the bottom right cell of the same range. The location of indi*idual cells in a cell range can be determined using the ge(7e++2.Mosi(ion method< where the coordinates of the top left cell in the cell range is :3< 3;. The following e9ample uses this method to create an object of cell 1.
"i# "i# "i# "i# "o' $s 3b:e'( S&ee( $s 3b:e'( 7e++, nge $s 3b:e'( 7e++ $s 3b:e'(
"o' = T&is7o#ponen( S&ee( = "o'1S&ee(s1ge(2.5 #e(@S&ee( 1@) 7e++, nge = S&ee(1ge(7e++, nge2.5 #e(@22!"4@) 7e++ = 7e++, nge1Ge(7e++2.Mosi(ion(1< 1)
3ormatti%g Ce// #a%ges

=ust li-e indi*idual cells< you can apply formatting to cell ranges using the com.sun.star.table. ellProperties ser*ice. 5or more information and e9amples of this ser*ice< see 5ormatting Spreadsheet Documents.
Computi%g -ith Ce// #a%ges

You can use the 'o#pu(e8un'(ion method to perform mathematical operations on cell ranges. The 'o#pu(e8un'(ion e9pects a constant as the parameter that describes the mathematical function that you want to use. The associated constants are defined in the com.sun.star.sheet.Deneral5unction enumeration. The following *alues are a*ailable:
SU"
sum of all numerical *alues
114
C.UN)
total number of all *alues :including nonGnumerical *alues;

C.UN)NU"S
total number of all numerical *alues

AV0$A+0
a*erage of all numerical *alues

"A8
largest numerical *alue

"IN
smallest numerical *alue

2$.DUC)
product of all numerical *alues

S)D0V
standard de*iation
VA$
*ariance
S)D0V2
standard de*iation based on the total population

VA$2
*ariance based on the total population The following e9ample computes the a*erage *alue of the $1!73 range and prints the result in a message bo9:
"i# "o' $s 3b:e'( "i# S&ee( $s 3b:e'( "i# 7e++, nge $s 3b:e'( "o' = T&is7o#ponen( S&ee( = "o'1S&ee(s1ge(2.5 #e(@S&ee( 1@) 7e++, nge = S&ee(1ge(7e++, nge2.5 #e(@$1!73@) Asg2ox 7e++, nge1'o#pu(e8un'(ion('o#1sun1s( r1s&ee(1Gener +8un'(ion1$4E,$GE)
-ar%i%g 5unctions ."@< ."@P< STD.6@P return an incorrect *alue when applied to a properly defined range. See &ssue !!2!4 .
0e/eti%g Ce// Co%te%ts

The '+e r7on(en(s method simplifies the process of deleting cell contents and cell ranges in that it deletes one specific type of content from a cell range. The following e9ample remo*es all the strings and the direct formatting information from the 22!73 range.
"i# "i# "i# "i# "o' $s 3b:e'( S&ee( $s 3b:e'( 7e++, nge $s 3b:e'( 8+ gs $s Long
"o' = T&is7o#ponen( S&ee( = "o'1S&ee(s(D) 7e++, nge = S&ee(1ge(7e++, nge2.5 #e(@22!73@) 8+ gs = 'o#1sun1s( r1s&ee(17e++8+ gs1ST,65G + _ 'o#1sun1s( r1s&ee(17e++8+ gs1B$,"$TT,
11-
7e++, nge1'+e r7on(en(s(8+ gs)
The flags specified in '+e r7on(en(s come from the com.sun.star.sheet. ell5lags constants list. This list pro*ides the following elements:
VALU0
numerical *alues that are not formatted as date or time

DA)0)I"0
numerical *alues that are formatted as date or time

S)$IN+
strings
ANN.)A)I.N
comments that are lin-ed to cells

-.$"ULA
formulas
(A$DA))$
direct formatting of cells

S)&L0S
indirect formatting
.B/0C)S
drawing objects that are connected to cells

0DI)A))$
character formatting that only applies to parts of the cells You can also add the constants together to delete different information using a call from '+e r7on(en(s.
2earchi%g a%d #ep/aci%g Ce// Co%te%ts

Spreadsheet documents< li-e te9t documents< pro*ide a function for searching and replacing. The descriptor objects for searching and replacing in spreadsheet documents are not created directly through the document object< but rather through the S&ee(s list. The following is an e9ample of a search and replace process:
"i# "i# "i# "i# "o' $s 3b:e'( S&ee( $s 3b:e'( ,ep+ 'e"es'rip(or $s 3b:e'( 6 $s 6n(eger
"o' = T&is7o#ponen( S&ee( = "o'1S&ee(s(D) ,ep+ 'e"es'rip(or = S&ee(1're (e,ep+ 'e"es'rip(or() ,ep+ 'e"es'rip(or1Se r'&S(ring = @is@ ,ep+ 'e"es'rip(or1,ep+ 'eS(ring = @0 s@ 8or 6 = D (o "o'1S&ee(s17oun( H 1 S&ee( = "o'1S&ee(s(6) S&ee(1,ep+ 'e$++(,ep+ 'e"es'rip(or) 5ex( 6
This e9ample uses the first page of the document to create a ,ep+ 'e"es'rip(or and then applies this to all pages in a loop.
11/
C H
P ! " #
(ra'ings and Presentations
This chapter pro*ides an introduction to the macroGcontrolled creation and editing of drawings and presentations. The first section describes the structure of drawings< including the basic elements that contain drawings. The second section addresses more comple9 editing functions< such as grouping< rotating< and scaling objects. The third section deals with presentations. &nformation about creating< opening< and sa*ing drawings can be found in ,or-ing ,ith Documents.
!he 2tructure of 0ra+i%gs

Pages
!ip 4 " Draw :or &mpress; document is composed of pages< also called slides. ,hat is written here also applies to &mpress documents. #pen#ffice.org does not limit the number of pages in a drawing document. You can design each page separately. There is also no limit to the number of drawing elements that you can add to a page. The pages of a drawing document are a*ailable through the "r 0M ges container. You can access indi*idual pages either through their number or their name. &f a document has one page and this is called /#%de 1< then the following e9amples are identical. :xamp#e 1: access .( mea$s o" )e $!m.er ;$!m.er%$g .eg%$s -% ) 0<
"i# "o' $s 3b:e'( "i# M ge $s 3b:e'( "o' = T&is7o#ponen( M ge = "o'1"r 0M ges(D)
Note The e9pression "o'1"r 0M ges(D) is a $asic simplification of the "P& call :
"o'1ge("r 0M ges1ge(2.6n-ex(D)
:xamp#e 2: access .( mea$s o" )e $ame

"i# "o' $s 3b:e'( "i# M ge $s 3b:e'( "o' = T&is7o#ponen(
117
'&e !tructure of 6ra$ings
M ge = "o'1"r 0M ges1ge(2.5 #e(@S+i-e 1@)
&n 69ample /< the page is accessed by its number :counting begins at 3;. &n the second e9ample< the page is accessed by its name and the ge(2.5 #e method.
Properties of a page
The preceding call returns a page object that supports the 'o#1sun1s( r1-r 0ing1"r 0M ge ser*ice. The ser*ice recogniBes the following properties:
Bor%erLe!t (Long)
leftGhand border in hundredths of a millimeter

Bor%er$ight (Long)
rightGhand border in hundredths of a millimeter

Bor%er)op (Long)
top border in hundredths of a millimeter

Bor%erBottom (Long)
bottom border in hundredths of a millimeter

Wi%th (Long)
page width in hundredths of a millimeter

(eight (Long)
page height in hundredths of a millimeter

Number (Short)
number of pages :numbering begins at /;< readGonly

.rientation (0num)
page orientation :in accordance with 'o#1sun1s( r1*ie01M per3rien( (ion enumeration; &f these settings are changed< then a## of the pages in the document are affected. The following e9ample sets the page siBe of a drawing document which has just been opened to !3 9 !3 centimeters with a page margin of 3.4 centimeters:
"i# "o' $s 3b:e'( "i# M ge $s 3b:e'( "o' = T&is7o#ponen( M ge = "o'1"r 0M ges(D) M M M M ge12or-erLe)( = 5DD ge12or-er,ig&( = 5DD ge12or-erTop = 5DD ge12or-er2o((o# = 5DD
M ge1Ci-(& = 2DDDD M ge1Beig&( = 2DDDD
#e%ami%g Pages
-ar%i%g &f a new page is inserted in a drawing document of se*eral pages< all subse?uent pages which ha*e $o been renamed will automatically see their default name change< e.g. /#%de 3 will be changed into /#%de 4< etc. This automatic renaming wor-s also in re*erse when a page is deleted. The only way to ha*e a fi9ed page name is to rename the page< by the user interface or by programming. " page pro*ides methods ge(5 #e and se(5 #e to read and modify its name. $asic can handle both methods li-e a property 5 #e. 7ere we rename the first page of the drawing document.
110
"i# "o' $s 3b:e'( "i# M ge $s 3b:e'( "o' = T&is7o#ponen( M ge = "o'1"r 0M ges(D) M ge15 #e = @8irs(@
Creati%g a%d 0e/eti%g Pages

The "r 0M ges container of a -r 0ing document is also used to create and delete indi*idual pages. The following e9ample uses the & s2.5 #e method to chec- if a page called 6(+age e9ists. &f it does< the method determines a corresponding object reference by using the ge(2.5 #e method and then sa*es the reference in a *ariable in M ge. &f the corresponding page does not e9ist< it is created and inserted in the drawing document by the inser(5e02.6n-ex method. The argument of the method is the position< counted from 3< of the existing page after which the new page will be inserted. Then the new page is renamed.
"i# "o' $s 3b:e'( "i# M ge $s 3b:e'( "o' = T&is7o#ponen( 6) "o'1"r 0p ges1& s2.5 #e(@A.M ge@) T&en M ge = "o'1"r 0p ges1ge(2.5 #e(@A.M ge@) E+se M ge = "o'1"r 0p ges1inser(5e02.6n-ex(2) M ge15 #e = @A.M ge@ % .ou s&ou+- +0 .s ren #e ne0 p ge % A.M ge is (&e )our(& p ge o) (&e -o'u#en(< i1e1 posi(ion 3 En- 6)
The & s2.5 #e and ge(2.5 #e methods are obtained from the com.sun.star.container.X0ame"ccess interface. The inser(5e02.6n-ex method is obtained from the com.sun.star.drawing.XDrawPages interface. The same interface pro*ides the method re#o*e to delete :remo*e; a page:
"i# "o' $s 3b:e'( "o' = T&is7o#ponen( 6) "o'1"r 0p ges1& s2.5 #e(@A.M ge@) T&en M ge = "o'1"r 0p ges1ge(2.5 #e(@A.M ge@) "o'1"r 0p ges1re#o*e(M ge) En- 6)
0up/icati%g a Page
" copy of a gi*en page is created< not from the DrawPages container< but from the drawing document itself with the method -up+i' (e. The copy is created at the ne9t position after the original page< with a default name.
"i# "o' $s 3b:e'( "i# M ge $s 3b:e'(< 7+one-M ge $s 3b:e'( "o' = T&is7o#ponen( M ge = "o'1"r 0p ges1ge(2.5 #e(@A.M ge@) 7+one-M ge = "o'1-up+i' (e(M ge) 7+one-M ge15 #e = @A.7op.@ % .ou s&ou+- +0 .s ren #e
ne0 p ge
(o*i%g a Page
The "P& does not pro*ide a method to change the position of a page inside a drawing document.
%&apter 0 6ra$ings and Presentations
119
"/eme%tary Properties of 0ra+i%g Ob8ects

Drawing objects include shapes :rectangles< circles< and so on;< lines< and te9t objects. "ll of these share a number of common features and support the 'o#1sun1s( r1-r 0ing1S& pe ser*ice. This ser*ice defines the SiXe and Mosi(ion properties of a drawing object. #pen#ffice.org $asic also offers se*eral other ser*ices through which you can modify such properties< as formatting or apply fills. The formatting options that are a*ailable depend on the type of drawing object. The following e9ample creates and inserts a rectangle in a drawing document:
"i# "i# "i# "i# "i# "o' $s 3b:e'( M ge $s 3b:e'( ,e'( ng+eS& pe $s 3b:e'( Moin( $s 5e0 'o#1sun1s( r1 0(1Moin( SiXe $s 5e0 'o#1sun1s( r1 0(1SiXe
"o' = T&is7o#ponen( M ge = "o'1"r 0M ges(D) Moin(1x = 1DDD Moin(1. = 1DDD SiXe1Ci-(& = 1DDDD SiXe1Beig&( = 1DDDD ,e'( ng+eS& pe = "o'1're (e6ns( n'e(@'o#1sun1s( r1-r 0ing1,e'( ng+eS& pe@) ,e'( ng+eS& pe1SiXe = SiXe ,e'( ng+eS& pe1Mosi(ion = Moin( M ge1 --(,e'( ng+eS& pe)
The Moin( and SiXe structures with the point of origin :left hand corner; and the siBe of the drawing object are then initialiBed. The lengths are specified in hundredths of a millimeter. The program code then uses the "o'1're (e6ns( n'e call to create the rectangle drawing object as specified by the com.sun.star.drawing.@ectangleShape ser*ice. "t the end< the drawing object is assigned to a page using a M ge1 -- call.
3i// Properties
This section describes four ser*ices and in each instance the sample program code uses a rectangle shape element that combines se*eral types of formatting. 5ill properties are combined in the com.sun.star.drawing.5illProperties ser*ice. #pen#ffice.org recogniBes four main types of formatting for a fill area. The simplest *ariant is a singleG color fill. The options for defining color gradients and hatches let you create other colors into play. The fourth *ariant is the option of projecting e9isting graphics into the fill area. The fill mode of a drawing object is defined using the 8i++S(.+e property. The permissible *alues are defined in com.sun.star.drawing.5illStyle.
2i%g/e Co/or 3i//s

The main property for singleGcolor fills is:
-illColor (Long)
fill color of area To use the fill mode< you must the 8i++S(.+e property to the S3L6" fill mode. The following e9ample creates a rectangle shape and fills it with red :@D$ *alue !44< 3< 3;:
"i# "o' $s 3b:e'( "i# M ge $s 3b:e'(
1"0
"i# ,e'( ng+eS& pe $s 3b:e'( "i# Moin( $s 5e0 'o#1sun1s( r1 0(1Moin( "i# SiXe $s 5e0 'o#1sun1s( r1 0(1SiXe Moin(1x = 1DDD Moin(1. = 1DDD SiXe1Ci-(& = 1DDDD SiXe1Beig&( = 1DDDD "o' = T&is7o#ponen( M ge = "o'1"r 0M ges(D) ,e'( ng+eS& pe = "o'1're (e6ns( n'e(@'o#1sun1s( r1-r 0ing1,e'( ng+eS& pe@) ,e'( ng+eS& pe1SiXe = SiXe ,e'( ng+eS& pe1Mosi(ion = Moin( ,e'( ng+eS& pe18i++S(.+e = 'o#1sun1s( r1-r 0ing18i++S(.+e1S3L6" ,e'( ng+eS& pe18i++7o+or = ,G2(255<D<D) M ge1 --(,e'( ng+eS& pe)
Co/or Gradie%t
&f you set the 8i++S(.+e property to G,$"6E5T< you can apply a color gradient to any fill area of a #pen#ffice.org document. &f you want to apply a predefined color gradient< you can assign the associated name of the 8i++Tr nsp ren'eGr -ien(5 #e property. To define your own color gradient< you need to complete a com.sun.star.awt.Dradient structure to assign the 8i++Gr -ien( property. This property pro*ides the following options:
St le (0num)
type of gradient< for e9ample< linear or radial :default *alues in accordance with com.sun.star.awt.DradientStyle;
StartColor (Long)
start color of color gradient

0n%Color (Long)
end color of color gradient

Angle (Short)
angle of color gradient in tenths of a degree

8.!!set (Short)
XGcoordinate at which the color gradient starts< specified in hundredths of a millimeter

&.!!set (Short)
YGcoordinate at which the color gradient begins< specified in hundredths of a millimeter

StartIntensit (Short)
intensity of S( r(7o+or as a percentage :in #pen#ffice.org $asic< you can also specify *alues higher than /33 percent;
0n%Intensit (Short)
intensity of En-7o+or as a percentage :in #pen#ffice.org $asic< you can also specify *alues higher than /33 percent;
StepCount (Short)
number of color graduations which #pen#ffice.org is to calculate for the gradients The following e9ample demonstrates the use of color gradients with the aid of the com.sun.star.awt.Dradient structure:
"i# "o' $s 3b:e'( "i# M ge $s 3b:e'(
1"1
"i# "i# "i# "i#
,e'( ng+eS& pe $s 3b:e'( Moin( $s 5e0 'o#1sun1s( r1 0(1Moin( SiXe $s 5e0 'o#1sun1s( r1 0(1SiXe Gr -ien( $s 5e0 'o#1sun1s( r1 0(1Gr -ien(
Moin(1x = 1DDD Moin(1. = 1DDD SiXe1Ci-(& = 1DDDD SiXe1Beig&( = 1DDDD "o' = T&is7o#ponen( M ge = "o'1"r 0M ges(D) ,e'( ng+eS& pe = "o'1're (e6ns( n'e(@'o#1sun1s( r1-r 0ing1,e'( ng+eS& pe@) ,e'( ng+eS& pe1SiXe = SiXe ,e'( ng+eS& pe1Mosi(ion = Moin( Gr -ien(1S(.+e = 'o#1sun1s( r1 0(1Gr -ien(S(.+e1L65E$, Gr -ien(1S( r(7o+or = ,G2(255<D<D) Gr -ien(1En-7o+or = ,G2(D<255<D) Gr -ien(1S( r(6n(ensi(. = 15D Gr -ien(1En-6n(ensi(. = 15D Gr -ien(1$ng+e = 45D Gr -ien(1S(ep7oun( = 1DD ,e'( ng+eS& pe18i++S(.+e = 'o#1sun1s( r1-r 0ing18i++S(.+e1G,$"6E5T ,e'( ng+eS& pe18i++Gr -ien( = Gr -ien( M ge1 --(,e'( ng+eS& pe)
This e9ample creates a linear color gradient :S(.+e = L65E$,;. The gradient starts with red :S( r(7o+or; in the top left corner< and e9tends at a 84 degree angle :$ng+e; to green :En-7o+or; in the bottom right corner. The color intensity of the start and end colors is /43 percent :S( r(6n(ensi(. and En-6n(ensi(.; which results in the colors seeming brighter than the *alues specified in the S( r(7o+or and En-7o+or properties. The color gradient is depicted using a hundred graduated indi*idual colors : S(ep7oun(;.
Hatches
To create a hatch fill< the 8i++S(.+e property must be set to B$T7B. The program code for defining the hatch is *ery similar to the code for color gradients. "gain an au9iliary structure< in this case com.sun.star.drawing.7atch< is used to define the appearance of hatches. The structure for hatches has the following properties:
St le (0num)
type of hatch: simple< s?uared< or s?uared with diagonals :default *alues in accordance with
'o#1sun1s( r1 0(1B ('&S(.+e; Color (Long)
color of lines
Distance (Long)
distance between lines in hundredths of a millimeter

Angle (Short)
angle of hatch in tenths of a degree The following e9ample demonstrates the use of a hatch structure:
"i# "i# "i# "i# "i# "i# "o' $s 3b:e'( M ge $s 3b:e'( ,e'( ng+eS& pe $s 3b:e'( Moin( $s 5e0 'o#1sun1s( r1 0(1Moin( SiXe $s 5e0 'o#1sun1s( r1 0(1SiXe B ('& $s 5e0 'o#1sun1s( r1-r 0ing1B ('&
Moin(1x = 1DDD Moin(1. = 1DDD SiXe1Ci-(& = 1DDDD SiXe1Beig&( = 1DDDD "o' = T&is7o#ponen(
1""
M ge = "o'1"r 0M ges(D) ,e'( ng+eS& pe = "o'1're (e6ns( n'e(@'o#1sun1s( r1-r 0ing1,e'( ng+eS& pe@) ,e'( ng+eS& pe1SiXe = SiXe ,e'( ng+eS& pe1Mosi(ion = Moin( ,e'( ng+eS& pe18i++S(.+e = 'o#1sun1s( r1-r 0ing18i++S(.+e1B$T7B B B B B ('&1S(.+e = 'o#1sun1s( r1-r 0ing1B ('&S(.+e1S65GLE ('&17o+or = ,G2(64<64<64) ('&1"is( n'e = 2D ('&1$ng+e = 45D
,e'( ng+eS& pe18i++B ('& = B ('& M ge1 --(,e'( ng+eS& pe)
This code creates a simple hatch structure :B ('&S(.+e = S65GLE; whose lines are rotated 84 degrees :$ng+e;. The lines are dar- gray :7o+or; and are spaced is 3.! millimeters :"is( n'e; apart.
Bitmaps
To use bitmap projection as a fill< you must set the 8i++S(.+e property to 26TA$M. &f the bitmap is already a*ailable in #pen#ffice.org< you just need to specify its name in the 8i++2i(A p5 #e property and its display style :simple< tiled< or elongated; in the 8i++2i(# pAo-e property :default *alues in accordance with com.sun.star.drawing.$itmap)ode;. &f you want to use an e9ternal bitmap file< you can specify its '@L in the 8i++2i(# pN,L property. The following e9ample creates a rectangle and tiles the S-y bitmap that is a*ailable in #pen#ffice.org to fill the area of the rectangle:
Moin(1x = 1DDD Moin(1. = 1DDD SiXe1Ci-(& = 1DDDD SiXe1Beig&( = 1DDDD "o' = T&is7o#ponen( M ge = "o'1"r 0M ges(D) ,e'( ng+eS& pe = "o'1're (e6ns( n'e(@'o#1sun1s( r1-r 0ing1,e'( ng+eS& pe@) ,e'( ng+eS& pe1SiXe = SiXe ,e'( ng+eS& pe1Mosi(ion = Moin( ,e'( ng+eS& pe18i++S(.+e = 'o#1sun1s( r1-r 0ing18i++S(.+e126TA$M ,e'( ng+eS& pe18i++2i(# p5 #e = @S/.@ ,e'( ng+eS& pe18i++2i(# pAo-e = 'o#1sun1s( r1-r 0ing12i(# pAo-e1,EME$T M ge1 --(,e'( ng+eS& pe)
!ra%spare%cy
You can adjust the transparency of any fill that you apply. The simplest way to change the transparency of a drawing element is to use the 8i++Tr nsp ren'e property. The following e9ample creates a red rectangle with a transparency of 43 percent.
Moin(1x = 1DDD Moin(1. = 1DDD
1"3
SiXe1Ci-(& = 1DDDD SiXe1Beig&( = 1DDDD "o' = T&is7o#ponen( M ge = "o'1"r 0M ges(D) ,e'( ng+eS& pe = "o'1're (e6ns( n'e(@'o#1sun1s( r1-r 0ing1,e'( ng+eS& pe@) ,e'( ng+eS& pe1SiXe = SiXe ,e'( ng+eS& pe1Mosi(ion = Moin( ,e'( ng+eS& pe18i++S(.+e = 'o#1sun1s( r1-r 0ing18i++S(.+e1S3L6" ,e'( ng+eS& pe18i++Tr nsp ren'e = 5D ,e'( ng+eS& pe18i++7o+or = ,G2(255<D<D) M ge1 --(,e'( ng+eS& pe)
To ma-e the fill transparent< set the 8i++Tr nsp ren'e property to /33. &n addition to the 8i++Tr nsp ren'e property< the com.sun.star.drawing.5illProperties ser*ice also pro*ides the 8i++Tr nsp ren'eGr -ien( property. This is used to define a gradient that specifies the transparency of a fill area.
Li%e Properties
"ll drawing objects that can ha*e a border line support the com.sun.star.drawing.LineStyle ser*ice. Some of the properties that this ser*ice pro*ides are:
LineSt le (0num)
line type :default *alues in accordance with com.sun.star.drawing.LineStyle;

LineColor (Long)
line color
Line)ransparence (Short)
line transparency
LineWi%th (Long)
line thic-ness in hundredths of a millimeter

Line/oint (0num)
transitions to connection points :default *alues in accordance with com.sun.star.drawing.Line=oint; The following e9ample creates a rectangle with a solid border :LineS(.+e = S3L6"; that is 4 millimeters thic- :LineCi-(&; and 43 percent transparent. The right and leftGhand edges of the line e9tend to their points of intersect with each other :LineWoin( = A6TE,; to form a rightGangle.
Moin(1x = 1DDD Moin(1. = 1DDD SiXe1Ci-(& = 1DDDD SiXe1Beig&( = 1DDDD "o' = T&is7o#ponen( M ge = "o'1"r 0M ges(D) ,e'( ng+eS& pe = "o'1're (e6ns( n'e(@'o#1sun1s( r1-r 0ing1,e'( ng+eS& pe@) ,e'( ng+eS& pe1SiXe = SiXe ,e'( ng+eS& pe1Mosi(ion = Moin( ,e'( ,e'( ,e'( ,e'( ng+eS& ng+eS& ng+eS& ng+eS& pe1Line7o+or = ,G2(128<128<128) pe1LineTr nsp ren'e = 5D pe1LineCi-(& = 5DD pe1LineWoin( = 'o#1sun1s( r1-r 0ing1LineWoin(1A6TE,
,e'( ng+eS& pe1LineS(.+e = 'o#1sun1s( r1-r 0ing1LineS(.+e1S3L6"
1"4
M ge1 --(,e'( ng+eS& pe)
&n addition to the listed properties< the com.sun.star.drawing.LineStyle ser*ice pro*ides options for drawing dotted and dashed lines. 5or more information< see the #pen#ffice.org "P& reference.
!e1t Properties 90ra+i%g Ob8ects:

The com.sun.star.style. haracterProperties and com.sun.star.style.ParagraphProperties ser*ices can format te9t in drawing objects. These ser*ices relate to indi*idual characters and paragraphs and are described in detail in Te9t Documents. The following e9ample inserts te9t in a rectangle and formats the font com.sun.star.style. haracterProperties ser*ice.
"i# "o' $s 3b:e'( "i# M ge $s 3b:e'( "i# ,e'( ng+eS& pe $s 3b:e'( "i# Moin( $s 5e0 'o#1sun1s( r1 0(1Moin( "i# SiXe $s 5e0 'o#1sun1s( r1 0(1SiXe Moin(1x = 1DDD Moin(1. = 1DDD SiXe1Ci-(& = 1DDDD SiXe1Beig&( = 1DDDD "o' = T&is7o#ponen( M ge = "o'1"r 0M ges(D) ,e'( ng+eS& pe = "o'1're (e6ns( n'e(@'o#1sun1s( r1-r 0ing1,e'( ng+eS& pe@) ,e'( ng+eS& pe1SiXe = SiXe ,e'( ng+eS& pe1Mosi(ion = Moin( M ge1 --(,e'( ng+eS& pe) ,e'( ng+eS& pe1S(ring = @T&is is (es(@ ,e'( ng+eS& pe17& rCeig&( = 'o#1sun1s( r1 0(18on(Ceig&(123L" ,e'( ng+eS& pe17& r8on(5 #e = @$ri +@
This code uses the S(ringGproperty of the rectangle to insert the te9t and the 7& rCeig&( and 7& r8on(5 #e properties from the com.sun.star.style. haracterProperties ser*ice to format the te9t font. The te9t can only be inserted after the drawing object has been added to the drawing page. You can also use the com.sun.star.drawing.Te9t ser*ice to position and format te9t in drawing object. The following are some of the important properties of this ser*ice:
)e1tAuto+ro*(eight (Boolean)
adapts the height of the drawing element to the te9t it contains

)e1tAuto+ro*Wi%th (Boolean)
adapts the width of the drawing element to the te9t it contains

)e1t(ori4ontalA%6ust (0num)
horiBontal position of te9t within the drawing element :default *alues in accordance with com.sun.star.drawing.Te9t7oriBontal"djust;
)e1tVerticalA%6ust (0num)
*ertical position of te9t within the drawing element :default *alues in accordance with com.sun.star.drawing.Te9t.ertical"djust;
)e1tLe!tDistance (Long)
leftGhand distance between drawing element and te9t in hundredths of a millimeter

)e1t$ightDistance (Long)
rightGhand distance between drawing element and te9t in hundredths of a millimeter

)e1tUpperDistance (Long)
upper distance between drawing element and te9t in hundredths of a millimeter

%&apter 0 6ra$ings and Presentations 1"-
)e1tLo*erDistance (Long)
lower distance between drawing element and te9t in hundredths of a millimeter The following e9ample demonstrates use of the named properties.
Moin(1x = 1DDD Moin(1. = 1DDD SiXe1Ci-(& = 1DDDD SiXe1Beig&( = 1DDDD "o' = T&is7o#ponen( M ge = "o'1"r 0M ges(D) ,e'( ng+eS& pe = "o'1're (e6ns( n'e(@'o#1sun1s( r1-r 0ing1,e'( ng+eS& pe@) ,e'( ng+eS& pe1SiXe = SiXe ,e'( ng+eS& pe1Mosi(ion = Moin( M ge1 --(,e'( ng+eS& pe) ,e'( ng+eS& pe1S(ring = @T&is is (es(@ % A . on+. ( /e p+ 'e )(er M ge1 --I
,e'( ng+eS& pe1Tex(4er(i' +$-:us( = 'o#1sun1s( r1-r 0ing1Tex(4er(i' +$-:us(1T3M ,e'( ng+eS& pe1Tex(BoriXon( +$-:us( = 'o#1sun1s( r1-r 0ing1Tex(BoriXon( +$-:us(1LE8T ,e'( ,e'( ,e'( ,e'( ng+eS& ng+eS& ng+eS& ng+eS& pe1Tex(Le)("is( n'e = 3DD pe1Tex(,ig&("is( n'e = 3DD pe1Tex(Npper"is( n'e = 3DD pe1Tex(Lo0er"is( n'e = 3DD
This code inserts a drawing element in a page and then adds te9t to the top left corner of the drawing object using the Tex(4er(i' +$-:us( and Tex(BoriXon( +$-:us( properties. The minimum distance between the te9t edge of the drawing object is set to three millimeters.
2hado+ Properties
You can add a shadow to most drawing objects with the com.sun.star.drawing.ShadowProperties ser*ice. The properties of this ser*ice are:
Sha%o* (Boolean)
acti*ates the shadow

Sha%o*Color (Long)
shadow color
Sha%o*)ransparence (Short)
transparency of the shadow

Sha%o*8Distance (Long)
*ertical distance of the shadow from the drawing object in hundredths of a millimeter
Sha%o*&Distance (Long)
horiBontal distance of the shadow from the drawing object in hundredths of a millimeter The following e9ample creates a rectangle with a shadow that is *ertically and horiBontally offset from the rectangle by ! millimeters. The shadow is rendered in dar- gray with 43 percent transparency.
Moin(1x = 1DDD
1"/
Moin(1. = 1DDD SiXe1Ci-(& = 1DDDD SiXe1Beig&( = 1DDDD "o' = T&is7o#ponen( M ge = "o'1"r 0M ges(D) ,e'( ng+eS& pe = "o'1're (e6ns( n'e(@'o#1sun1s( r1-r 0ing1,e'( ng+eS& pe@) ,e'( ng+eS& pe1SiXe = SiXe ,e'( ng+eS& pe1Mosi(ion = Moin( ,e'( ,e'( ,e'( ,e'( ,e'( ng+eS& ng+eS& ng+eS& ng+eS& ng+eS& pe1S& pe1S& pe1S& pe1S& pe1S& -o0 = True -o07o+or = ,G2(1L2<1L2<1L2) -o0Tr nsp ren'e = 5D -o0R"is( n'e = 2DD -o0Z"is( n'e = 2DD
M ge1 --(,e'( ng+eS& pe)
% O*er*ie+ of .arious 0ra+i%g Ob8ects

#ecta%g/e 2hapes
@ectangle shape objects :com.sun.star.drawing.@ectangleShape; support the following ser*ices for formatting objects:
-ill properties
com.sun.star.drawing.5illProperties
Line properties
com.sun.star.drawing.LineProperties
)e1t properties
com.sun.star.drawing.Te9t :with com.sun.star.style. haracterProperties and com.sun.star.style.ParagraphProperties;

Sha%o* properties
com.sun.star.drawing.ShadowProperties
Corner$a%ius (Long)
radius for rounding corners in hundredths of a millimeter
Circ/es a%d "//ipses

The Ser*ice com.sun.star.drawing.6llipseShape ser*ice is responsible for circles and ellipses and supports the following ser*ices:
-ill properties
Line properties
)e1t properties

Sha%o* properties
com.sun.star.drawing.ShadowProperties &n addition to these ser*ices< circles and ellipses also pro*ide these properties:
1"7
Circle5in% (0num)
type of circle or ellipse :default *alues in accordance with com.sun.star.drawing. irclePind;

CircleStartAngle (Long)
start angle in tenths of a degree :only for circle or ellipse segments;

Circle0n%Angle (Long)
end angle in tenths of a degree :only for circle or ellipse segments; The 7ir'+eVin- property determines if an object is a complete circle< a circular slice< or a section of a circle. The following *alues are a*ailable:
com.sun.star.%ra*ing.Circle5in%.-ULL
full circle or full ellipse

com.sun.star.%ra*ing.Circle5in%.CU)
section of circle :partial circle whose interfaces are lin-ed directly to one another;
com.sun.star.%ra*ing.Circle5in%.S0C)I.N
circle slice
com.sun.star.%ra*ing.Circle5in%.A$C
angle :not including circle line; The following e9ample creates a circular slice with a %3 degree angle :produced from difference between start angle of !3 degrees and end angle of +3 degrees;
"i# "i# "i# "i# "i# "o' $s 3b:e'( M ge $s 3b:e'( E++ipseS& pe $s 3b:e'( Moin( $s 5e0 'o#1sun1s( r1 0(1Moin( SiXe $s 5e0 'o#1sun1s( r1 0(1SiXe
Moin(1x = 1DDD Moin(1. = 1DDD SiXe1Ci-(& = 1DDDD SiXe1Beig&( = 1DDDD "o' = T&is7o#ponen( M ge = "o'1"r 0M ges(D) E++ipseS& pe = "o'1're (e6ns( n'e(@'o#1sun1s( r1-r 0ing1E++ipseS& pe@) E++ipseS& pe1SiXe = SiXe E++ipseS& pe1Mosi(ion = Moin( E++ipseS& pe17ir'+eS( r($ng+e = 2DDD E++ipseS& pe17ir'+eEn-$ng+e = LDDD E++ipseS& pe17ir'+eVin- = 'o#1sun1s( r1-r 0ing17ir'+eVin-1SE7T635 M ge1 --(E++ipseS& pe)
Li%es
#pen#ffice.org pro*ides the com.sun.star.drawing.LineShape ser*ice for line objects. Line objects support all of the general formatting ser*ices with the e9ception of areas. The following are all of the properties that are associated with the LineS& pe ser*ice:
Line properties
)e1t properties

Sha%o* properties
com.sun.star.drawing.ShadowProperties
1"0
The following e9ample creates and formats a line with the help of the named properties. The origin of the line is specified in the Lo' (ion property< whereas the coordinates listed in the SiXe property specify the end point of the line.
"i# "i# "i# "i# "i# "o' $s 3b:e'( M ge $s 3b:e'( LineS& pe $s 3b:e'( Moin( $s 5e0 'o#1sun1s( r1 0(1Moin( SiXe $s 5e0 'o#1sun1s( r1 0(1SiXe
Moin(1x = 1DDD Moin(1. = 1DDD SiXe1Ci-(& = 1DDDD SiXe1Beig&( = 1DDDD "o' = T&is7o#ponen( M ge = "o'1"r 0M ges(D) LineS& pe = "o'1're (e6ns( n'e(@'o#1sun1s( r1-r 0ing1LineS& pe@) LineS& pe1SiXe = SiXe LineS& pe1Mosi(ion = Moin( M ge1 --(LineS& pe)
Po/ypo/ygo% 2hapes
#pen#ffice.org also supports comple9 polygonal shapes through the com.sun.star.drawing.PolyPolygonShape ser*ice. Strictly spea-ing< a PolyPolygon is not a simple polygon but a multiple polygon. Se*eral independent lists containing corner points can therefore be specified and combined to form a complete object. "s with rectangle shapes< all the formatting properties of drawing objects are also pro*ided for polypolygons:
-ill properties
Line properties
)e1t properties

Sha%o* properties
com.sun.star.drawing.ShadowProperties The Mo+.Mo+.gonS& pe ser*ice also has a property that lets you define the coordinates of a polygon:
Mo+.Mo+.gon ($rr .) F field containing the coordinates of the polygon :double array with points of
the com.sun.star.awt.Point type; The following e9ample shows how you can define a triangle with the Mo+.Mo+.gonS& pe ser*ice.
"i# "i# "i# "i# "i# "o' $s 3b:e'( M ge $s 3b:e'( Mo+.Mo+.gonS& pe $s 3b:e'( Mo+.Mo+.gon $s 4 ri n( 7oor-in (es(2) $s 5e0 'o#1sun1s( r1 0(1Moin(
"o' = T&is7o#ponen( M ge = "o'1"r 0M ges(D) Mo+.Mo+.gonS& pe = "o'1're (e6ns( n'e(@'o#1sun1s( r1-r 0ing1Mo+.Mo+.gonS& pe@) M ge1 --(Mo+.Mo+.gonS& pe) % M ge1 -- #us( ( /e p+ 'e be)ore (&e 'oor-in (es 7oor-in 7oor-in 7oor-in 7oor-in 7oor-in (es(D)1x (es(1)1x (es(2)1x (es(D)1. (es(1)1. = = = = = 1DDD 75DD 1DDDD 1DDD 75DD re se(
1"9
7oor-in (es(2)1. = 5DDD Mo+.Mo+.gonS& pe1Mo+.Mo+.gon = $rr .(7oor-in (es())
Since the points of a polygon are defined as absolute *alues< you do not need to specify the siBe or the start position of a polygon. &nstead< you need to create an array of the points< pac-age this array in a second array :using the $rr .(7oor-in (es()) call;< and then assign this array to the polygon. $efore the corresponding call can be made< the polygon must be inserted into the document. The double array in the definition allows you to create comple9 shapes by merging se*eral polygons. 5or e9ample< you can create a rectangle and then insert another rectangle inside it to create a hole in the original rectangle:
"i# "i# "i# "i# "i# "i# "i# "o' $s 3b:e'( M ge $s 3b:e'( Mo+.Mo+.gonS& pe $s 3b:e'( Mo+.Mo+.gon $s 4 ri n( S?u re1(3) $s 5e0 'o#1sun1s( r1 0(1Moin( S?u re2(3) $s 5e0 'o#1sun1s( r1 0(1Moin( S?u re3(3) $s 5e0 'o#1sun1s( r1 0(1Moin(
"o' = T&is7o#ponen( M ge = "o'1"r 0M ges(D) Mo+.Mo+.gonS& pe = "o'1're (e6ns( n'e(@'o#1sun1s( r1-r 0ing1Mo+.Mo+.gonS& pe@) M ge1 --(Mo+.Mo+.gonS& pe) S?u S?u S?u S?u S?u S?u S?u S?u S?u S?u S?u S?u S?u S?u S?u S?u S?u S?u S?u S?u S?u S?u S?u S?u re1(D)1x re1(1)1x re1(2)1x re1(3)1x re1(D)1. re1(1)1. re1(2)1. re1(3)1. re2(D)1x re2(1)1x re2(2)1x re2(3)1x re2(D)1. re2(1)1. re2(2)1. re2(3)1. re3(D)1x re3(1)1x re3(2)1x re3(3)1x re3(D)1. re3(1)1. re3(2)1. re3(3)1. = = = = = = = = = = = = = = = = = = = = = = = = 5DDD 1DDDD 1DDDD 5DDD 5DDD 5DDD 1DDDD 1DDDD 65DD 85DD 85DD 65DD 65DD 65DD 85DD 85DD 65DD 85DD 85DD 65DD LDDD LDDD L5DD L5DD % M ge1 -- #us( ( /e p+ 'e be)ore (&e 'oor-in (es re se(
Mo+.Mo+.gonS& pe1Mo+.Mo+.gon = $rr .(S?u re1()< S?u re2()< S?u re3())
,ith respect as to which areas are filled and which areas are holes< #pen#ffice.org applies a simple rule: the edge of the outer shape is always the outer border of the polypolygon. The ne9t line inwards is the inner border of the shape and mar-s the transition to the first hole. &f there is another line inwards< it mar-s the transition to a filled area.
Graphics
The last of the drawing elements presented here are graphic objects that are based on the com.sun.star.drawing.Draphic#bjectShape ser*ice. These can be used with any graphic within #pen#ffice.org whose appearance can be adapted using a whole range of properties. Draphic objects support two of the general formatting properties:
)e1t properties
com.sun.star.drawing.Te9t :with com.sun.star.style. haracterProperties and

com.sun.star.style.ParagraphProperties;
Sha%o* properties
com.sun.star.drawing.ShadowProperties "dditional properties that are supported by graphic objects are:

+raphicU$L (String)
'@L of the graphic

A%6ustLuminance (Short)
luminance of the colors< as a percentage :negati*e *alues are also permitted;

A%6ustContrast (Short)
contrast as a percentage :negati*e *alues are also permitted;

A%6ust$e% (Short)
red *alue as a percentage :negati*e *alues are also permitted;

A%6ust+reen (Short)
green *alue as a percentage :negati*e *alues are also permitted;

A%6ustBlue (Short)
blue *alue as a percentage :negati*e *alues are also permitted;

+amma (Short)
gamma *alue of a graphic

)ransparenc (Short)
transparency of a graphic as a percentage

+raphicColor"o%e (enum)
color mode< for e9ample< standard< gray stages< blac- and white :default *alue in accordance with com.sun.star.drawing. olor)ode; The following e9ample shows how to insert a page into a graphics object.
"i# "i# "i# "i# "i# "o' $s 3b:e'( M ge $s 3b:e'( Gr p&i'3b:e'(S& pe $s 3b:e'( Moin( $s 5e0 'o#1sun1s( r1 0(1Moin( SiXe $s 5e0 'o#1sun1s( r1 0(1SiXe % spe'i)i' (ions< insigni)i' n( be' use + ((er 'oor-in (es re bin-ing
Moin(1x = 1DDD Moin(1. = 1DDD SiXe1Ci-(& = 1DDDD SiXe1Beig&( = 1DDDD "o' = T&is7o#ponen( M ge = "o'1"r 0M ges(D)
Gr p&i'3b:e'(S& pe = "o'1're (e6ns( n'e(@'o#1sun1s( r1-r 0ing1Gr p&i'3b:e'(S& pe@) Gr p&i'3b:e'(S& pe1SiXe = SiXe Gr p&i'3b:e'(S& pe1Mosi(ion = Moin( Gr Gr Gr Gr Gr Gr Gr Gr p&i'3b:e'(S& p&i'3b:e'(S& p&i'3b:e'(S& p&i'3b:e'(S& p&i'3b:e'(S& p&i'3b:e'(S& p&i'3b:e'(S& p&i'3b:e'(S& pe1Gr p&i'N,L = @)i+e!OOO'!O(es(1:pg@ pe1$-:us(2+ue = H5D pe1$-:us(Green = 5 pe1$-:us(2+ue = 1D pe1$-:us(7on(r s( = 2D pe1$-:us(Lu#in n'e = 5D pe1Tr nsp ren'. = 4D pe1Gr p&i'7o+orAo-e = 'o#1sun1s( r1-r 0ing17o+orAo-e1ST$5"$,"
M ge1 --(Gr p&i'3b:e'(S& pe)
This code inserts the (es(1:pg graphic and adapts its appearance using the $-:us( properties. &n this
131
e9ample< the graphics are depicted as 83 percent transparent with no other color con*ersions do not ta-e place :Gr p&i'7o+orAo-e = ST$5"$,";.
"diti%g 0ra+i%g Ob8ects

Groupi%g Ob8ects
&n many situations< it is useful to group se*eral indi*idual drawing objects together so that they beha*e as a single large object. The following e9ample combines two drawing objects:
"i# "i# "i# "i# "i# "i# "i# "i# "i# "i# "i# "o' $s 3b:e'( M ge $s 3b:e'( S?u re $s 3b:e'( 7ir'+e $s 3b:e'( S& pes $s 3b:e'( Group $s 3b:e'( Moin( $s 5e0 'o#1sun1s( r1 0(1Moin( SiXe $s 5e0 'o#1sun1s( r1 0(1SiXe 5e0Mos $s 5e0 'o#1sun1s( r1 0(1Moin( Beig&( $s Long Ci-(& $s Long
"o' = T&is7o#ponen( M ge = "o'1"r 0M ges(D) Moin(1x = 3DDD Moin(1. = 3DDD SiXe1Ci-(& = 3DDD SiXe1Beig&( = 3DDD % 're (e s?u re -r 0ing e+e#en( S?u re = "o'1're (e6ns( n'e(@'o#1sun1s( r1-r 0ing1,e'( ng+eS& pe@) S?u re1SiXe = SiXe S?u re1Mosi(ion = Moin( S?u re18i++7o+or = ,G2(255<128<128) M ge1 --(S?u re) % 're (e 'ir'+e -r 0ing e+e#en( 7ir'+e = "o'1're (e6ns( n'e(@'o#1sun1s( r1-r 0ing1E++ipseS& pe@) 7ir'+e1SiXe = SiXe 7ir'+e1Mosi(ion = Moin( 7ir'+e18i++7o+or = ,G2(255<128<128) 7ir'+e18i++7o+or = ,G2(D<255<D) M ge1 --(7ir'+e) % 'o#bine s?u re n- 'ir'+e -r 0ing e+e#en(s S& pes = 're (eNnoSer*i'e(@'o#1sun1s( r1-r 0ing1S& pe7o++e'(ion@) S& pes1 --(S?u re) S& pes1 --(7ir'+e) Group = M ge1group(S& pes) % 'en(re 'o#bine- -r 0ing e+e#en(s Beig&( = M ge1Beig&( Ci-(& = M ge1Ci-(& 5e0Mos1R = Ci-(& O 2 5e0Mos1Z = Beig&( O 2 Beig&( = Group1SiXe1Beig&( Ci-(& = Group1SiXe1Ci-(& 5e0Mos1R = 5e0Mos1R H Ci-(& O 2 5e0Mos1Z = 5e0Mos1Z H Beig&( O 2 Group1Mosi(ion = 5e0Mos
This code creates a rectangle and a circle and inserts them into a page. &t then creates an object that supports the com.sun.star.drawing.Shape ollection ser*ice and uses the $-- method to add the rectangle and the circle to this object. The S& pe7o++e'(ion is added to the page using the Group method and returns the actual Group object that can be edited li-e an indi*idual S& pe. &f you want to format the indi*idual objects of a group< apply the formatting before you add them to the
13" LibreOffice 3.4 Basic Programmer's Guide !eptember "011
3diting 6ra$ing Ob:ects
group. You cannot modify the objects once they are in the group.
#otati%g a%d 2heari%g 0ra+i%g Ob8ects

"ll of the drawing objects that are described in the pre*ious sections can also be rotated and sheared using the com.sun.star.drawing.@otationDescriptor ser*ice. The ser*ice pro*ides the following properties:
$otateAngle (Long)
rotary angle in hundredths of a degree

ShearAngle (Long)
shear angle in hundredths of a degree The following e9ample creates a rectangle and rotates it by 13 degrees using the ,o( (e$ng+e property:
Moin(1x = 1DDD Moin(1. = 1DDD SiXe1Ci-(& = 1DDDD SiXe1Beig&( = 1DDDD "o' = T&is7o#ponen( M ge = "o'1"r 0M ges(D) ,e'( ng+eS& pe = "o'1're (e6ns( n'e(@'o#1sun1s( r1-r 0ing1,e'( ng+eS& pe@) ,e'( ng+eS& pe1SiXe = SiXe ,e'( ng+eS& pe1Mosi(ion = Moin( ,e'( ng+eS& pe1,o( (e$ng+e = 3DDD M ge1 --(,e'( ng+eS& pe)
The ne9t e9ample creates the same rectangle as in the pre*ious e9ample< but instead shears it through 13 degrees using the S&e r$ng+e property.
Moin(1x = 1DDD Moin(1. = 1DDD SiXe1Ci-(& = 1DDDD SiXe1Beig&( = 1DDDD "o' = T&is7o#ponen( M ge = "o'1"r 0M ges(D) ,e'( ng+eS& pe = "o'1're (e6ns( n'e(@'o#1sun1s( r1-r 0ing1,e'( ng+eS& pe@) ,e'( ng+eS& pe1SiXe = SiXe ,e'( ng+eS& pe1Mosi(ion = Moin( ,e'( ng+eS& pe1S&e r$ng+e = 3DDD M ge1 --(,e'( ng+eS& pe)
133
3diting 6ra$ing Ob:ects
2earchi%g a%d #ep/aci%g

"s in te9t documents< drawing documents pro*ide a function for searching and replace. This function is similar to the one that is used in te9t documents as described in Te9t Documents. 7owe*er< in drawing documents the descriptor objects for searching and replacing are not created directly through the document object< but rather through the associated character le*el. The following e9ample outlines the replacement process within a drawing:
"i# "i# "i# "i# "o' $s 3b:e'( M ge $s 3b:e'( ,ep+ 'e"es'rip(or $s 3b:e'( 6 $s 6n(eger
"o' = T&is7o#ponen( M ge = "o'1"r 0M ges(D) ,ep+ 'e"es'rip(or = M ge1're (e,ep+ 'e"es'rip(or() ,ep+ 'e"es'rip(or1Se r'&S(ring = @is@ ,ep+ 'e"es'rip(or1,ep+ 'eS(ring = @0 s@ 8or 6 = D (o "o'1"r 0M ges17oun( H 1 M ge = "o'1"r 0M ges(6) M ge1,ep+ 'e$++(,ep+ 'e"es'rip(or) 5ex( 6
This code uses the first page of the document to create a ,ep+ 'e"es'rip(or and then applies this descriptor in a loop to all of the pages in the drawing document.
Prese%tatio%s
#pen#ffice.org presentations are based on drawing documents. 6ach page in the presentation is a slide. You can access slides in the same way as a standard drawing is accessed through the "r 0M ges list of the document object. The com.sun.star.presentation.PresentationDocument ser*ice< responsible for presentation documents< also pro*ides the complete com.sun.star.drawing.DrawingDocument ser*ice.
-or,i%g -ith Prese%tatio%s

&n addition to the drawing functions that are pro*ided by the Mresen( (ion property< the presentation document has a presentation object that pro*ides access to the main properties and control mechanisms for presentations. 5or e9ample< this object pro*ides a s( r( method that can start presentations.
"i# "o' $s 3b:e'( "i# Mresen( (ion $s 3b:e'( "o' = T&is7o#ponen( Mresen( (ion = "o'1Mresen( (ion Mresen( (ion1s( r(()
The code used in this e9ample creates a "o' object that references the current presentation document and establishes the associated presentation object. The s( r(() method of the object is used to start the e9ample and run the screen presentation. The following methods are pro*ided as presentation objects:
start
starts the presentation

en%
ends the presentation

rehearse)imings
starts the presentation from the beginning and establishes its runtime
Presentations
The following properties are also a*ailable:

Allo*Animations (Boolean)
runs animations in the presentation

CustomSho* (String)
allows you to specify the name of the presentation so that you can reference the name in the presentation
-irst2age (String)
name of slide that you want to start the presentation with

IsAl*a s.n)op (Boolean)
always displays the presentation window as the first window on the screen
IsAutomatic (Boolean)
automatically runs through the presentation

Is0n%less (Boolean)
restarts the presentation from the beginning once it ends

Is-ullScreen (Boolean)
automatically starts the presentation in full screen mode

Is"ouseVisible (Boolean)
displays the mouse during the presentation

2ause (long)
the amount of time that a blan- screen is displayed at the end of the presentation
StartWithNa3igator (Boolean)
displays the na*igator window when the presentation starts

Use2n (Boolean)
displays the pointer during the presentation
13-
C H
P ! " #
Charts .(iagrams/
#pen#ffice.org can display data as a chart< which creates graphical representations of numerical data in the form of bars< pie charts< lines or other elements. Data can either be displayed as !D or 1D graphics< and the appearance of the chart elements can be indi*idually adapted in a way similar to the process used for drawing elements. harts are not treated as independent documents in #pen#ffice.org< but as objects that are embedded in an e9isting document. " chart may contain its own data or may display data from the container document. 5or e9ample charts in spreadsheets can display data obtained from the cell ranges and charts in te9t documents can display data obtained from writer tables.
'si%g Charts i% 2preadsheets

harts within spreadsheets can display the data from an assigned cell range within the spreadsheet. "ny modifications made to the data within the spreadsheet will also be reflected in the assigned chart. The following e9ample shows how to create a chart assigned to some cell ranges within a spreadsheet document:
"i# "i# "i# "i# "i# "o' $s 3b:e'( 7& r(s $s 3b:e'( 7& r( s 3b:e'( ,e'( $s 5e0 'o#1sun1s( r1 0(1,e'( ng+e , nge$--ress(D) $s 5e0 'o#1sun1s( r1( b+e17e++, nge$--ress
"o' = T&is7o#ponen( 7& r(s = "o'1S&ee(s(D)17& r(s ,e'(1R = 8DDD ,e'(1Z = 1DDD ,e'(1Ci-(& = 1DDDD ,e'(1Beig&( = 7DDD , nge$--ress(D)1S&ee( = D , nge$--ress(D)1S( r(7o+u#n = D , nge$--ress(D)1S( r(,o0 = D , nge$--ress(D)1En-7o+u#n = 2 , nge$--ress(D)1En-,o0 = 12 7& r(s1 --5e02.5 #e(@A.7& r(@< ,e'(< , nge$--ress()< True< True)
"lthough the code used in the e9ample may appear to be comple9< the central processes are limited to three lines. The first central line creates the "o' document *ariable< which references the current spreadsheet document :"o' line O S( r"es/(op17urren(7o#ponen(;. The code used in the e9ample then creates a list containing all charts of the first spreadsheet :7& r(s line O "o'1S&ee(s(D)17& r(s;. 5inally< in the last line< a new chart is added to this list using the --5e02.5 #e method. This new chart is then *isible to the
137
9sing %&arts in !preads&eets
user. The *ariable , nge$--ress determines the assigned cell range whose data will be displayed within the chart. The *ariable ,e'( determines the position and siBe of the chart within the first sheet in the spreadsheet document. The pre*ious e9ample creates a bar chart. &f a different chart type is needed< then the bar chart must be e9plicitly replaced:
7& r( = 7& r(s1ge(2.5 #e(@A.7& r(@)1e#be--e-3b:e'( 7& r(1"i gr # = 7& r(1're (e6ns( n'e(@'o#1sun1s( r1'& r(1Line"i gr #@)
The first line defines the corresponding chart object. The second line replaces the current chart with a new one A in this e9ample< a line chart. Note VBA : &n )icrosoft 69cel< a distinction is made between charts which ha*e been inserted as a separate page in a )icrosoft 69cel document and charts which are embedded in a table page. orrespondingly< two different access methods are defined there for charts. This distinction is not made in #pen#ffice.org $asic< because charts in #pen#ffice.org alc are always created as embedded objects of a table page. The charts are always accessed using the 7& r(s list of the associated S&ee( object.
!he 2tructure of Charts

The structure of a chart< and therefore the list of ser*ices and interfaces supported by it< depends on the chart type. 5or e9ample< the methods and properties of the YGa9is< are a*ailable in 1D charts< but not in !D charts< and in pie charts< there are no interfaces for wor-ing with a9es.
!it/e5 2ubtit/e a%d Lege%d

Title< subtitle and legend are basic elements pro*ided for e*ery chart. The 7& r( object pro*ides the following properties for administrating these elements:
(as"ain)itle (Boolean)
acti*ates the title

)itle (.b6ect)
object with detailed information about the chart title :supports the com.sun.star.chart. hartTitle ser*ice;
(asSub)itle(Boolean)
acti*ates the subtitle

Subtitle (.b6ect)
object with detailed information about the chart subtitle :supports the com.sun.star.chart. hartTitle ser*ice;
(asLegen% (Boolean)
acti*ates the legend

Legen% (.b6ect)
object with detailed information about the legend :supports the com.sun.star.chart. hartLegend ser*ice; $oth ser*ices 'o#1sun1s( r1'& r(17& r(Ti(+e and 'o#1sun1s( r1'& r(17& r(Legen- do support the ser*ice 'o#1sun1s( r1-r 0ing1S& pe. This allows to determine the position and siBe of the elements using the Mosi(ion and SiXe properties. "s the siBe of the legend and the titles is calculated automatically based on the current content and the character height for e9ample< the siBe property pro*ides read access only.
130
'&e !tructure of %&arts
5ill and line properties :com.sun.star.drawing.5illProperties and com.sun.star.drawing.LineProperties ser*ices; as well as the character properties :com.sun.star.style. haracterProperties ser*ice; are pro*ided for further formatting of the elements. com.sun.star.chart. hartTitlecontains not only the listed formatting properties< but also two other properties:
String (String)
te9t which to be displayed as the title or subtitle

)e1t$otation (Long)
angle of rotation of te9t in /33ths of a degree The legend :com.sun.star.chart. hartLegend; contains the following additional property:
Alignment (0num)
position at which the legend appears :*alue of type com.sun.star.chart. hartLegendPosition; The following e9ample creates a chart with a title N)ain Title StringN< a subtitle NSubtitle StringN and a legend. The legend has a gray bac-ground color< is placed at the bottom of the chart< and has a character siBe of % points.
,e'(1R = 8DDD ,e'(1Z = 1DDD ,e'(1Ci-(& = 1DDDD ,e'(1Beig&( = 7DDD , nge$--ress(D)1S&ee( = D , nge$--ress(D)1S( r(7o+u#n = D , nge$--ress(D)1S( r(,o0 = D , nge$--ress(D)1En-7o+u#n = 2 , nge$--ress(D)1En-,o0 = 12 "o' = T&is7o#ponen( 7& 7& 7& 7& 7& 7& 7& 7& 7& 7& 7& 7& r(s = "o'1S&ee(s(D)17& r(s r(s1 --5e02.5 #e(@A.7& r(@< ,e'(< , nge$--ress()< True< True) r( = 7& r(s1ge(2.5 #e(@A.7& r(@)1E#be--e-3b:e'( r(1B sA inTi(+e = True r(1Ti(+e1S(ring = @A in Ti(+e S(ring@ r(1B sSubTi(+e = True r(1Sub(i(+e1S(ring = @Sub(i(+e S(ring@ r(1B sLegen- = True r(1Legen-1$+ign#en( = 'o#1sun1s( r1'& r(17& r(Legen-Mosi(ion123TT3A r(1Legen-18i++S(.+e = 'o#1sun1s( r1-r 0ing18i++S(.+e1S3L6" r(1Legen-18i++7o+or = ,G2(21D< 21D< 21D) r(1Legen-17& rBeig&( = 7
Bac,grou%d
6*ery chart has a bac-ground area. The 7& r( object pro*ides the property $re to format the bac-ground:
Area (.b6ect)
bac-ground area of the chart :supports com.sun.star.chart. hart"rea ser*ice; The bac-ground of a chart co*ers its complete area< including the area under the title< subtitle and legend. The associated com.sun.star.chart. hart"rea ser*ice supports line and fill properties.
0iagram
The 7& r( object pro*ides the property "i gr # which forms the coordinate system with a9es and grids<
%&apter 9 %&arts ;6iagrams<
139
where the data finally is displayed:

Diagram (.b6ect)
object forming the coordinate system where the data is plotted. &t supports com.sun.star.chart.Diagram ser*ice and: com.sun.star.chart.Stac-ableDiagram com.sun.star.chart. hart"9isXSupplier com.sun.star.chart. hart"9isYSupplier com.sun.star.chart. hart"9isYSupplier com.sun.star.chart. hartTwo"9isXSupplier com.sun.star.chart. hartTwo"9isYSupplier Different ser*ices are supported depending on the chart type :see hart Types;.
-a// a%d 3/oor

The chart wall is the bac-ground of the coordinate system where the data is plotted. Two chart walls usually e9ist for 1D charts: one behind the plotted data and one as the leftGhand or rightGhand demarcation. This depends on the rotation of the chart. 1D charts usually also ha*e a floor. The "i gr # object pro*ides the properties ,all and 5loor:
Wall (.b6ect)
bac-ground wall of the coordinate system :supports com.sun.star.chart. hart"rea ser*ice;

-loor (.b6ect)
floor panel of coordinate system :only for 1D charts< supports com.sun.star.chart. hart"rea ser*ice; The specified objects support the 'o#1sun1s( r1'& r(17& r($re ser*ice< which pro*ides the usual fill and line properties :com.sun.star.drawing.5illProperties and com.sun.star.drawing.LineProperties ser*ices< refer to Drawings and Presentations;. The following e9ample shows how graphics :named S-y; already contained in #pen#ffice.org can be used as a bac-ground for a chart. The wall is set to be blue.
,e'(1R = 8DDD ,e'(1Z = 1DDD ,e'(1Ci-(& = 1DDDD ,e'(1Beig&( = 7DDD , nge$--ress(D)1S&ee( = D , nge$--ress(D)1S( r(7o+u#n = D , nge$--ress(D)1S( r(,o0 = D , nge$--ress(D)1En-7o+u#n = 2 , nge$--ress(D)1En-,o0 = 12 "o' = T&is7o#ponen( 7& 7& 7& 7& 7& 7& r(s = "o'1S&ee(s(D)17& r(s r(s1 --5e02.5 #e(@A.7& r(@< ,e'(< , nge$--ress()< True< True) r( = 7& r(s1ge(2.5 #e(@A.7& r(@)1E#be--e-3b:e'( r(1$re 18i++S(.+e = 'o#1sun1s( r1-r 0ing18i++S(.+e126TA$M r(1$re 18i++2i(# p5 #e = @S/.@ r(1$re 18i++2i(# pAo-e = 'o#1sun1s( r1-r 0ing12i(# pAo-e1,EME$T
7& r(1"i gr #1C ++18i++S(.+e = 'o#1sun1s( r1-r 0ing18i++S(.+e1S3L6" 7& r(1"i gr #1C ++18i++7o+or = ,G2(DD<132<2DL)
140
1es
#pen#ffice.org recogniBes fi*e different a9es that can be used in a chart. &n the simplest scenario< these are the X and YGa9es. ,hen wor-ing with 1D charts< a YGa9is is also sometimes pro*ided. 5or charts in which the *alues of the *arious rows of data de*iate significantly from one another< #pen#ffice.org pro*ides a second X and YGa9is for second scaling operations. The "i gr # object pro*ides the following properties to access the a9es:
(as8A1is (Boolean)
acti*ates the XGa9is

8A1is (.b6ect)
object with detailed information about the XGa9is :supports com.sun.star.chart. hart"9is ser*ice;
(as8A1isDescription (Boolean)
acti*ates the labels for the inter*al mar-s for the XGa9is
(as&A1is (Boolean)
acti*ates the YGa9is

&A1is (.b6ect)
object with detailed information about the YGa9is :supports com.sun.star.chart. hart"9is ser*ice;
(as&A1isDescription (Boolean)
acti*ates the labels for the inter*al mar-s for the YGa9is
(as9A1is (Boolean)
acti*ates the YGa9is

9A1is (.b6ect)
object with detailed information about the YGa9is :supports com.sun.star.chart. hart"9is ser*ice;
(as9A1isDescription (Boolean)
acti*ates the labels for the inter*al mar-s for the YGa9is
(asSecon%ar 8A1is (Boolean)
acti*ates the secondary XGa9is

Secon%ar 8A1is (.b6ect)
object with detailed information about the secondary XGa9is :supports com.sun.star.chart. hart"9is ser*ice;
(asSecon%ar 8A1isDescription (Boolean)
acti*ates the labels for the inter*al mar-s for the secondary XGa9is
(asSecon%ar &A1is (Boolean)
acti*ates the secondary YGa9is

Secon%ar &A1is (.b6ect)
object with detailed information about the secondary YGa9is :supports com.sun.star.chart. hart"9is ser*ice;
(asSecon%ar &A1isDescription (Boolean)
acti*ates the labels for the inter*al mar-s for the secondary YGa9is
Properties of 1es
The a9is objects of a #pen#ffice.org chart support the com.sun.star.chart. hart"9is ser*ice. &n addition to
141
the properties for characters :com.sun.star.style. haracterProperties ser*ice< refer to Te9t Documents; and lines :com.sun.star.drawing.LineStyle ser*ice< refer to Drawings and Presentations;< it pro*ides the following properties:
2ca/i%g properties6
"a1 (Double)
ma9imum *alue for a9is

"in (Double)
minimum *alue for a9is

.rigin (Double)
point of intersect for crossing a9es

Step"ain (Double)
distance between the major inter*al mar-s

Step(elp (Double)
distance between the minor inter*al mar-s :deprecated since #pen#ffice.org 1.3M 'se property Step7elp ount instead;
Step(elpCount (Long)
ontains the number of minor inter*als within a major inter*al. 6.g. a Step7elp ount of 4 di*ides the major inter*al into 4 pieces and thus produces 8 minor tic- mar-s. :a*ailable since #pen#ffice.org 1.3;
Auto"a1 (Boolean)
the ma9imum *alue for the a9is is calculated automatically when set to true
Auto"in (Boolean)
the minimum *alue for the a9is is calculated automatically when set to true
Auto.rigin (Boolean)
the origin is determined automatically when set to true

AutoStep"ain (Boolean)
Step)ain is determined automatically when set to true

AutoStep(elp (Boolean)
Step7elp ount is determined automatically when set to true

Logarithmic (Boolean)
scales the a9es in logarithmic manner :rather than linear;

$e3erseDirection (Boolean)
determines if the a9is orientation is mathematical or re*ersed. :a*ailable since #pen#ffice.org !.8;
Labe/ properties6
Displa Labels (Boolean)
acti*ates the te9t label at the inter*al mar-s

)e1t$otation (Long)
angle of rotation of te9t label in /33ths of a degree

Arrange.r%er (enum)
the label may be staggered< thus they are positioned alternately o*er two lines :*alues according to com.sun.star.chart. hart"9is"rrange#rderType;
14"
)e1tBrea' (Boolean)
permits line brea-s within the a9es labels

)e1tCan.3erlap (Boolean)
permits an o*erlap of the a9es labels

Number-ormat (Long)
number format to be used with the a9es labels

Lin'Number-ormat)oSource (Boolean)
determines whether to use the number format gi*en by the container document< or from the property
5u#ber8or# (. :since #pen#ffice.org !.1;
&%ter*a/ mar, properties6

"ar's (Const)
determines the position of the major inter*al mar-s :*alues in accordance with com.sun.star.chart. hart"9is)ar-s;
(elp"ar's (Const)
determines the position of the minor inter*al mar-s :*alues in accordance with com.sun.star.chart. hart"9is)ar-s;
O%/y for bar charts6

.3erlap (Long)
percentage which specifies the e9tent to which the bars of different sets of data may o*erlap :at /33\< the bars are shown as completely o*erlapping< at G/33\< there is a distance of the width of one bar between them;
+apWi%th (long)
percentage which specifies the distance there may be between the different groups of bars of a chart :at /33\< there is a distance corresponding to the width of one bar;
Grids
5or the primary a9es grids and sub grids can be displayed< matching to the major and minor inter*als. The "i gr # object pro*ides the following properties to access the grids:
(as8A1is+ri% (Boolean)
acti*ates major grid for XGa9is

8"ain+ri% (.b6ect)
object with detailed information about the major grid for XGa9is :supports com.sun.star.chart. hartDrid ser*ice;
(as8A1is(elp+ri% (Boolean)
acti*ates minor grid for XGa9is

8(elp+ri% (.b6ect)
object with detailed information about the minor grid for XGa9is :supports com.sun.star.chart. hartDrid ser*ice; the same for y and B:
(as&A1is+ri% (Boolean)
acti*ates major grid for YGa9is

%&apter 9 %&arts ;6iagrams< 143
&"ain+ri% (.b6ect)
object with detailed information about the major grid for YGa9is :supports com.sun.star.chart. hartDrid ser*ice;
(as&A1is(elp+ri% (Boolean)
acti*ates minor grid for YGa9is

&(elp+ri% (.b6ect)
object with detailed information about the minor grid for YGa9is :supports com.sun.star.chart. hartDrid ser*ice;
(as9A1is+ri% (Boolean)
acti*ates major grid for YGa9is

9"ain+ri% (.b6ect)
object with detailed information about the major grid for YGa9is :supports com.sun.star.chart. hartDrid ser*ice;
(as9A1is(elp+ri% (Boolean)
acti*ates minor grid for YGa9is

9(elp+ri% (.b6ect)
object with detailed information about the minor grid for YGa9is :supports com.sun.star.chart. hartDrid ser*ice; The grid object is based on the com.sun.star.chart. hartDrid ser*ice< which in turn supports the line properties of the com.sun.star.drawing.LineStyle support ser*ice :refer to Drawings and Presentations;.
1es !it/e
5or all a9es an additional title can be displayed. The "i gr # object pro*ides the following properties to access the a9es title:
(as8A1is)itle (Boolean)
acti*ates title of XGa9is

8A1is)itle (.b6ect)
object with detailed information about title of the XGa9is :supports com.sun.star.chart. hartTitle ser*ice; same y and B:
(as&A1is)itle (Boolean)
acti*ates title of YGa9is

&A1is)itle (.b6ect)
object with detailed information about title of the YGa9is :supports com.sun.star.chart. hartTitle ser*ice;
(as9A1is)itle (Boolean)
acti*ates title of YGa9is

9A1is)itle (.b6ect)
object with detailed information about title of the YGa9is :supports com.sun.star.chart. hartTitle ser*ice; and for the secondary a9es :a*ailable since #pen#ffice.org 1.3;:
144
(asSecon%ar 8A1is)itle (Boolean)
acti*ates title of the secondary XGa9is.

Secon%8A1is)itle (.b6ect)
object with detailed information about title of the secondary XGa9is :supports com.sun.star.chart. hartTitle ser*ice;
(asSecon%ar &A1is)itle (Boolean)
acti*ates title of the secondary YGa9is.

Secon%&A1is)itle (.b6ect)
object with detailed information about title of the secondary YGa9is :supports com.sun.star.chart. hartTitle ser*ice; The objects for formatting the a9es title are based on the com.sun.star.chart. hartTitle ser*ice< which is also used for chart titles.
"1amp/e
The following e9ample creates a line chart. The color for the rear wall of the chart is set to white. $oth the X and YGa9es ha*e a gray grid for *isual orientation. The minimum *alue of the YGa9is is fi9ed to 3 and the ma9imum *alue is fi9ed to /33 so that the resolution of the chart is retained e*en if the *alues are changed. The XGa9is points in re*erse direction from right to left. "nd a title for the XGa9is was added.
"o' = T&is7o#ponen( 7& r(s = "o'1S&ee(s(D)17& r(s ,e'(1R = 8DDD ,e'(1Z = 1DDD ,e'(1Ci-(& = 1DDDD ,e'(1Beig&( = 7DDD , nge$--ress(D)1S&ee( = D , nge$--ress(D)1S( r(7o+u#n = D , nge$--ress(D)1S( r(,o0 = D , nge$--ress(D)1En-7o+u#n = 2 , nge$--ress(D)1En-,o0 = 12 7& 7& 7& 7& 7& 7& 7& 7& 7& 7& r(s1 --5e02.5 #e(@A.7& r(@< ,e'(< , nge$--ress()< True< True) r( = 7& r(s1ge(2.5 #e(@A.7& r(@)1e#be--e-3b:e'( r(1"i gr # = 7& r(1're (e6ns( n'e(@'o#1sun1s( r1'& r(1Line"i gr #@) r(1"i gr #1C ++18i++7o+or = ,G2(255< 255< 255) r(1"i gr #1B sR$xisGri- = True r(1"i gr #1RA inGri-1Line7o+or = ,G2(1L2< 1L2< 1L2) r(1"i gr #1B sZ$xisGri- = True r(1"i gr #1ZA inGri-1Line7o+or = ,G2(1L2< 1L2< 1L2) r(1"i gr #1Z$xis1Ain = D r(1"i gr #1Z$xis1A x = 1DD
7& r(1"i gr #1R$xis1,e*erse"ire'(ion = (rue %nee-s 3pen3))i'e1org 214 or ne0er 7& r(1"i gr #1B sR$xisTi(+e = (rue 7& r(1"i gr #1R$xisTi(+e1S(ring = @,e*erse- R $xis Ex #p+e@
30 Charts
)ost charts in #pen#ffice.org can also be displayed with 1D graphics. The following properties are pro*ided for 1D charts at the "i gr # object:
Dim:D (Boolean)
acti*ates 1D display
14-
Deep (Boolean)
the series will be arranged behind each other in BGdirection

$ightAngle%A1es (Boolean)
acti*ates a 1D display mode where XG and YGa9es form a right angle within the projection. :a*ailable since #pen#ffice.org !.1;
D:DScene2erspecti3e (0num)
defines whether the 1D objects are to be drawn in perspecti*e or parallel projection.:*alues according to com.sun.star.drawing.Projection)ode;
2erspecti3e (Long)
Perspecti*e of 1D charts : ]3</33^ ; :a*ailable since #pen#ffice.org !.8./;

$otation(ori4ontal (Long)
7oriBontal rotation of 1D charts in degrees : ]G/(3</(3^ ; :a*ailable since #pen#ffice.org !.8./;

$otationVertical (Long)
.ertical rotation of 1D charts in degrees : ]G/(3</(3^ ; :a*ailable since #pen#ffice.org !.8./; The following e9ample creates a 1D area chart.
"o' = T&is7o#ponen( 7& r(s = "o'1S&ee(s(D)17& r(s ,e'(1R = 8DDD ,e'(1Z = 1DDD ,e'(1Ci-(& = 1DDDD ,e'(1Beig&( = 7DDD , nge$--ress(D)1S&ee( = D , nge$--ress(D)1S( r(7o+u#n = D , nge$--ress(D)1S( r(,o0 = D , nge$--ress(D)1En-7o+u#n = 2 , nge$--ress(D)1En-,o0 = 12 7& 7& 7& 7& 7& 7& 7& 7& 7& 7& r(s1 --5e02.5 #e(@A.7& r(@< ,e'(< , nge$--ress()< True< True) r( = 7& r(s1ge(2.5 #e(@A.7& r(@)1e#be--e-3b:e'( r(1"i gr # = 7& r(1're (e6ns( n'e(@'o#1sun1s( r1'& r(1$re "i gr #@) r(1"i gr #1"i#3" = (rue r(1"i gr #1"eep = (rue r(1"i gr #1,ig&($ng+e-$xes = (rue %nee-s 3pen3))i'e1org 213 or ne0er r(1"i gr #1"3"S'eneMerspe'(i*e = 'o#1sun1s( r1-r 0ing1Mro:e'(ionAo-e1ME,SME7T64E r(1"i gr #1Merspe'(i*e = 1DD %nee-s 3pen3))i'e1org 21411 or ne0er r(1"i gr #1,o( (ionBoriXon( + = 6D %nee-s 3pen3))i'e1org 21411 or ne0er r(1"i gr #1,o( (ion4er(i' + = 3D %nee-s 3pen3))i'e1org 21411 or ne0er
2tac,ed Charts
Stac-ed charts are charts that are arranged with se*eral indi*idual *alues on top of one another to produce a total *alue. This *iew shows not only the indi*idual *alues< but also an o*er*iew of all the *alues. &n #pen#ffice.org< *arious types of charts can be displayed in a stac-ed form. "ll of these charts support the com.sun.star.chart.Stac-ableDiagram ser*ice< which in turn pro*ides the following properties:
Stac'e% (Boolean)
acti*ates the stac-ed *iewing mode

2ercent (Boolean)
rather than absolute *alues< displays their percentage distribution
14/
%&art '1pes
Chart !ypes
Li%e Charts
Line charts :com.sun.star.chart.LineDiagram; support two XGa9es< two YGa9es and one YGa9is. They can be displayed as !D or 1D graphics :com.sun.star.chart.Dim1Ddiagramser*ice;. The lines can be stac-ed :com.sun.star.chart.Stac-ableDiagram;. Line charts pro*ide the following properties:
S mbol) pe (const)
symbol for displaying the data points :constant in accordance with com.sun.star.chart. hartSymbolType;
S mbolSi4e (Long)
siBe of symbol for displaying the data points in /33ths of a millimeter

S mbolBitmapU$L (String)
file name of graphics for displaying the data points

Lines (Boolean)
lin-s the data points by means of lines

Spline) pe (Long)
spline function for smoothing the lines :3: no spline function< /: cubic splines< !: $ splines;
Spline.r%er (Long)
polynomial weight for splines :only for $ splines;

Spline$esolution (Long)
number of support points for spline calculation
rea Charts
"rea charts :com.sun.star.chart."reaDiagram ser*ice; support two XGa9es< two YGa9es and one YGa9is. They can be displayed as !D or 1D graphics :com.sun.star.chart.Dim1Ddiagram ser*ice;. The areas can be stac-ed :com.sun.star.chart.Stac-ableDiagram;.
Bar Charts
$ar charts :com.sun.star.chart.$arDiagram; support two XGa9es< two YGa9es and one YGa9is. They can be displayed as !D or 1D graphics :com.sun.star.chart.Dim1Ddiagram ser*ice;. The bars can be stac-ed :com.sun.star.chart.Stac-ableDiagram;. They pro*ide the following properties:
Vertical (Boolean)
displays the bars *ertically< otherwise they are depicted horiBontally

Deep (Boolean)
in 1D *iewing mode< positions the bars behind one another rather than ne9t to one another
Stac'e%BarsConnecte% (Boolean)
lin-s the associated bars in a stac-ed chart by means of lines :only a*ailable with horiBontal charts;
147
%&art '1pes
Number.!Lines (Long)
number of lines to be displayed in a stac-ed chart as lines rather than bars

+roupBars2erA1is (Boolean)
displays bars attached to different a9es behind or ne9t to each other :a*ailable since #pen#ffice.org !.8;
Pie Charts
Pie charts :com.sun.star.chart.PieDiagram; do not contain any a9es and cannot be stac-ed. They can be displayed as !D or 1D graphics :com.sun.star.chart.Dim1DDiagram ser*ice;. The following properties are pro*ided for pie and donut charts with the "i gr # object:
StartingAngle (Long)
angle of the first piece of a pie in degrees :a*ailable since #pen#ffice.org 1.3;
140
C H
/3
P ! " #
$ C
10
(ata!ases
#pen#ffice.org has an integrated database interface :independent of any systems; called Star Database onnecti*ity :SD$ ;. The objecti*e of de*eloping this interface was to pro*ide access to as many different data sources as possible. To ma-e this possible< data sources are accessed by dri*ers. The sources from which the dri*ers ta-e their data is irrele*ant to a SD$ user. Some dri*ers access fileGbased databases and ta-e the data directly from them. #thers use standard interfaces such as =D$ or #D$ . There are< howe*er< also special dri*ers which access the )"P& address boo-< LD"P directories or #pen#ffice.org spreadsheets as data sources. Since the dri*ers are based on '0# components< other dri*ers can be de*eloped and therefore open up new data sources. You will find details about this in the #pen#ffice.org De*eloperCs Duide. Note VBA : &n terms of its concept< SD$ is comparable with the "D# and D"# libraries a*ailable in .$". &t permits high le*el access to databases< regardless of the underlying database bac-ends.
27L6 a 7uery La%guage

The S>L language is pro*ided as a ?uery language for users of SD$ . To compare the differences between different S>L dialects< the SD$ components from #pen#ffice.org ha*e their own S>L parser. This uses the ?uery window to chec- the S>L commands typed and corrects simple synta9 errors< such as those associated with uppercase and lowercase characters. &f a dri*er permits access to a data source that does not support S>L< then it must independently con*ert the transferred S>L commands to the nati*e access needed.
!ypes of 0atabase ccess

The database interface from #pen#ffice.org is a*ailable in the #pen#ffice.org ,riter and #pen#ffice.org alc applications< as well as in the database forms. &n #pen#ffice.org ,riter< standard letters can be created with the assistance of SD$ data sources and these can then be printed out. You can also mo*e data from the database window into te9t documents using the dragGandGdrop function. &f you mo*e a database table into a spreadsheet< #pen#ffice.org creates a table area which can be updated
149
'1pes of 6atabase Access
at the clic- of the mouse if the original data has been modified. on*ersely< spreadsheet data can be mo*ed to a database table and a database import performed. 5inally< #pen#ffice.org pro*ides a mechanism for forms based on databases. To do this< you first create a standard #pen#ffice.org ,riter or #pen#ffice.org alc form and then lin- the fields to a database. "ll the options specified here are based on the user interface from #pen#ffice.org. 0o programming -nowledge is needed to use the corresponding functions. This section< howe*er< pro*ides little information about the functions specified< but instead concentrates on the programming interface from SD$ < which allows for automated database ?uerying and therefore permits a much greater range of applications to be used. $asic -nowledge of the way in which databases function and the S>L ?uery language is howe*er needed to fully understand the following sections.
0ata 2ources
" database is incorporated into #pen#ffice.org by creating what is commonly referred to as a data source. The user interface pro*ides a corresponding option for creating data sources in the 69tras menu. You can also create data sources and wor- with them using #pen#ffice.org $asic. " database conte9t object that is created using the 're (eNnoSer*i'e function ser*es as the starting point for accessing a data source. This based on the com.sun.star.sdb.Database onte9t ser*ice and is the root object for all database operations. The following e9ample shows how a database conte9t can be created and then used to determine the names of all data sources a*ailable. &t displays the names in a message bo9.
"i# " ( b se7on(ex( $s 3b:e'( "i# 5 #es "i# 6 $s 6n(eger " ( b se7on(ex( = 're (eNnoSer*i'e(@'o#1sun1s( r1s-b1" ( b se7on(ex(@) 5 #es = " ( b se7on(ex(1ge(E+e#en(5 #es() 8or 6 = D To N2oun-(5 #es()) Asg2ox 5 #es(6) 5ex( 6
The indi*idual data sources are based on the com.sun.star.sdb.DataSource ser*ice and can be determined from the database conte9t using the ge(2.5 #e method:
"i# " ( b se7on(ex( $s 3b:e'( "i# " ( Sour'e $s 3b:e'( " ( b se7on(ex( = 're (eNnoSer*i'e(@'o#1sun1s( r1s-b1" ( b se7on(ex(@) " ( Sour'e = " ( b se7on(ex(1ge(2.5 #e(@7us(o#ers@)
The e9ample creates a " ( Sour'e object for a data source called >!s omers. Data sources pro*ide a range of properties< which in turn pro*ide general information about the origin of the data and information about access methods. The properties are:
Name (String)
name of data source

U$L (String)
'@L of data source in the form of 3d.c: s!.pro oco# : s!.$ame or sd.c: s!.pro oco# : s!.$ame
Settings (Arra )
array containing Mroper(.4 +ueGpairs with connection parameters :usually at least user name and
1-0
6ata !ources
password;
User (String)
user name
2ass*or% (String)
user password :is not sa*ed;

Is2ass*or%$e7uire% (Boolean)
the password is needed and is interacti*ely re?uested from user.

Is$ea%.nl (Boolean)
permits readGonly access to the database

Number-ormatsSupplier (.b6ect)
object containing the number formats a*ailable for the database :supports the com.sun.star.util.X0umber5ormatsSupplier interface;
)able-ilter (Arra )
list of table names to be displayed

)able) pe-ilter (Arra )
list of table types to be displayed. .alues a*ailable are T$2LE< 46EC and SZSTEA T$2LE
SuppressVersionColumns (Boolean)
suppresses the display of columns that are used for *ersion administration Note The data sources from #pen#ffice.org are not /:/ comparable with the data sources in #D$ . ,hereas an #D$ data source only co*ers information about the origin of the data< a data source in #pen#ffice.org also includes a range of information about how the data is displayed within the database windows of #pen#ffice.org.
7ueries
Predefined ?ueries can be assigned to a data source. #pen#ffice.org notes the S>L commands of ?ueries so that they are a*ailable at all times. >ueries are used to simplify wor-ing with databases because they can be opened with a simple mouse clic- and also pro*ide users without any -nowledge of S>L with the option of issuing S>L commands. "n object which supports the com.sun.star.sdb.>ueryDefinition ser*ice is concealed behind a ?uery. The ?ueries are accessed by means of the Suer."e)ini(ions method of the data source. The following e9ample lists the names of data source ?ueries can be established in a message bo9.
"i# "i# "i# "i# "i# " ( b se7on(ex( $s 3b:e'( " ( Sour'e $s 3b:e'( Suer."e)ini(ions $s 3b:e'( Suer."e)ini(ion $s 3b:e'( 6 $s 6n(eger
" ( b se7on(ex( = 're (eNnoSer*i'e(@'o#1sun1s( r1s-b1" ( b se7on(ex(@) " ( Sour'e = " ( b se7on(ex(1ge(2.5 #e(@7us(o#ers@) Suer."e)ini(ions = " ( Sour'e1ge(Suer."e)ini(ions() 8or 6 = D To Suer."e)ini(ions17oun(() H 1 Suer."e)ini(ion = Suer."e)ini(ions(6) Asg2ox Suer."e)ini(ion15 #e 5ex( 6
&n addition to the 0ame property used in the e9ample< the com.sun.star.sdb.>ueryDefinition pro*ides a whole range of other properties. These are:
%&apter 10 6atabases
1-1
6ata !ources
Name (String)
?uery name
Comman% (String)
S>L command :typically a SELE7T command; The following e9ample shows how a ?uery object can be created in a programGcontrolled manner and can be assigned to a data source.
"i# "i# "i# "i# "i# " ( b se7on(ex( $s 3b:e'( " ( Sour'e $s 3b:e'( Suer."e)ini(ions $s 3b:e'( Suer."e)ini(ion $s 3b:e'( 6 $s 6n(eger
" ( b se7on(ex( = 're (eNnoSer*i'e(@'o#1sun1s( r1s-b1" ( b se7on(ex(@) " ( Sour'e = " ( b se7on(ex(1ge(2.5 #e(@7us(o#ers@) Suer."e)ini(ions = " ( Sour'e1ge(Suer."e)ini(ions() Suer."e)ini(ion = 're (eNnoSer*i'e(@'o#1sun1s( r1s-b1Suer."e)ini(ion@) Suer."e)ini(ion17o## n- = @SELE7T * 8,3A 7us(o#er@ Suer."e)ini(ions1inser(2.5 #e(@5e0Suer.@< Suer."e)ini(ion)
The ?uery object is first created using the 're (eNnoSer*i'e call< then initialiBed< and then inserted into the Suer."e)ini(ions object by means of inser(2.5 #e.
0atabase ccess
" database connection is needed for access to a database. This is a transfer channel which permits direct communication with the database. 'nli-e the data sources presented in the pre*ious section< the database connection must therefore be reGestablished e*ery time the program is restarted. #pen#ffice.org pro*ides *arious ways of establishing database connections. This e9ample shows how to connect to an e9isting data source.
"i# "i# "i# "i# " ( b se7on(ex( $s 3b:e'( " ( Sour'e $s 3b:e'( 7onne'(ion $s 3b:e'( 6n(er '(ionB n-+er s 3b:e'(
" ( b se7on(ex( = 're (eNnoSer*i'e(@'o#1sun1s( r1s-b1" ( b se7on(ex(@) " ( Sour'e = " ( b se7on(ex(1ge(2.5 #e(@7us(o#ers@) 6) 5o( " ( Sour'e16sM ss0or-,e?uire- T&en 7onne'(ion = " ( Sour'e1Ge(7onne'(ion(@@<@@) E+se 6n(er '(ionB n-+er = 're (eNnoSer*i'e(@'o#1sun1s( r1s-b16n(er '(ionB n-+er@) 7onne'(ion = " ( Sour'e17onne'(Ci(&7o#p+e(ion(6n(er '(ionB n-+er) En- 6)
The code used in the e9ample first chec-s whether the database is password protected. &f not< it creates the database connection re?uired using the Ge(7onne'(ion call. The two empty strings in the command line stand for the user name and password. &f the database is password protected< the e9ample creates an 6n(er '(ionB n-+er and opens the database connection using the 7onne'(Ci(&7o#p+e(ion method. The &nteraction7andler ensures that #pen#ffice.org as-s the user for the re?uired login data.
&teratio% of !ab/es
" table is usually accessed in #pen#ffice.org through the ,esu+(Se( object. " ,esu+(Se( is a type of mar-er that indicates a current set of data within a *olume of results obtained using the SELE7T command. This e9ample shows how a ,esu+(Se( can be used to ?uery *alues from a database table.
1-" LibreOffice 3.4 Basic Programmer's Guide !eptember "011
6atabase Access
"i# "i# "i# "i# "i# "i#
" ( b se7on(ex( $s 3b:e'( " ( Sour'e $s 3b:e'( 7onne'(ion $s 3b:e'( 6n(er '(ionB n-+er s 3b:e'( S( (e#en( $s 3b:e'( ,esu+(Se( $s 3b:e'(
" ( b se7on(ex( = 're (eNnoSer*i'e(@'o#1sun1s( r1s-b1" ( b se7on(ex(@) " ( Sour'e = " ( b se7on(ex(1ge(2.5 #e(@7us(o#ers@) 6) 5o( " ( Sour'e16sM ss0or-,e?uire- T&en 7onne'(ion = " ( Sour'e1Ge(7onne'(ion(@@<@@) E+se 6n(er '(ionB n-+er = 're (eNnoSer*i'e(@'o#1sun1s( r1s-b16n(er '(ionB n-+er@) 7onne'(ion = " ( Sour'e17onne'(Ci(&7o#p+e(ion(6n(er '(ionB n-+er) En- 6) S( (e#en( = 7onne'(ion1're (eS( (e#en(() ,esu+(Se( = S( (e#en(1exe'u(eSuer.(@SELE7T @@7us(o#er5u#ber@@ 8,3A @@7us(o#er@@@) 6) 5o( 6s5u++(,esu+(Se() T&en C&i+e ,esu+(Se(1nex( Asg2ox ,esu+(Se(1ge(S(ring(1) CenEn- 6)
#nce the database connection has been established< the code used in the e9ample first uses the 7onne'(ion1're (e3b:e'( call to create a S( (e#en( object. This S( (e#en( object then uses the exe'u(eSuer. call to return the actual ,esu+(Se(. The program now chec-s whether the ,esu+(Se( actually e9ists and tra*erses the data records using a loop. The *alues re?uired :in the e9ample< those from the 7us(o#er5u#ber field; returns the ,esu+(Se( using the ge(S(ring method< whereby the parameter / determines that the call relates to the *alues of the first column. Note VBA : The ,esu+(Se( object from SD$ is comparable with the ,e'or-se( object from D"# and "D#< since this also pro*ides iterati*e access to a database. Note / ar2""%ce 5 : The database is actually accessed in #pen#ffice.org through a ,esu+(Se( object. This reflects the content of a table or the result of a S>LGS6L6 T command. &n the past< the ,esu+(Se( object pro*ided the resident methods in the $pp+i' (ion object for na*igation within the data< for e9ample< " ( 5ex(,e'or- ;.
!ype42pecific (ethods for #etrie*i%g .a/ues

"s can be seen in the e9ample from the pre*ious section< #pen#ffice.org pro*ides a ge(S(ring method for accessing table contents. The method pro*ides the result in the form of a string. The following ge( methods are a*ailable:
getB te()
supports the S>L data types for numbers< characters and strings
getShort()
getInt()
getLong()
get-loat()
getDouble()
%&apter 10 6atabases 1-3
6atabase Access
getBoolean()
getString()
supports all S>L data types

getB tes()
supports the S>L data types for binary *alues

getDate()
supports the S>L data types for numbers< strings< date and time stamp
get)ime()
get)imestamp()
getCharacterStream()
supports the S>L data types for numbers< strings and binary *alues
getUnico%eStream()
supports the S>L data types for numbers< strings and binary *alues
getBinar Stream()
binary *alues
get.b6ect()
supports all S>L data types &n all instances< the number of columns should be listed as a parameter whose *alues should be ?ueried.
!he #esu/t2et .aria%ts

"ccessing databases is often a matter of critical speed. #pen#ffice.org pro*ides se*eral ways of optimiBing ,esu+(Se(s and thereby controlling the speed of access. The more functions a ,esu+(Se( pro*ides< the more comple9 its implementation usually is and therefore the slower the functions are. " simple ,esu+(Se(< pro*ides the minimum scope of functions a*ailable. &t only allows iteration to be applied forward< and for *alues to be interrogated. )ore e9tensi*e na*igation options< such as the possibility of modifying *alues< are therefore not included. The Statement object used to create the ,esu+(Se( pro*ides some properties which allow the functions of the ,esu+(Se( to be influenced:
$esultSetConcurrenc (const)
specifications as to whether the data can be modified :specifications in accordance with com.sun.star.sdbc.@esultSet oncurrency;.
$esultSet) pe (const)
specifications regarding type of ,esu+(Se(s : specifications in accordance with com.sun.star.sdbc.@esultSetType;. The *alues defined in com.sun.star.sdbc.@esultSet oncurrency are:
U2DA)ABL0 ,esu+(Se( permits *alues to be modified
1-4
6atabase Access
$0AD,.NL& ,esu+(Se( does not permit modifications
The com.sun.star.sdbc.@esultSet oncurrency group of constants pro*ides the following specifications:

-.$WA$D,.NL& ,esu+(Se( only permits forward na*igation SC$.LL,INS0NSI)IV0 ,esu+(Se( permits any type of na*igation< changes to the original data are< howe*er< not noted SC$.LL,S0NSI)IV0 ,esu+(Se( permits any type of na*igation< changes to the original data impact on the ,esu+(Se(
Note VBA : " ,esu+(Se( containing the ,E$"_35LZ and S7,3LL_65SE5S6T64E properties corresponds to a record set of the Sn ps&o( type in "D# and D"#. ,hen using the ,esu+(Se(%s NM"$TE$2LE and S7,3LL_SE5S6T64E properties< the scope of function of a ,esu+(Se( is comparable with a ".n se( type ,e'or-se( from "D# and D"#.
(ethods for Na*igatio% i% #esu/t2ets

&f a ,esu+(Se( is a S7,3LL_65SE5S6T64E or S7,3LL_SE5S6T64E type< it supports a whole range of methods for na*igation in the stoc- of data. The central methods are:
ne1t()
na*igation to the ne9t data record

pre3ious()
na*igation to the pre*ious data record

!irst()
na*igation to the first data record

last()
na*igation to the last data record

be!ore-irst()
na*igation to before the first data record

a!terLast()
na*igation to after the last data record "ll methods return a $oolean parameter which specifies whether the na*igation was successful. To determine the current cursor position< the following test methods are pro*ided and all return a $oolean *alue:
isBe!ore-irst() ,esu+(Se( is before the first data record isA!terLast() ,esu+(Se( is after the last data record is-irst() ,esu+(Se( is the first data record
%&apter 10 6atabases
1--
6atabase Access
isLast() ,esu+(Se( is the last data record
(odifyi%g 0ata #ecords

&f a ,esu+(Se( has been created with the ,esu+(Se(7on'urren'. O NM"$TE$2LE *alue< then its content can be edited. This only applies for as long as the S>L command allows the data to be reGwritten to the database :depends on principle;. This is not< for e9ample< possible with comple9 S>L commands with lin-ed columns or accumulated *alues. The ,esu+(Se( object pro*ides Np- (e methods for modifying *alues< which are structured in the same way as the ge( methods for retrie*ing *alues. The up- (eS(ring method< for e9ample< allows a string to be written. "fter modification< the *alues must be transferred into the database using the up- (e,o0()method. The call must ta-e place before the ne9t na*igation command< otherwise the *alues will be lost. &f an error is made during the modifications< this can be undone using the ' n'e+,o0Np- (es()method. This call is only a*ailable pro*ided that the data has not be reGwritten into the database using up- (e,o0().
1-/
C H
//
P ! " #
$ $
11
(ia1ogs
You can add custom dialog windows and forms to #pen#ffice.org documents. These in turn can be lin-ed to #pen#ffice.org $asic macros to considerably e9tend the usage range of #pen#ffice.org $asic. Dialogs can< for e9ample< display database information or guide users through a stepGbyGstep process of creating a new document in the form of a ,iBard. !ip 4 You will find another description of dialogs in the De*eloperCs Duide: chapter #pen#ffice.orgH$asicH&D6 describes more fully the &D6 chapter Programming Dialogs and Dialog ontrols shows more e9amples in $asic.
-or,i%g -ith 0ia/ogs

#pen#ffice.org $asic dialogs consist of a dialog window that can contain te9t fields< list bo9es< radio buttons< and other control elements.
Creati%g 0ia/ogs
You can create and structure dialogs using the #pen#ffice.org dialog editor:
Create and stru ture dialogs in the dialog editor You can drag the control elements from the design pallet :right; into the dialog area< and define their
1-7
)or*ing )it& 6ia,ogs
position and siBe. The e9ample shows a dialog that contains a label and a list bo9.
! dialog ontaining a la"el and a list "ox You can open a dialog with the following code:
"i# "+g $s 3b:e'( "i +ogLibr ries1Lo -Libr r.(@S( n- r-@) "+g = 7re (eNno"i +og("i +ogLibr ries1S( n- r-1"+g"e)) "+g1Exe'u(e() "+g1-ispose()
7re (eNno"i +og creates an object called "+g that references the associated dialog. $efore you can create the dialog< you must ensure that the library it uses :in this e9ample< the S( n- r- library; is loaded. The Lo -Libr r. method performs this tas-.
#nce the "+g dialog object has been initialiBed< you can use the Exe'u(e method to display the dialog. Dialogs such as this one are described as modal because they do not permit any other program action until they are closed. ,hile this dialog is open< the program remains in the Exe'u(e call. The -ispose method at the end of the code releases the resources used by the dialog once the program ends.
C/osi%g 0ia/ogs
C/osi%g -ith OD or Ca%ce/
&f a dialog contains an 2? or a >a$ce# button< the dialog is automatically closed when you clic- one of these buttons. )ore information about wor-ing with these buttons is discussed in Dialog ontrol 6lements in Detail. &f you close a dialog by clic-ing the 2? button< the Exe'u(e method returns a return *alue of /< otherwise a *alue of 3 is returned.
"i# "+g $s 3b:e'( "i +ogLibr ries1Lo -Libr r.(@S( n- r-@) "+g = 7re (eNno"i +og("i +ogLibr ries1S( n- r-1A."i +og) Se+e'( 7 se "+g1Exe'u(e() 7 se 1 Asg2ox @3/ presse-@ 7 se D Asg2ox @7 n'e+ presse-@ En- Se+e'(
1-0
)or*ing )it& 6ia,ogs
C/osi%g -ith the C/ose Butto% i% the !it/e Bar

You can close a dialog by clic-ing the close button on the title bar of the dialog window. The Exe'u(e method of the dialog returns the *alue 3< which is the same as when you clic- ancel.
C/osi%g -ith a% "1p/icit Program Ca//

You can also close an open dialog window with the en-Exe'u(e method:
"+g1en-Exe'u(e()
The 69ecute method of the dialog returns the *alue 3< which is the same as when you clic- ancel.
ccess to &%di*idua/ Co%tro/ "/eme%ts

" dialog can contain any number of control elements. You can access these elements through the ge(7on(ro+ method that returns the control element by name.
"i# 7(+ $s 3b:e'( 7(+ = "+g1ge(7on(ro+(@A.2u((on@) 7(+1L be+ = @5e0 L be+@
This code determines the object for the A.2u((on control element and then initialiBes the 7(+ object *ariable with a reference to the element. 5inally the code sets the L be+ property of the control element to the 5e0 L be+ *alue. Note 'nli-e #pen#ffice.org $asic identifiers< the names of control elements are case sensiti*e.
-or,i%g -ith the (ode/ of 0ia/ogs a%d Co%tro/ "/eme%ts

The di*ision between *isible program elements :V%e-; and the data or documents behind them :6ode#; occurs at many places in #pen#ffice.org "P&. &n addition to the methods and properties of control elements< both dialog and control element objects ha*e a subordinate Ao-e+ object. This object allows you to directly access the content of a dialog or control element. &n dialogs< the distinction between data and depiction is not always as clear as in other "P& areas of #pen#ffice.org. 6lements of the "P& are a*ailable through both the .iew and the )odel. The Ao-e+ property pro*ides programGcontrolled access to the model of dialog and control element objects.
"i# '#-5ex( $s 3b:e'( '#-5ex( = "+g1ge(7on(ro+(@'#-5ex(@) '#-5ex(1Ao-e+1En b+e- = 8 +se
This e9ample deacti*ates the '#-5ex( button in the "+g dialog with the aid of the model object from '#-5ex(.
Properties
Name a%d !it/e
6*ery control element has its own name that can be ?ueried using the following model property:
%&apter 11 6ia,ogs
1-9
Properties
"o%el.Name (String)
control element name You can specify the title that appears in the title bar of a dialog with the following model property:
"o%el.)itle (String)
dialog title :only applies to dialogs;
Positio% a%d 2iEe

You can ?uery the siBe and position of a control element using the following properties of the model object:
"o%el.(eight (long)
height of control element :in ma units;

"o%el.Wi%th (long)
width of control element :in ma units;

"o%el.2osition8 (long)
XGposition of control element< measured from the left inner edge of the dialog :in ma units;
"o%el.2osition& (long)
YGposition of control element< measured from top inner edge of the dialog :in ma units; To ensure platform independence for the appearance of dialogs< #pen#ffice.org uses the 6ap App=o$ ;ma< internal unit to specify the position and siBe within dialogs. "n ma unit is defined as being one eighth of the a*erage height of a character from the system font defined in the operating system and one ?uarter of its width. $y using ma units< #pen#ffice.org ensures that a dialog loo-s the same on different systems under different system settings. &f you want to change the siBe or position of control elements for runtime< determine the total siBe of the dialog and adjust the *alues for the control elements to the corresponding part ratios. Note The )ap "pp5ont :ma; replaces the Twips unit to achie*e better platform independence.
3ocus a%d !abu/ator 2eFue%ce

You can na*igate through the control elements in any dialog by pressing the Tab -ey. The following properties are a*ailable in this conte9t in the control elements model:
"o%el.0nable% (Boolean)
acti*ates the control element

"o%el.)abstop (Boolean)
allows the control element to be reached through the Tab -ey

"o%el.)abIn%e1 (Long)
position of control element in the order of acti*ation 5inally< the control element pro*ides a ge(8o'us method that ensures that the underlying control element recei*es the focus:
get-ocus
control element recei*es the focus :only for dialogs;
1/0
Properties
(u/ti4Page 0ia/ogs
" dialog in #pen#ffice.org can ha*e more than one tab page. The S(ep property of a dialog defines the current tab page of the dialog whereas the S(ep property for a control element specifies the tab page where the control element is to be displayed. The S(epG*alue of 3 is a special case. &f you set this *alue to Bero in a dialog< all of the control elements are *isible regardless of their S(ep *alue. Similarly< if you set this *alue to Bero for a control element< the element is displayed on all of the tab pages in a dialog.
Designing #age 1 of the dialog &n the preceding e9ample< you can also assign the S(ep *alue of 3 to the di*iding line as well as the 7 n'e+< Mre*< 5ex(< and "one buttons to display these elements on all pages. You can also assign the elements to an indi*idual tab page :for e9ample page /;. The following program code shows how the S(ep *alue in e*ent handlers of the 5ex( and Mre* buttons can be increased or reduced and changes the status of the buttons.
Sub '#-5ex(_6ni(i (e"i# '#-5ex( $s 3b:e'( "i# '#-Mre* $s 3b:e'( '#-Mre* = "+g1ge(7on(ro+(@'#-Mre*@) '#-5ex( = "+g1ge(7on(ro+(@'#-5ex(@) '#-Mre*1Ao-e+1En b+e- = 5o( '#-Mre*1Ao-e+1En b+e'#-5ex(1Ao-e+1En b+e- = 8 +se "+g1Ao-e+1S(ep = "+g1Ao-e+1S(ep + 1 En- Sub Sub '#-Mre*_6ni(i (e"i# '#-5ex( $s 3b:e'( "i# '#-Mre* $s 3b:e'( '#-Mre* = "+g1ge(7on(ro+(@'#-Mre*@) '#-5ex( = "+g1ge(7on(ro+(@'#-5ex(@) '#-Mre*1Ao-e+1En b+e- = 8 +se '#-5ex(1Ao-e+1En b+e- = True "+g1Ao-e+1S(ep = "+g1Ao-e+1S(ep H 1 En- Sub
" global "+g *ariable that references an open dialog must be included to ma-e this e9ample possible. The dialog then changes its appearance as follows:
%&apter 11 6ia,ogs
1/1
Properties
#age 1
#age 2 !ip 4 You can find an other ##o$asic e9ample here.
0ia/ogs supporti%g se*era/ /a%guages

The strings of a Dialog can be localiBed< see the De*eloperCs Duide chapter Dialog LocaliBation.
"*e%ts
#pen#ffice.org dialogs and forms are based on an e*entGoriented programming model where you can assign e'e$ )a$d#ers to the control elements. "n e*ent handler runs a predefined procedure when a particular action occurs. You can also edit documents or open databases with e*ent handling as well as access other control elements. #pen#ffice.org control elements recogniBe different types of e*ents that can be triggered in different situations. These e*ent types can be di*ided into four groups: 6o!se co$ ro#: 6*ents that correspond to mouse actions :for e9ample< simple mouse mo*ements or a clic- on a particular screen location;. ?e(.oard co$ ro#: 6*ents that are triggered by -eyboard stro-es. =oc!s mod%"%ca %o$: 6*ents that #pen#ffice.org performs when control elements are acti*ated or deacti*ated.
1/"
3#ents
>o$ ro# e#eme$ -spec%"%c e'e$ s: 6*ents that only occur in relation to certain control elements.
,hen you wor- with e*ents< ma-e sure that you create the associated dialog in the #pen#ffice.org de*elopment en*ironment and that it contains the re?uired control elements or documents :if you apply the e*ents to a form;.
$he %pen%ffi e&org Basi de'elop(ent en'iron(ent The figure abo*e shows the #pen#ffice.org $asic de*elopment en*ironment with a dialog window that contains two list bo9es. You can mo*e the data from one list to the other using the buttons between the two list bo9es. &f you want to display the layout on screen< then you should create the associated #pen#ffice.org $asic procedures so that they can be called up by the e*ent handlers. 6*en though you can use these procedures in any module< it is best to limit their use to two modules. To ma-e your code easier to read< you should assign meaningful names to these procedures. =umping directly to a general program procedure from a macro can result in unclear code. &nstead< to simplify code maintenance and troubleshooting< you should create another procedure to ser*e as an entry point for e*ent handling G e*en if it only e9ecutes a single call to the target procedure. The code in the following e9ample mo*es an entry from the left to the right list bo9 of a dialog.
Sub '#-Se+e'(_6ni(i (e"i# +s(En(ries $s 3b:e'( "i# +s(Se+e'(ion $s 3b:e'( +s(En(ries = "+g1ge(7on(ro+(@+s(En(ries@) +s(Se+e'(ion = "+g1ge(7on(ro+(@+s(Se+e'(ion@) 6) +s(En(ries1Se+e'(e-6(e# U D T&en +s(Se+e'(ion1$--6(e#(+s(En(ries1Se+e'(e-6(e#< D) +s(En(ries1re#o*e6(e#s(+s(En(ries1Se+e'(6(e#Mos< 1) E+se 2eep En- 6) En- Sub
&f this procedure was created in #pen#ffice.org $asic< you can assign it to an e*ent re?uired using the property window of the dialog editor.
%&apter 11 6ia,ogs
1/3
3#ents
$he !ssign ! tion dialog The "ssign "ction dialog lists all of the a*ailable 6*ents. To assign a macro to an e*ent: /. Select the e*ent !. lic- 6acro...
1. $rowse to and select the macro you want to assign 8. lic- #P
Parameters
The occurrence of a particular e*ent is not always enough for an appropriate response. "dditional information may be re?uired. 5or e9ample< to process a mouse clic-< you may need the screen position where the mouse button was pressed. &n #pen#ffice.org $asic< you can use object parameters to pro*ide more information about an e*ent to a procedure< for e9ample:
Sub Mro'essE*en((E*en( $s 3b:e'() En- Sub
The structure and properties of the E*en( object depend on the type of e*ent that triggers the procedure call. @egardless of the type of e*ent< all objects pro*ide access to the rele*ant control element and its model. The control element can be reached using E*en(1Sour'e and its model using E*en(1Sour'e1Ao-e+. You can use these properties to trigger an e*ent within an e*ent handler.
(ouse "*e%ts
#pen#ffice.org $asic recogniBes the following mouse e*ents:
"ouse mo3e%
user mo*es mouse

"ouse mo3e% *hile 'e presse%
user drags mouse while holding down a -ey

"ouse button presse%
user presses a mouse button
1/4
3#ents
Note This e*ent is also used for notifying re?uests for a popup conte9t menu on the control. &n this case< the member MopupTrigger of the e*ent passed to your macro function will be T,NE. &n particular< if such a re?uest is made by pressing the right mouse button on the control< the e*ent will be fired twice: once for the popup menu re?uest< and once for the real mouse e*ent. &f you are interested in only the mouse clic-< your macro should ignore all calls where MopupTrigger is T,NE.
"ouse button release%
user releases a mouse button

"ouse outsi%e
user mo*es mouse outside of the current window The structure of the associated e*ent objects is defined in the com.sun.star.awt.)ouse6*ent structure which pro*ides the following information:
Buttons (short)
button pressed :one or more constants in accordance with com.sun.star.awt.)ouse$utton;

8 (long)
XGcoordinate of mouse< measured in pi9els from the top left corner of the control element
& (long)
YGcoordinate of mouse< measured in pi9els from the top left corner of the control element
Clic'Count (long)
number of clic-s associated with the mouse e*ent :if #pen#ffice.org can respond fast enough<
7+i'/7oun( is also / for a doubleGclic- because only an indi*idual e*ent is initiated;
The constants defined in com.sun.star.awt.)ouse$utton for the mouse buttons are:

L0-)
left mouse button

$I+()
right mouse button

"IDDL0
middle mouse button The following e9ample outputs the mouse position as well as the mouse button that was pressed:
Sub AouseNp(E*en( $s 3b:e'() "i# Asg $s S(ring Asg = @Ve.s! @ 6) E*en(12u((ons $5" 'o#1sun1s( r1 0(1Aouse2u((on1LE8T T&en Asg = Asg G @LE8T @ En- 6) 6) E*en(12u((ons $5" 'o#1sun1s( r1 0(1Aouse2u((on1,6GBT T&en Asg = Asg G @,6GBT @ En- 6) 6) E*en(12u((ons $5" 'o#1sun1s( r1 0(1Aouse2u((on1A6""LE T&en Asg = Asg G @A6""LE @ En- 6) Asg = Asg G 7&r(13) G @Mosi(ion! @ Asg = Asg G E*en(1R G @O@ G E*en(1Z Asg2ox Asg En- Sub
%&apter 11 6ia,ogs
1/-
3#ents
Note VBA : The .$" 7+i'/ and "oub+e'+i'/ e*ents are not a*ailable in #pen#ffice.org $asic. &nstead use the #pen#ffice.org $asic AouseNp e*ent for the '+i'/ e*ent and imitate the "oub+e'+i'/ e*ent by changing the application logic.
Deyboard "*e%ts
The following -eyboard e*ents are a*ailable in #pen#ffice.org $asic:
5e presse%
user presses a -ey.

5e release%
user releases a -ey $oth e*ents relate to logical -ey actions and not to physical actions. &f the user presses se*eral -eys to output a single character :for e9ample< to add an accent to a character;< then #pen#ffice.org $asic only creates one e*ent. " single -ey action on a modification -ey< such as the Shift -ey or the "lt -ey does not create an independent e*ent. &nformation about a pressed -ey is pro*ided by the e*ent object that #pen#ffice.org $asic supplies to the procedure for e*ent handling. &t contains the following properties:
5e Co%e (short)
code of the pressed -ey :default *alues in accordance with com.sun.star.awt.Pey;

5e Char (String)
character that is entered :ta-ing the modification -eys into consideration; The following e9ample uses the Ve.7o-e property to establish if the 6nter -ey< the Tab -ey< or one of the other control -eys has been pressed. &f one of these -eys has been pressed< the name of the -ey is returned< otherwise the character that was typed is returned:
Sub Ve.Mresse-(E*en( $s 3b:e'() "i# Asg $s S(ring Se+e'( 7 se E*en(1Ve.7o-e 7 se 'o#1sun1s( r1 0(1Ve.1,ETN,5 Asg = @,e(urn presse-@ 7 se 'o#1sun1s( r1 0(1Ve.1T$2 Asg = @T b presse-@ 7 se 'o#1sun1s( r1 0(1Ve.1"ELETE Asg = @"e+e(e presse-@ 7 se 'o#1sun1s( r1 0(1Ve.1ES7$ME Asg = @Es' pe presse-@ 7 se 'o#1sun1s( r1 0(1Ve.1"3C5 Asg = @"o0n presse-@ 7 se 'o#1sun1s( r1 0(1Ve.1NM Asg = @Np presse-@ 7 se 'o#1sun1s( r1 0(1Ve.1LE8T Asg = @Le)( presse-@ 7 se 'o#1sun1s( r1 0(1Ve.1,6GBT Asg = @,ig&( presse-@ 7 se E+se Asg = @7& r '(er @ G E*en(1Ve.7& r G @ en(ere-@ En- Se+e'( Asg2ox Asg En- Sub
&nformation about other -eyboard constants can be found in the "P& @eference under the com.sun.star.awt.Pey group of constants.
1//
3#ents
3ocus "*e%ts
5ocus e*ents indicate if a control element recei*es or loses focus. You can use these e*ents to< for e9ample< determine if a user has finished processing a control element so that you can update other elements of a dialog. The following focus e*ents are a*ailable:
When recei3ing !ocus
element recei*es focus

When losing !ocus
element loses focus The E*en( objects for the focus e*ents are structured as follows:
-ocus-lags (short)
cause of focus change :default *alue in accordance with com.sun.star.awt.5ocus hange@eason;

Ne1t-ocus (.b6ect)
object that recei*es focus :only for the C&en +osing )o'us e*ent;
)emporar (Boolean)
the focus is temporarily lost
Co%tro/ "/eme%t42pecific "*e%ts

&n addition to the preceding e*ents< which are supported by all control elements< there are also some control elementGspecific e*ents that are only defined for certain control elements. The most important of these e*ents are:
When Item Change%
the *alue of a control element changes

Item Status Change%
the status of a control element changes

)e1t mo%i!ie%
the te9t of a control element changes

When initiating
an action that can be performed when the control element is triggered :for e9ample< a button is pressed; ,hen you wor- with e*ents< note that some e*ents< such as the C&en ini(i (ing e*ent< can be initiated each time you clic- the mouse on some control elements :for e9ample< on radio buttons;. 0o action is performed to chec- if the status of the control element has actually changed. To a*oid such Vblind e*entsW< sa*e the old control element *alue in a global *ariable< and then chec- to see if the *alue has changed when an e*ent is e9ecuting. The C&en ini(i (ing e*ent is also noteworthy for the following reasons: This e*ent is initiated by either a -eyGpress or a mouse button. Thus< it pro*ides a consistent interface for users who na*igate by mouse or by -eyboard. ,hen the ,epe ( property of a command button is set to True< this e*ent is the one which is repeatedly sent< as long as the triggering action :-ey down or mouseGbutton down; remains in effect.
The properties for the 6(e# S( (us 7& nge- e*ent are:
Selecte% (long)
currently selected entry
%&apter 11 6ia,ogs
1/7
3#ents
(ighlighte% (long)
currently highlighted entry

ItemI% (long)
&D of entry
0ia/og Co%tro/ "/eme%ts

#pen#ffice.org $asic recogniBes a range of control elements which can be di*ided into the following groups: "%try fie/ds Te9t fields Date fields Time fields 0umerical fields urrency fields 5ields adopting any format Butto%s Standard buttons hec-bo9es @adio $uttons 2e/ectio% /ists List bo9es omboGbo9es Tree ontrol Other Scrollbars :horiBontal and *ertical; 5ields of groups Progress bars Di*iding lines :horiBontal and *ertical; Draphics 5ile selection fields
Butto%s
" button performs an action when you clic- it. The simplest scenario is for the button to trigger a C&en 6ni(i (ing e*ent when it is clic-ed by a user. You can also lin- another action to the button to close a dialog using the Mus&2u((onT.pe property. ,hen you clic- a button that has this property set to the *alue of 3< the dialog remains unaffected. &f you clic- a button that has this property set to the *alue of /< the dialog is closed< and the Exe'u(e method of the dialog returns the *alue / :dialog se?uence has been ended correctly;. &f the Mus&2u((onT.pe has the *alue of !< the dialog is closed and the Exe'u(e method of the dialog returns the *alue 3 :dialog closed;. &n the Dialog 6ditor< the property *alues are shown symbolically< as "e) u+( :3;< 3/ . :/;< and 7 n'e+ :!;. The following are some of the properties that are a*ailable through the button model:
"o%el.Bac'groun%Color (long)
color of bac-ground
"o%el.De!aultButton (Boolean)
The button is used as the default *alue and responds to the 6nter -ey if it has no focus
"o%el.-ontDescriptor (struct)
structure that specifies the details of the font to be used :in accordance with com.sun.star.awt.5ontDescriptor structure;
"o%el.Label (String)
label that is displayed on the button

"o%el.2rintable (Boolean)
the control element can be printed

"o%el.)e1tColor (Long)
te9t color of the control element

"o%el.(elp)e1t (String)
help te9t that is displayed when you mo*e the mouse cursor o*er the control element
1/0 LibreOffice 3.4 Basic Programmer's Guide !eptember "011
6ia,og %ontro, 3,ements
"o%el.(elpU$L (String)
'@L of the online help for the corresponding control element

2ushButton) pe (short)
action that is lin-ed to the button :3: no action< /: #P< !: ancel;
Optio% Butto%s
These buttons are generally used in groups and allow you to select from one of se*eral options. ,hen you select an option< all of the other options in the group are deacti*ated. This ensures that at any one time< only one option button is set. "n option button control element pro*ides two properties:
State (Boolean)
acti*ates the button

Label (String)
label that is displayed on the button You can also use the following properties from the model of the option buttons:
structure with details of the font to be used :in accordance with com.sun.star.awt.5ontDescriptor;
label that is displayed on the control element

control element can be printed

"o%el.State (Short)
if this property is e?ual to /< the option is acti*ated< otherwise it is deacti*ated

te9t color of control element

help te9t that is displayed when the mouse cursor rests o*er the control element
'@L of online help for the corresponding control element To combine se*eral option buttons in a group< you must position them one after another in the acti*ation se?uence without any gaps :Ao-e+1T b6n-ex property* described as #rder in the dialog editor;. &f the acti*ation se?uence is interrupted by another control element< then #pen#ffice.org automatically starts with a new control element group that can be acti*ated regardless of the first group of control elements. Note VBA : 'nli-e .$"< you cannot insert option buttons in a group of control elements in #pen#ffice.org $asic. The grouping of control elements in #pen#ffice.org $asic is only used to ensure a *isual di*ision by drawing a frame around the control elements.
Chec,bo1es
hec-bo9es are used to record a Yes or 0o *alue and depending on the mode< they can adopt two or three states. &n addition to the Yes and 0o states< a chec- bo9 can ha*e an inGbetween state if the corresponding
%&apter 11 6ia,ogs
1/9
Yes or 0o status has more than one meaning or is unclear. hec-bo9es pro*ide the following properties:
State (Short)
state of the chec-bo9 :3: no< /: yes< !: inGbetween state;

Label (String)
label for the control element

enable)riState (Boolean)
in addition to the acti*ated and deacti*ated states< you can also use the inGbetween state The model object of a chec-bo9 pro*ides the following properties:
structure with details of the font used :in accordance with com.sun.star.awt.5ontDescriptor structure;
label for the control element


"o%el.State (Short)
state of the chec-bo9 :3: no< /: yes< !: inGbetween state;

the control element can be reached with the Tab -ey


help te9t that is displayed when you rest the mouse cursor o*er the control element
'@L of online help for the corresponding control element
!e1t 3ie/ds
Te9t fields allow users to type numbers and te9t. The com.sun.star.awt.'no ontrol6dit. ser*ice forms the basis for te9t fields. " te9t field can contain one or more lines and can be edited or bloc-ed for user entries. Te9t fields can also be used as special currency and numerical fields as well as screen fields for special tas-s. "s these control elements are based on the Nno7on(ro+E-i( 'no ser*ice< their programGcontrolled handling is similar. Te9t fields pro*ide the following properties:
)e1t (String)
current te9t
Selecte%)e1t (String)
currently highlighted te9t

Selection (Struct)
readGonly highlighting of details :structure in accordance with com.sun.star.awt.Selection< with the

Ain and A x properties to specify the start and end of the current highlighting;
170
"a1)e1tLen (short)
ma9imum number of characters that you can type in the field

0%itable (Boolean) True acti*ates the option for entering te9t< 8 +se bloc-s the entry option :the property cannot be called up directly but only through 6sE-i( b+e; Is0%itable (Boolean)
the content of the control element can be changed< readGonly The following properties are pro*ided through the associated model object:
"o%el.Align (short)
orientation of te9t :3: leftGaligned< /: centered< !: rightGaligned;

color of the bac-ground of the control element

"o%el.Bor%er (short)
type of border :3: no border< /: 1D border< !: simple border;

"o%el.0choChar (String)
echo character for password fields

structure with details of font used :in accordance with com.sun.star.awt.5ontDescriptor structure;
"o%el.(ar%LineBrea's (Boolean)
automatic line brea-s are permanently inserted in the control element te9t
"o%el.(Scroll (Boolean)
the te9t has a horiBontal scrollbar

"o%el."a1)e1tLen (Short)
ma9imum length of te9t< where 3 corresponds to no length limit

"o%el."ultiLine (Boolean)
permits entry to spans se*eral lines


"o%el.$ea%.nl (Boolean)
the content of the control element is readGonly


"o%el.)e1t (String)
te9t associate with the control element


"o%el.VScroll (Boolean)
the te9t has a *ertical scrollbar

help te9t that is displayed when the mouse cursor rests o*er the control element
%&apter 11 6ia,ogs
171
List Bo1es
List bo9es :com.sun.star.awt.'no ontrolList$o9 ser*ice; support the following properties:
ItemCount (Short)
number of elements< readGonly

Selecte%Item (String)
te9t of highlighted entry< readGonly

Selecte%Items (Arra .! Strings)
data field with highlighted entries< readGonly

Selecte%Item2os (Short)
number of the entry highlighted at present< readGonly

Selecte%Items2os (Arra o! Short)
data field with the number of highlighted entries :for lists which support multiple selection;< readG only
"ultiple"o%e (Boolean) True acti*ates the option for multiple selection of entries< 8 +se bloc-s multiple selections :the property cannot be called up directly but only through 6sAu+(ip+eAo-e; Is"ultiple"o%e (Boolean)
permits multiple selection within lists< readGonly List bo9es pro*ide the following methods:
a%%Item (Item# 2os)
enters the string specified in the 6(e# into the list at the Mos position
a%%Items (ItemArra # 2os)
enters the entries listed in the stringCs 6(e#$rr . data field into the list at the Mos position
remo3eItems (2os# Count)
remo*es 7oun( entries as of the Mos position

selectItem (Item# Select"o%e)
acti*ates or deacti*ates highlighting for the element specified in the string 6(e# depending on the
Se+e'(Ao-e $oolean *ariable ma'eVisible (2os)
scrolls through the list field so that the entry specified with Mos is *isible The model object of the list bo9es pro*ides the following properties:
bac-ground color of control element

"o%el.Bor%er (short)

structure with details of font used :in accordance with com.sun.star.awt.5ontDescriptor structure;
17"
"o%el.LineCount (Short)
number of lines in control element

"o%el."ultiSelection (Boolean)
permits multiple selection of entries

"o%el.Selecte%Items (Arra o! Strings)
list of highlighted entries

"o%el.StringItemList (Arra o! Strings)
list of all entries


"o%el.$ea%.nl (Boolean)



automatically displayed help te9t which is displayed if the mouse cursor is abo*e the control element
'@L of online help for the corresponding control element Note VBA : The .$" option for issuing list entries with a numerical additional *alue :6(e#" ( ; does not e9ist in #pen#ffice.org $asic. &f you want to administer a numerical *alue :for e9ample a database &D; in addition to the natural language te9t< you must create an au9iliary data field that administers in parallel to the list bo9.
%&apter 11 6ia,ogs
173
C H
/!
P ! " #
$ )
12
2orms
&n many respects< the structure of #pen#ffice.org forms corresponds to the dialogs. There are< howe*er< a few -ey differences:
Dialogs appear in the form of one single dialog window< which is displayed o*er the document and does not permit any actions other than dialog processing until the dialog is ended. 5orms< on the other hand< are displayed directly in the document< just li-e drawing elements. " dialog editor is pro*ided for creating dialogs< and this can be found in the #pen#ffice.org $asic de*elopment en*ironment. 5orms are created using the 5orm ontrols and the 5orm Design Toolbar directly within the document. ,hereas the dialog functions are a*ailable in all #pen#ffice.org documents< the full scope of the form functions are only a*ailable in te9t and spreadsheets. The control elements of a form can be lin-ed with an e9ternal database table. This function is not a*ailable in dialogs. The control elements of dialogs and forms differ in se*eral aspects.
'sers who want to pro*ide their forms with their own methods for e*ent handling< should refer to the Dialogs chapter. The mechanisms e9plained there are identical to those for forms.
-or,i%g -ith 3orms

#pen#ffice.org forms may contain te9t fields< list bo9es< radio buttons< and a range of other control elements< which are inserted directly in a te9t or spreadsheet. The 5orm 5unctions Toolbar is used for editing forms. " #pen#ffice.org form may adopt one of two modes: the draft mode and the display mode. &n draft mode< the position of control elements can be changed and their properties can be edited using a properties window. The 5orm 5unctions Toolbar is also used to switch between modes.
0etermi%i%g Ob8ect 3orms

#pen#ffice.org positions the control elements of a form at drawing object le*el. The actual object form can be accessed through the 5orms list at the drawing le*el. The objects are accessed as follows in te9t documents:
"i# "o' $s 3b:e'( "i# "r 0M ge $s 3b:e'( "i# 8or# $s 3b:e'(
17-
)or*ing )it& 2orms
"o' = T&is7o#ponen( "r 0M ge = "o'1"r 0M ge 8or# = "r 0M ge18or#s1Ge(2.6n-ex(D)
The Ge(2.6n-ex method returns the form with the inde9 number 3. ,hen wor-ing with spreadsheets< an intermediate stage is needed for the Sheets list because the drawing le*els are not located directly in the document but in the indi*idual sheets:
"i# "i# "i# "i# "o' $s 3b:e'( S&ee( $s 3b:e'( "r 0M ge $s 3b:e'( 8or# $s 3b:e'(
"o' = T&is7o#ponen( S&ee( = "o'1S&ee(s1Ge(2.6n-ex(D) "r 0M ge = S&ee(1"r 0M ge 8or# = "r 0M ge18or#s1Ge(2.6n-ex(D)
"s is already suggested by the Ge(2.6n-ex method name< a document may contain se*eral forms. This is useful< for e9ample< if the contents of different databases are displayed within one document< or if a /:n database relationship is displayed within a form. The option of creating subGforms is also pro*ided for this purpose.
!he !hree spects of a Co%tro/ "/eme%t 3orm

" control element of a form has three aspects: The 6ode# of the control element is the -ey object for the #pen#ffice.org $asicGprogrammer when wor-ing with control element forms. The counterpart to this is the V%e- of the control element< which administers the display information. Since control element forms within the documents are administered li-e a special drawing element< there is also a /)ape o.3ec which reflects the drawing elementGspecific properties of the control element :in particular its position and siBe;.
ccessi%g the (ode/ of Co%tro/ "/eme%t 3orms

The models of the control elements of a form are a*ailable through the Ge(2.5 #e method of the #bject form:
"i# "o' $s 3b:e'( "i# 8or# $s 3b:e'( "i# 7(+ $s 3b:e'( "o' = T&is7o#ponen( 8or# = "o'1"r 0M ge18or#s1Ge(2.6n-ex(D) 7(+ = 8or#1ge(2.5 #e(@A.Lis(2ox@)
The e9ample determines the model of the A.Lis(2ox control element< which is located in the first form of the te9t document currently open. &f you are not sure of the form of a control element< you can use the option for searching through all forms for the control element re?uired:
"i# "i# "i# "i# "i# "o' $s 3b:e'( 8or#s $s 3b:e'( 8or# $s 3b:e'( 7(+ $s 3b:e'( 6 s 6n(eger
"o' = T&is7o#ponen( 8or#s = "o'1"r 0p ge18or#s 8or 6 = D To 8or#s17oun( H 1 8or# = 8or#s1Ge(b.6n-ex(6) 6) 8or#1B s2.5 #e(@A.Lis(2ox@) T&en 7(+ = 8or#1Ge(b.5 #e(@A.Lis(2ox@) Exi( 8un'(ion
17/
)or*ing )it& 2orms
En- 6) 5ex( 6
The e9ample uses the B s2.5 #e method to chec- all forms of a te9t document to determine whether they contain a control element model called A.Lis(2ox. &f a corresponding model is found< then a reference to this is sa*ed in the 7(+ *ariable and the search is terminated.
ccessi%g the .ie+ of Co%tro/ "/eme%t 3orms

To access the *iew of a control element form< you need the associated model. The *iew of the control element can then be determined with the assistance of the model and using the document controller.
"i# "i# "i# "i# "i# "i# "i# "o' $s 3b:e'( "o'7r+ $s 3b:e'( 8or#s $s 3b:e'( 8or# $s 3b:e'( 7(+ $s 3b:e'( 7(+4ie0 $s 3b:e'( 6 s 6n(eger
"o' = T&is7o#ponen( "o'7r+ = "o'1ge(7urren(7on(ro++er() 8or#s = "o'1"r 0p ge18or#s 8or 6 = D To 8or#s17oun( H 1 8or# = 8or#s1Ge(b.6n-ex(6) 6) 8or#1B s2.5 #e(@A.Lis(2ox@) T&en 7(+ = 8or#1Ge(b.5 #e(@A.Lis(2ox@) 7(+4ie0 = "o'7r+1Ge(7on(ro+(7(+) Exi( 8un'(ion En- 6) 5ex( 6
The code listed in the e9ample is *ery similar to the code listed in the pre*ious e9ample for determining a control element model. &t uses not only the "o' document object but also the "o'7r+ document controller object which ma-es reference to the current document window. ,ith the help of this controller object and the model of the control element< it then uses the Ge(7on(ro+ method to determine the *iew :7(+4ie0 *ariable; of the control element form.
ccessi%g the 2hape Ob8ect of Co%tro/ "/eme%t 3orms

The method for accessing the shape objects of a control element also uses the corresponding drawing le*el of the document. To determine a special control element< all drawing elements of the drawing le*el must be searched through.
"i# "o' $s 3b:e'( "i# S& pe s 3b:e'( "i# 6 s in(eger "o' = T&is7o#ponen( 8or i = D (o "o'1"r 0M ge17oun( H 1 S& pe = "o'1"r 0M ge(i) 6) B sNno6n(er) 'es(S& pe< @'o#1sun1s( r1-r 0ing1R7on(ro+S& pe@) T&en 6) S& pe17on(ro+15 #e = @A.Lis(2ox@ T&en Exi( 8un'(ion En- 6) En- 6) 5ex(
The e9ample chec-s all drawing elements to determine whether they support the com.sun.star.drawing.X ontrolShape interface needed for control element forms. &f this is the case< the 7on(ro+15 #e property then chec-s whether the name of the control element is A.Lis(2ox. &f this is true< the function ends the search.
%&apter 1" 2orms
177
)or*ing )it& 2orms
0etermi%i%g the 2iEe a%d Positio% of Co%tro/ "/eme%ts

"s already mentioned< the siBe and position of control elements can be determined using the associated s& pe object. The control element shape< li-e all other s& pe objects< pro*ides the SiXe and Mosi(ion properties for this purpose:
Si4e (struct)
siBe of control element :com.sun.star.awt.SiBe data structure;

2osition (struct)
position of control element :com.sun.star.awt.Point data structure; The following e9ample shows how the position and siBe of a control element can be set using the associated shape object:
"i# S& pe $s 3b:e'( "i# Moin( $s 5e0 'o#1sun1s( r1 0(1Moin( "i# SiXe $s 5e0 'o#1sun1s( r1 0(1SiXe % 111 6ni(i +iXe S& pe ob:e'(< Moin(1x = 1DDD Moin(1. = 1DDD SiXe1Ci-(& = 1DDDD SiXe1Beig&( = 1DDDD S& pe1SiXe = SiXe S& pe1Mosi(ion = Moin( s pre*ious+. s&o0n 111
The s& pe object of the control element must already be -nown if the code is to function. &f this is not the case< it must be determined using the preceding code.
Co%tro/ "/eme%t 3orms

The control elements a*ailable in forms are similar to those of dialogs. The selection ranges from simple te9t fields through list and combo bo9es to *arious buttons. $elow< you will find a list of the most important properties for control element forms. "ll properties form part of the associated model objects. &n addition to the standard control elements< a table control element is also a*ailable for forms< which enables the complete incorporation of database tables. This is described in the Database 5orms chapter.
Butto%s
The model object of a form button pro*ides the following properties:
Bac'groun%Color (long)
bac-ground color
De!aultButton (Boolean)
the button ser*es as a default *alue. &n this case< it also responds to the entry button if it has no focus
0nable% (Boolean)
the control element can be acti*ated

)abstop (Boolean)
the control element can be reached through the tabulator button
170
%ontro, 3,ement 2orms
)abIn%e1 (Long)
position of control element in acti*ation se?uence

-ontName (String)
name of font type

-ont(eight (Single)
height of character in points :pt;

)ag (String)
string containing additional information< which can be sa*ed in the button for programGcontrolled access
)argetU$L (String)
target '@L for buttons of the '@L type

)arget-rame (String)
name of window :or frame; in which T rge(N,L is to be opened when acti*ating the button :for buttons of the N,L type;
Label (String)
button label
)e1tColor (Long)

(elp)e1t (String)
automatically displayed help te9t which is displayed if the mouse cursor is abo*e the control element
(elpU$L (String)

Button) pe (0num)
action that is lin-ed with the button :default *alue from com.sun.star.form.5orm$uttonType;
State (Short)
in toggle button< / O pushed< 3 O normal Through the 2u((onT.pe property< you ha*e the opportunity to define an action that is automatically performed when the button is pressed. The associated com.sun.star.form.5orm$uttonType group of constants pro*ides the following *alues:
2US(
standard button
SUB"I)
end of form entry :particularly rele*ant for 7T)L forms;

$0S0)
resets all *alues within the form to their original *alues

U$L
call of the '@L defined in T rge(N,L :is opened within the window which was specified through
T rge(8r #e;
The 2? and >a$ce# button types pro*ided in dialogs are not supported in forms.
%&apter 1" 2orms
179
Optio% Butto%s
The following properties of an option button are a*ailable through its model object:
0nable% (Boolean)

)abstop (Boolean)
the control element can be reached through the tab -ey

)abIn%e1 (Long)
position of control element in the acti*ation se?uence

-ontName (String)
name of font type

-ont(eight (Single)

)ag (String)
Label (String)
inscription of button
2rintable (Boolean)

State (Short)
if /< the option is acti*ated< otherwise it is deacti*ated

$e!Value (String)
string for sa*ing additional information :for e9ample< for administering data record &Ds;
)e1tColor (Long)

(elp)e1t (String)
automatically displayed help te9t< which is displayed if the mouse cursor is abo*e the control element
(elpU$L (String)
'@L of online help for the corresponding control element The mechanism for grouping option buttons distinguishes between the control elements for dialogs and forms. ,hereas control elements appearing one after another in dialogs are automatically combined to form a group< grouping in forms is performed on the basis of names. To do this< all option buttons of a group must contain the same name. #pen#ffice.org combines the grouped control elements into an array so that the indi*idual buttons of a #pen#ffice.org $asic program can be reached in the same way. The following e9ample shows how the model of a control element group can be determined.
"i# "i# "i# "i# "i# "o' $s 3b:e'( 8or#s $s 3b:e'( 8or# $s 3b:e'( 7(+ $s 3b:e'( 6 s 6n(eger
"o' = T&is7o#ponen( 8or#s = "o'1"r 0p ge18or#s 8or 6 = D To 8or#s17oun( H 1 8or# = 8or#s1Ge(b.6n-ex(6) 6) 8or#1B s2.5 #e(@A.3p(ions@) T&en
100
7(+ = 8or#1 Ge(Groupb.5 #e(@A.3p(ions@) Exi( 8un'(ion En- 6) 5ex( 6
The code corresponds to the pre*ious e9ample for determining a simple control element model. &t searches through all forms in the current te9t document in a loop and uses the B s2.5 #e method to chec- whether the corresponding form contains an element with the A.3p(ions name it is searching for. &f this is the case< then the model array is accessed using the Ge(Group2.5 #e method :rather than the Ge(2.5 #e method to determine simple models;.
Chec,bo1es
The model object of a chec-bo9 form pro*ides the following properties:
0nable% (Boolean)

)abstop (Boolean)

)abIn%e1 (Long)

-ontName (String)
name of font type

-ont(eight (Single)

)ag (String)
Label (String)
button label
2rintable (Boolean)

State (Short)
if /< the option is acti*ated< otherwise it is deacti*ated

$e!Value (String)
string for sa*ing additional information :for e9ample< for administrating data record &Ds;
)e1tColor (Long)

(elp)e1t (String)
(elpU$L (String)
!e1t 3ie/ds
The model objects of te9t field forms offer the following properties:
%&apter 1" 2orms
101
Align (short)
orientation of te9t :3: leftGaligned< /: centered< !: rightGaligned;


Bor%er (short)

0choChar (String)
echo character for password field

-ontName (String)
name of font type

-ont(eight (Single)

(ar%LineBrea's (Boolean)
the automatic line brea-s are permanently inserted in the te9t of the control element
(Scroll (Boolean)
the te9t has a horiBontal scrollbar

"a1)e1tLen (Short)
ma9imum length of te9tM if 3 is specified< there are no limits

"ultiLine (Boolean)
permits multiGline entries

2rintable (Boolean)

$ea%.nl (Boolean)

0nable% (Boolean)

)abstop (Boolean)

)abIn%e1 (Long)
position of the control element in the acti*ation se?uence

-ontName (String)
name of font type

-ont(eight (Single)

)e1t (String)
te9t of control element

)e1tColor (Long)

VScroll (Boolean)
the te9t has a *ertical scrollbar
10"
(elp)e1t (String)
(elpU$L (String)
List Bo1es
The model object of the list bo9 forms pro*ides the following properties:

Bor%er (short)
type of border :3: no border< /: 1D frame< !: simple frame;

-ontDescriptor (struct)
structure with details of font to be used :in accordance with com.sun.star.awt.5ontDescriptor structure;
LineCount (Short)
number of lines of control element

"ultiSelection (Boolean)
permits multiple selection of entries

Selecte%Items (Arra o! Strings)
list of highlighted entries

StringItemList (Arra o! Strings)
list of all entries

ValueItemList (Arra o! Variant)
list containing additional information for each entry :for e9ample< for administrating data record &Ds;
2rintable (Boolean)

$ea%.nl (Boolean)

0nable% (Boolean)

)abstop (Boolean)

)abIn%e1 (Long)

-ontName (String)
name of font type

-ont(eight (Single)

)ag (String)
string containing additional information which can be sa*ed in the button for programGcontrolled access
%&apter 1" 2orms
103
)e1tColor (Long)

(elp)e1t (String)
(elpU$L (String)
'@L of online help for the corresponding control element Note VBA : Through their 4 +ue6(e#Lis( property< list bo9 forms pro*ide a counterpart to the .$" property< 6(e#" ( < through which you can administer additional information for indi*idual list entries. 5urthermore< the following methods are pro*ided though the *iew object of the list bo9:
a%%Item (Item# 2os)
inserts the string specified in the 6(e# at the Mos position in the list
a%%Items (ItemArra # 2os)
inserts the entries listed in the stringCs 6(e#$rr . data field in the list at the Mos position
remo3eItems (2os# Count)
remo*es 7oun( entries as of the Mos position

selectItem (Item# Select"o%e)
acti*ates or deacti*ates the highlighting for the element specified in the string 6(e# depending on the
Se+e'(Ao-e *ariable ma'eVisible (2os)
scrolls through the list field so that the entry specified by Mos is *isible
0atabase 3orms
#pen#ffice.org forms can be directly lin-ed to a database. The forms created in this way pro*ide all the functions of a full database front end without re?uiring independent programming wor-. You can page through and search in the selected tables and ?ueries< as well as change data records and insert new data records. #pen#ffice.org automatically ensures that the rele*ant data is retrie*ed from the database< and that any changes made are written bac- to the database. " database form corresponds to a standard #pen#ffice.org form. &n addition to the standard properties< the following databaseGspecific properties must also be set in the form:
DataSourceName (String)
name of data source :refer to Database "ccessM the data source must be globally created in #pen#ffice.org;
Comman% (String)
name of table< ?uery< or the S>L select command to which a lin- is to be made
Comman%) pe (Const)
specifies whether the ommand is a table< a ?uery or a S>L command :*alue from com.sun.star.sdb. ommandType enumeration; The com.sun.star.sdb. ommandType enumeration co*ers the following *alues:
)ABL0
Table
6atabase 2orms
;U0$&
>uery
C.""AND
S>L command The database fields are assigned to the indi*idual control elements through this property:
Data-iel% (String)
name of lin-ed database field
!ab/es
"nother control element is pro*ided for wor- with databases< the table control element. This represents the content of a complete database table or ?uery. &n the simplest scenario< a table control element is lin-ed to a database using the autopilot form< which lin-s all columns with the rele*ant database fields in accordance with the user specifications.
%&apter 1" 2orms
10-

BG3400 BasicProgrammersGuide

Transféré par

Informations du document

Description originale:

Titre original

Copyright

Formats disponibles

Partager ce document

Partager ou intégrer le document

Options de partage

Avez-vous trouvé ce document utile ?

Ce contenu est-il inapproprié ?

Droits d'auteur :

Formats disponibles

BG3400 BasicProgrammersGuide

Transféré par

Droits d'auteur :

Formats disponibles

LibreOffice 3.

4 Basic Programmer's Guide

OpenOffice.org BASIC Programming Guide

The Language of #pen#ffice.org $asic @untime Library &ntroduction to the "P&

bout Ope%Office.org Basic

About OpenOffice.org Basic

&%te%ded 'sers of Ope%Office.org Basic

'se of Ope%Office.org Basic

LibreOffice 3.4 Basic Programmer's Guide !eptember "011

The Language of OpenOffice.org BASIC

O*er*ie+ of a Basic Program

O#er#ie$ of a Basic Program

can be written as follows:

"ll characters that follow an apostrophe are treated as comments:

The -eyword ,e#< followed by the comment:

,e# T&is 'o##en( is in(ro-u'e- b. (&e /e.0or- ,e#1

LibreOffice 3.4 Basic Programmer's Guide !eptember "011

O#er#ie$ of a Basic Program

-or,i%g -ith .ariab/es

"1p/icit .ariab/e 0ec/aratio%

%&apter " '&e Language of OpenOffice.org BA!(%

)or*ing )it& +ariab,es

The Dim instruction can record se*eral *ariable declarations:

3rom a 2et of 2C&& Characters to '%icode

!he 2C&& Character 2et

!he N2& Character 2et

LibreOffice 3.4 Basic Programmer's Guide !eptember "011

You can also write this declaration as:

2pecificatio% of "1p/icit 2tri%gs

&nteger Long &nteger Single Double urrency

%&apter " '&e Language of OpenOffice.org BA!(%

Lo%g &%teger .ariab/es

LibreOffice 3.4 Basic Programmer's Guide !eptember "011

2pecificatio% of "1p/icit Numbers

%&apter " '&e Language of OpenOffice.org BA!(%

"1po%e%tia/ -riti%g 2ty/e

LibreOffice 3.4 Basic Programmer's Guide !eptember "011

0ate a%d !ime

%&apter " '&e Language of OpenOffice.org BA!(%

2pecified .a/ue for 2tart &%de1

(u/ti40ime%sio%a/ 0ata 3ie/ds

0y%amic Cha%ges i% the 0ime%sio%s of 0ata 3ie/ds

LibreOffice 3.4 Basic Programmer's Guide !eptember "011

use the following call:

0etermi%i%g the 0ime%sio%s of 0ata 3ie/ds

%&apter " '&e Language of OpenOffice.org BA!(%

0efi%i%g *a/ues for arrays

rray Creatio%5 *a/ue assig%me%t a%d access e1amp/e

2cope a%d Life 2pa% of .ariab/es

LibreOffice 3.4 Basic Programmer's Guide !eptember "011

!cope and Life !pan of +ariab,es

Pub/ic 0omai% .ariab/es

define the *ariable:

%&apter " '&e Language of OpenOffice.org BA!(%

!cope and Life !pan of +ariab,es

Sub S&o04 r$ Asg2ox 7 En- Sub

% S&o0s (&e * ri b+e 7 )ro# #o-u+e $1

You can also specify the constant type in the declaration:

LibreOffice 3.4 Basic Programmer's Guide !eptember "011

6?uality of numbers< date *alues and strings

%&apter " '&e Language of OpenOffice.org BA!(%

The second e9ample of this page may be written as:

Oerie+ of a Basic Program

The Dim instruction can record seeral ariable declarations:

conerts any data types into an integer alue.

conerts any data types into a long alue.

conerts any data types into a single alue.

conerts any data types into a double alue.

conerts any data types into a $oolean alue.