LibreOffice 3 Basic Guide PDF

LibreOffice 3
Basic Guide
Using LibreOffice Basic in LibreOffice 3
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
Contributors
Feedback
This book is based on OpenOffice.or !." #asic $uide.
Publication date and software version
Published
%e need a re&iew of this work to suit the #asic LibreOffice !.' and !.() please know well who
re&iew and update for translations into &arious lanuaes. Thanks a lot for your work and
collaboration.
Difficult due to the di&ision into chapters reference fields inserted.
*aul Pacheco da Sil&a
Contents
Copyright..................................................................................................................................................... 2
ote for !ac "sers...................................................................................................................................... #
Chapter $
Programming %"i&e......................................................................................................................................... '
LibreOffice B()*C Programming %"i&e...................................................................................................... +
*nten&e& Users of LibreOffice Basic............................................................................................................ +
Use of LibreOffice Basic.............................................................................................................................. ,
!ore *nformation......................................................................................................................................... ,
Chapter 2
-he Lang"age of LibreOffice Basic................................................................................................................. $$
-he Lang"age of LibreOffice Basic........................................................................................................... $2
O.er.iew of a Basic Program.................................................................................................................... $2
/or0ing /ith 1ariables............................................................................................................................. $3
)trings....................................................................................................................................................... $2
"mbers.................................................................................................................................................... $#
Date an& -ime........................................................................................................................................... $,
(rrays........................................................................................................................................................ $,
)cope an& Life )pan of 1ariables............................................................................................................. 22
Constants.................................................................................................................................................. 23
Operators.................................................................................................................................................. 22
Branching.................................................................................................................................................. 23
Loops......................................................................................................................................................... 2'
Proce&"res an& 4"nctions......................................................................................................................... 2,
5rror 6an&ling........................................................................................................................................... 32
Other *nstr"ctions...................................................................................................................................... 32
Chapter 3
7"ntime Library.............................................................................................................................................. 3'
7"ntime Library......................................................................................................................................... 3+
Con.ersion 4"nctions................................................................................................................................ 3+
)trings....................................................................................................................................................... 2$
Date an& -ime........................................................................................................................................... 23
4iles an& Directories.................................................................................................................................. 23
!essage an& *np"t Bo8es......................................................................................................................... 2,
Other 4"nctions......................................................................................................................................... 32
Chapter 2
*ntro&"ction to the (P*.................................................................................................................................... 33
*ntro&"ction to the (P*............................................................................................................................... 3#
Uni.ersal etwor0 Ob9ects :UO;............................................................................................................. 3#
Properties an& !etho&s............................................................................................................................ 3#
!o&"les< )er.ices an& *nterfaces............................................................................................................. 3'
-ools for /or0ing with UO...................................................................................................................... 3+
O.er.iew of Central *nterfaces.................................................................................................................. 3,
Chapter 3
/or0ing with Doc"ments................................................................................................................................ #3
/or0ing with Doc"ments........................................................................................................................... #2
)tyles an& -emplates................................................................................................................................ '$
Chapter #
-e8t Doc"ments.............................................................................................................................................. '3
LibreOffice 3 Basic %"i&e 3
-e8t Doc"ments......................................................................................................................................... '#
-he )tr"ct"re of -e8t Doc"ments.............................................................................................................. '#
5&iting -e8t Doc"ments............................................................................................................................. +2
!ore -han ="st -e8t.................................................................................................................................. +,
Chapter '
)prea&sheet Doc"ments................................................................................................................................ ,,
)prea&sheet Doc"ments......................................................................................................................... $>>
-he )tr"ct"re of )prea&sheets................................................................................................................ $>>
5&iting )prea&sheet Doc"ments............................................................................................................. $$'
Chapter +
Drawings an& Presentations......................................................................................................................... $2$
Drawings an& Presentations.................................................................................................................... $22
-he )tr"ct"re of Drawings....................................................................................................................... $22
5&iting Drawing Ob9ects.......................................................................................................................... $3#
Presentations.......................................................................................................................................... $3,
Chapter ,
Charts :Diagrams;........................................................................................................................................ $2$
Charts :Diagrams;................................................................................................................................... $22
Using Charts in )prea&sheets................................................................................................................. $22
-he )tr"ct"re of Charts........................................................................................................................... $23
Chart -ypes............................................................................................................................................. $32
Chapter $>
Databases.................................................................................................................................................... $33
Databases............................................................................................................................................... $3#
)?L: a ?"ery Lang"age.......................................................................................................................... $3#
-ypes of Database (ccess...................................................................................................................... $3#
Data )o"rces........................................................................................................................................... $3'
Database (ccess..................................................................................................................................... $3,
Chapter $$
Dialogs......................................................................................................................................................... $#3
Dialogs.................................................................................................................................................... $#2
/or0ing /ith Dialogs.............................................................................................................................. $#2
Properties................................................................................................................................................ $#'
5.ents..................................................................................................................................................... $#,
Dialog Control 5lements.......................................................................................................................... $'3
Chapter $2
4orms........................................................................................................................................................... $+$
4orms...................................................................................................................................................... $+2
Chapter $3
Calc as a )imple Database.......................................................................................................................... $,3
*ntro&"ction.............................................................................................................................................. $,2
(ssociating a range with a name............................................................................................................. $,3
)orting..................................................................................................................................................... 2>>
4ilters....................................................................................................................................................... 2>$
Calc f"nctions similar to &atabase f"nctions............................................................................................ 2>+
Database@specific f"nctions..................................................................................................................... 2$#
Concl"sion............................................................................................................................................... 2$'
Chapter $2
)etting "p an& C"stomiAing Calc.................................................................................................................. 2$,
*ntro&"ction.............................................................................................................................................. 22>
2 LibreOffice 3 Basic %"i&e
Choosing options that affect all of LibreOffice......................................................................................... 22>
Choosing options for loa&ing an& sa.ing &oc"ments.............................................................................. 222
Choosing options for Calc....................................................................................................................... 22+
Controlling CalcBs ("toCorrect f"nctions................................................................................................. 233
C"stomiAing the "ser interface................................................................................................................ 23#
(&&ing f"nctionality with e8tensions........................................................................................................ 222
(ppen&i8 (
Ceyboar& )hortc"ts...................................................................................................................................... 22'
*ntro&"ction.............................................................................................................................................. 22+
a.igation an& selection shortc"ts.......................................................................................................... 22+
4"nction 0ey shortc"ts............................................................................................................................. 22,
(rrow 0ey shortc"ts................................................................................................................................. 23>
Cell formatting shortc"ts.......................................................................................................................... 23>
DataPilot shortc"ts.................................................................................................................................. 23$
(ppen&i8 B
Description of 4"nctions............................................................................................................................... 233
4"nctions a.ailable in Calc...................................................................................................................... 232
!athematical f"nctions............................................................................................................................ 232
4inancial analysis f"nctions..................................................................................................................... 23+
)tatistical analysis f"nctions.................................................................................................................... 2#'
Date an& time f"nctions........................................................................................................................... 2'3
Logical f"nctions...................................................................................................................................... 2'3
*nformational f"nctions............................................................................................................................ 2'#
Database f"nctions.................................................................................................................................. 2'+
(rray f"nctions........................................................................................................................................ 2',
)prea&sheet f"nctions............................................................................................................................. 2+$
-e8t f"nctions.......................................................................................................................................... 2+2
(&&@in f"nctions....................................................................................................................................... 2+#
(ppen&i8 C
Calc 5rror Co&es.......................................................................................................................................... 2,$
*ntro&"ction to Calc error co&es.............................................................................................................. 2,2
5rror co&es &isplaye& within cells........................................................................................................... 2,3
%eneral error co&es................................................................................................................................. 2,2
*n&e8............................................................................................................................................................. 2,'
LibreOffice 3 Basic %"i&e 3
Note for Mac users
Some keystrokes and menu items are different on a +ac from those used in %indows and Linu,. The table
below i&es some common substitutions for the instructions in this chapter. -or a more detailed list) see the
application .elp.
Windows/Linux Mac equivalent Effect
Tools > Options menu
selection
OpenOffice.org > Preferences /ccess setup options
7ight@clic0 ControlDclic0 Open conte,t menu
Ctrl :Control; :Comman&; 0sed with other keys
43 )hiftDD43 Open the 1a&iator
4$$ 2- Open Styles 3 -ormattin window
# LibreOffice 3 Basic %"i&e
#asic $uide
Chapter $
Programming %"i&e
Using LibreOffice Basic in LibreOffice
ibreOffice !"#$C Progra%%ing &uide
This uide pro&ides an introduction to prorammin with LibreOffice #asic. To et the most out of this book)
you should be familiar with other prorammin lanuaes. 4,tensi&e e,amples are pro&ided to help you
5uickly de&elop your own LibreOffice #asic prorams.
This uide di&ides information about LibreOffice administration into se&eral chapters. The first three chapters
introduce you to LibreOffice #asic:
The Lanuae of LibreOffice #asic
*untime Library
6ntroduction to the /P6
These chapters pro&ide an o&er&iew of LibreOffice #asic and should be read by anyone who intends to write
LibreOffice #asic prorams. The remainin chapters describe the indi&idual components of the LibreOffice
/P6 in more detail and can be read selecti&ely as re5uired:
%orkin with Documents
Te,t Documents
Spreadsheet Documents
Drawins and Presentations
7harts 8Diarams9
Databases
Dialos
-orms
/bout LibreOffice #asic. The LibreOffice #asic prorammin lanuae has been de&eloped especially for
LibreOffice and is firmly interated in the Office packae.
/s the name suests) LibreOffice #asic is a prorammin lanuae from the #asic family. /nyone who has
pre&iously worked with other #asic lanuaes : in particular with ;isual #asic or ;isual #asic for
/pplications 8;#/9 from +icrosoft : will 5uickly become accustomed to LibreOffice #asic. Lare sections of
the basic constructs of LibreOffice #asic are compatible with ;isual #asic.
The LibreOffice #asic prorammin lanuae can be di&ided into four components:
The lanuae of LibreOffice #asic: Defines the elementary linuistic constructs) for e,ample) for &ariable
declarations) loops) and functions.
The runtime library: Pro&ides standard functions which ha&e no direct reference to LibreOffice) for
e,ample) functions for editin numbers) strins) date &alues) and files.
The LibreOffice /P6 8/pplication Prorammin 6nterface9: Permits access to LibreOffice documents and
allows these to be created) sa&ed) modified) and printed.
he Dialo 4ditor: 7reates personal dialo windows and pro&ides scope for the addin of control elements
and e&ent handlers.
Note
7ompatibility between LibreOffice #asic and ;#/ relates to the LibreOffice #asic lanuae
as well as the runtime library. The LibreOffice /P6 and the Dialo 4ditor are not compatible
with ;#/ 8standardi<in these interfaces would ha&e made many of the concepts pro&ided
in LibreOffice impossible9.
$ntended 'sers of ibreOffice !asic
The scope of application for LibreOffice #asic beins where the standard functions of LibreOffice end.
*outine tasks can therefore be automated in LibreOffice #asic) links can be made to other prorams : for
e,ample to a database ser&er : and comple, acti&ities can be performed at the press of a button by usin
predefined scripts.
+ LibreOffice 3 Basic %"i&e
LibreOffice #asic offers complete access to all LibreOffice functions) supports all functions) modifies
document types) and pro&ides options for creatin personal dialo windows.
'se of ibreOffice !asic
LibreOffice #asic can be used by any LibreOffice user without any additional prorams or aids. 4&en in the
standard installation) LibreOffice #asic has all the components needed to create its own #asic macros)
includin:
The interated de&elopment en&ironment 86D49 which pro&ides an editor for creatin and testin macros.
The interpreter) which is needed to run LibreOffice #asic macros.
The interfaces to &arious LibreOffice applications) which allow for direct access to Office documents.
More $nfor%ation
The components of the LibreOffice /P6 that are discussed in this uide were selected based on their
practical benefits for the LibreOffice #asic prorammer. 6n eneral) only parts of the interfaces are discussed.
-or a more detailed picture) see the (P* reference.
The De.eloperEs %"i&e describes the LibreOffice /P6 in more detail than this uide) but is primarily intended
for =a&a and 722 prorammers. /nyone who is already familiar with LibreOffice #asic prorammin can find
additional information in the De&eloper>s $uide on LibreOffice #asic and LibreOffice prorammin.
Prorammers who want to work directly with =a&a or 722 rather than LibreOffice #asic should consult the
LibreOffice De&eloper>s $uide instead of this uide. LibreOffice prorammin with =a&a or 722 is a
considerably more comple, process than prorammin with LibreOffice #asic.
Chapter $2 4orms ,
#asic $uide
Chapter 2
-he Lang"age of LibreOffice
Basic
The anguage of ibreOffice !asic
LibreOffice #asic belons to the family of #asic lanuaes. +any parts of LibreOffice #asic are identical to
+icrosoft ;isual #asic for /pplications and +icrosoft ;isual #asic. /nyone who has already worked with
these lanuaes can 5uickly become accustomed to LibreOffice #asic.
Prorammers of other lanuaes ? such as =a&a) 722) or Delphi ? should also find it easy to familiari<e
themsel&es with LibreOffice #asic. LibreOffice #asic is a fully@de&eloped procedural prorammin lanuae
and no loner re5uires rudimentary control structures) such as GoTo and GoSub.
You can also benefit from the ad&antaes of object@oriented prorammin since an interface in LibreOffice
#asic enables you to use e,ternal object libraries. The entire LibreOffice /P6 is based on these interfaces)
which are described in more detail in the followin chapters of this document.
This chapter pro&ides an o&er&iew of the key elements and constructs of the LibreOffice #asic lanuae) as
well as the framework in which applications and libraries are oriented to LibreOffice #asic.
Overview of a !asic Progra%
LibreOffice #asic is an interpreter lanuae. 0nlike 722 or Delphi) the LibreOffice #asic compiler does not
create e,ecutable or self@e,tractin files that are capable of runnin automatically. 6nstead) you e,ecute an
LibreOffice #asic proram inside LibreOffice. The code is first checked for ob&ious errors and then e,ecuted
line by line.
Progra% ines
The #asic interpreter>s line@oriented e,ecution produces one of the key differences between #asic and other
prorammin lanuaes. %hereas the position of hard line breaks in the source code of =a&a) 722) or Delphi
prorams is irrele&ant) each line in a #asic proram forms a self@contained unit. -unction calls) mathematical
e,pressions) and other linuistic elements) such as function and loop headers) must be completed on the
same line that they bein on.
6f there is not enouh space) or if this results in lon lines) then se&eral lines can be linked toether by
addin underscores A. The followin e,ample shows how four lines of a mathematical e,pression can be
linked:
LongExpression = (Expression1 * Expression2) +
_(Expression3 * Expression4) + _ (Expression5 *
Expression6) + _(Expression7 * Expression8)
Note
The underscore must always be the last character in a linked line and cannot be followed by
a space or a tab or a comment) otherwise the code enerates an error.
6n addition to linkin indi&idual lines) in LibreOffice #asic you can use colons to di&ide one line into se&eral
sections) so that there is enouh space for se&eral e,pressions. The assinments
= 1 = + 1 = + 1
can be written as follows:
= 1 ! = + 1 ! = + 1
Co%%ents
6n addition to the proram code to be e,ecuted) an LibreOffice #asic proram can also contain comments
that e,plain the indi&idual parts of the proram and pro&ide important information that can be helpful at a
later point.
LibreOffice #asic pro&ides two methods for insertin comments in the proram code:
/ll characters that follow an apostrophe are treated as comments:
"i# $ % T&is is 'o##en( )or *rib+e $
Chapter $2 4orms $$
The keyword ,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. LibreOffice #asic then interprets the
followin line as a reular instruction aain. 6f comments co&er se&eral lines) each line must be identified as
a comment:
"i# 2 % T&is 'o##en( )or *rib+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
Markers
/ LibreOffice #asic proram can contain do<ens) hundreds) or e&en thousands of markers) which are names
for &ariables) constants) functions) and so on. %hen you select a name for a marker) the followin rules
apply:
+arkers can only contain Latin letters) numbers) and underscores 8A9.
The first character of a marker must be a letter or an underscore.
+arkers cannot contain special characters) such as B C D E.
The ma,imum lenth of a marker is "(( characters.
1o distinction is made between uppercase and lowercase characters. The 3neTes(4rib+e marker) for
e,ample) defines the same &ariable as one(es(4rib+e and 35ETEST4$,6$2LE.
There is) howe&er) one e,ception to this rule: a distinction is made between uppercase and lowercase
characters for 01O@/P6 constants. +ore information about 01O is presented in 6ntroduction to the /P6
Note
The rules for constructin markers are different in LibreOffice #asic than in ;#/. -or
e,ample) LibreOffice #asic only allows special characters in markers when usin 3p(ion
7o#p(ib+e) since they can cause problems in international projects.
.ere are a few e,amples of correct and incorrect markers:
Surn#e % 7orre'(
Surn#e5 % 7orre'( (nu#ber 5 is no( (&e )irs( -igi()
8irs( 5#e % 6n'orre'( (sp'es re no( per#i((e-)
"9:;4u % 6n'orre'( (+e((ers su'& s 9< ; re no(
per#i((e-)
5Surn#es % 6n'orre'( ((&e )irs( '&r'(er #us( no( be
nu#ber)
8irs(<5#e % 6n'orre'( ('o##s n- )u++ s(ops re no(
per#i((e-)
4nclosin a &ariable name in s5uare brackets allows names that miht otherwise be disallowedF for e,ample)
spaces.
"i# =8irs( 5#e> $s S(ring %Sp'e ''ep(e- in s?ure
br'/e(s
"i# ="9:;4u> $s 6n(eger %Spe'i+ '&r'(ers in
s?ure br'/e(s
=8irs( 5#e> = @$n-re0@
="9:;4u> = 2
(orking (ith )ariables
$%plicit )ariable *eclaration
#asic lanuaes are desined to be easy to use. /s a result) LibreOffice #asic enables the creation of a
&ariable throuh simple usae and without an e,plicit declaration. 6n other words) a &ariable e,ists from the
$2 LibreOffice 3 Basic %"i&e
moment that you include it in your code. Dependin on the &ariables that are already present) the followin
e,ample declares up to three new &ariables:
= b + '
Declarin &ariables implicitly is not ood prorammin practice because it can result in the inad&ertent
introduction of a new &ariable throuh) for e,ample) a typin error. 6nstead of producin an error messae)
the interpreter initiali<es the typin error as a new &ariable with a &alue of G. 6t can be &ery difficult to locate
errors of this kind in your code.
+,plicit )ariable *eclaration
To pre&ent errors caused by an implicit declaration of &ariables) LibreOffice #asic pro&ides a switch called:
3p(ion Exp+i'i(
This must be listed in the first proram line of each module and ensures that an error messae 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.
6n its simplest form) the command for an e,plicit declaration of a &ariable is as follows:
"i# A.4r
This e,ample declares a &ariable with the name A.4r and the type *rin(. / &ariant is a uni&ersal
&ariable that can record all concei&able &alues) includin strins) whole numbers) floatin point fiures) and
#oolean &alues. .ere are a few e,amples of ;ariant &ariables:
A.4r = @Be++o Cor+-@ % $ssign#en( o) s(ring
A.4r = 1 % $ssign#en( o) 0&o+e nu#ber
A.4r = 11D % $ssign#en( o) )+o(ing
poin( nu#ber
A.4r = True % $ssign#en( o) 2oo+en *+ue
The &ariables declared in the pre&ious e,ample can e&en be used for different &ariable types in the same
proram. /lthouh this pro&ides considerable fle,ibility) it is best to restrict a &ariable to one &ariable type.
%hen LibreOffice #asic encounters an incorrectly defined &ariable type in a particular conte,t) an error
messae is enerated.
0se the followin style when you make a type@bound &ariable declaration:
"i# A.4r $s 6n(eger % "e'+r(ion o) *rib+e o) (&e
in(eger (.pe
The &ariable is declared as an inteer type and can record whole number &alues. You can also use the
followin style to declare an inteer type &ariable:
"i# A.4rE % "e'+r(ion o) *rib+e o) (&e
in(eger (.pe
The Dim instruction can record se&eral &ariable declarations:
"i# A.4r1< A.4r2
6f you want to assin the &ariables to a permanent type) you must make separate assinments for each
&ariable:
"i# A.4r1 $s 6n(eger< A.4r2 $s 6n(eger
6f you do not declare the type for a &ariable) LibreOffice #asic assins the &ariable a &ariant type. -or
e,ample) in the followin &ariable declaration) A.4r1 becomes a &ariant and A.4r2 becomes an inteer:
"i# A.4r1< A.4r2 $s 6n(eger
The followin sections list the &ariable types that are a&ailable in LibreOffice #asic and describe how they
can be used and declared.
#trings
Strins) toether with numbers) form the most important basic types of LibreOffice #asic. / strin consists of
a se5uence of consecuti&e indi&idual characters. The computer sa&es the strins internally as a se5uence of
numbers where each number represents one specific character.
Chapter $2 4orms $3
Fro% a #et of "#C$$ Characters to 'nicode
7haracter sets match characters in a strin with a correspondin code 8numbers and characters9 in a table
that describes how the computer is to display the strin.
The A!"" !haracter et
The /S766 character set is a set of codes that represent numbers) characters) and special symbols by one
byte. The G to H"I /S766 codes correspond to the alphabet and to common symbols 8such as periods)
parentheses) and commas9) as well as some special screen and printer control codes. The /S766 character
set is commonly used as a standard format for transferrin te,t data between computers.
.owe&er) this character set does not include a rane of special characters used in 4urope) such as C) B) and
D) as well as other character formats) such as the 7yrillic alphabet.
The A#" !haracter et
+icrosoft based its %indows product on the /merican 1ational Standards 6nstitute 8/1S69 character set)
which was radually e,tended to include characters that are missin from the /S766 character set.
Code Pages
The 6SO JJ(K character sets pro&ide an international standard. The first H"J characters of the 6SO character
set correspond to the /S766 character set. The 6SO standard introduces new character sets 8code pages9 so
that more lanuaes can be correctly displayed. .owe&er) as a result) the same character &alue can
represent different characters in different lanuaes.
'nicode
0nicode increases the lenth of a character to four bytes and combines different character sets to create a
standard to depict as many of the world>s lanuaes as possible. ;ersion ".G of 0nicode is now supported by
many prorams : includin LibreOffice and LibreOffice #asic.
#tring )ariables
LibreOffice #asic sa&es strins as strin &ariables in 0nicode. / strin &ariable can store up to L((!(
characters. 6nternally) LibreOffice #asic sa&es the associated 0nicode &alue for e&ery character. The workin
memory needed for a strin &ariable depends on the lenth of the strin.
4,ample declaration of a strin &ariable:
"i# 4rib+e $s S(ring
You can also write this declaration as:
"i# 4rib+eF
Note
%hen portin ;#/ applications) ensure that the ma,imum allowed strin lenth in
LibreOffice #asic is obser&ed 8L((!( characters9.
#pecification of +,plicit #trings
To assin an e,plicit strin to a strin &ariable) enclose the strin in 5uotation marks 8M9.
"i# A.S(ring $s S(ring
A.S(ring = @ T&is is (es(@
To split a strin across two lines of code) add an ampersand sin 8the concatenation operator9 and the
underscore continuation character at the end of the first line:
A.S(ring = @T&is s(ring is so +ong (&( i( @ G _
@&s been sp+i( o*er (0o +ines1@
To include a 5uotation mark 8M9 in a strin) enter it twice at the rele&ant point:
A.S(ring = @ @@H?uo((ion #r/1@ % pro-u'es @H
?uo((ion #r/
Nu%bers
LibreOffice #asic supports fi&e basic types for processin numbers:
H.6nteer
".Lon 6nteer
!.Sinle
'.Double
(.7urrency
$nteger )ariables
6nteer &ariables can store any whole number between -32768and 32767. /n inteer &ariable can take up to
two bytes of memory. The type declaration symbol for an inteer &ariable is E. 7alculations that use inteer
&ariables are &ery fast and are particularly useful for loop counters. 6f you assin a floatin point number to
an inteer &ariable) the number is rounded up or down to the ne,t whole number.
4,ample declarations for inteer &ariables:
"i# 4rib+e $s 6n(eger
"i# 4rib+eE
ong $nteger )ariables
Lon inteer &ariables can store any whole number between 2147483648and 2147483647. / lon inteer
&ariable can takes up to four bytes of memory. The type declaration symbol for a lon inteer is G.
7alculations with lon inteer &ariables are &ery fast and are particularly useful for loop counters. 6f you
assin a floatin point number to a lon inteer &ariable) the number is rounded up or down to the ne,t whole
number.
4,ample declarations for lon inteer &ariables:
"i# 4rib+e s Long
"i# 4rib+eG
#ingle )ariables
Sinle &ariables can store any positi&e or neati&e floatin point number between 3.402823 x 10
38
and
1.401298 x 10
-45
. / sinle &ariable can take up to four bytes of memory. The type declaration symbol for a
sinle &ariable is I.
Oriinally) sinle &ariables were used to reduce the computin time re5uired for the more precise double
&ariables. .owe&er) these speed considerations no loner apply) reducin the need for sinle &ariables.
4,ample declarations for sinle &ariables:
"i# 4rib+e s Sing+e
"i# 4rib+eI
*ouble )ariables
Double &ariables can store any positi&e or neati&e floatin point numbers between 1.79769313486232 x 10
308
and 4.94065645841247 x 10
-324
. / double &ariable can take up to eiht bytes of memory. Double &ariables are
suitable for precise calculations. The type declaration symbol is J.
4,ample declarations of double &ariables:
Chapter $2 4orms $3
"i# 4rib+e $s "oub+e
"i# 4rib+eJ
Currency )ariables
7urrency &ariables differ from the other &ariable types by the way they handle &alues. The decimal point is
fi,ed and is followed by four decimal places. The &ariable can contain up to H( numbers before the decimal
point. / currency &ariable can store any &alue between -922337203685477.5808and +922337203685477.5807
and takes up to eiht bytes of memory. The type declaration symbol for a currency &ariable is K.
7urrency &ariables are mostly intended for business calculations that yield unforeseeable roundin errors
due to the use of floatin point numbers.
4,ample declarations of currency &ariables:
"i# 4rib+e $s 7urren'.
"i# 4rib+eK
(arning
The handlin of #asic 7urrency type is not reliable. "ssue 3$%%$ "ssue &'%'( "ssue
($$)$ "ssue $%*)** are still not corrected on LibreOffice &ersion !.H.H.
Floats
The types sinle) double and currency are often collecti&ely referred to as floats) or floatin@point number
types. They can contain numerical &alues with decimal fractions of &arious lenth) hence the name: The
decimal point seems to be able to >float> throuh the number.
You can declare &ariables of the type float. The actual &ariable type 8sinle) lon) currency9 is determined the
moment a &alue is assined to the &ariable:
"i# $ $s 8+o(
$ = 121D1126
#pecification of +,plicit Nu%bers
1umbers can be presented in se&eral ways) for e,ample) in decimal format or in scientific notation) or e&en
with a different base than the decimal system. The followin rules apply to numerical characters in
LibreOffice #asic:
Whole #u+bers
The simplest method is to work with whole numbers. They are listed in the source te,t without a comma
separatin the thousand fiure:
"i# $ $s 6n(eger
"i# 2 $s 8+o(
$ = 121D
2 = 2438
The numbers can be preceded by both a plus 829 or minus 8@9 sin 8with or without a space in between9:
"i# $ $s 6n(eger
"i# 2 $s 8+o(
$ = + 121
2 = H 243
*eci%al Nu%bers
%hen you type a decimal number) use a period 8.9 as the decimal point. This rule ensures that source te,ts
can be transferred from one country to another without con&ersion.
"i# $ $s 6n(eger
$# LibreOffice 3 Basic %"i&e
"i# 2 $s 6n(eger
"i# 7 $s 8+o(
$ = 1223153 % is roun-e-
2 = H 23446146 % is roun-e-
7 = + 3532176323
You can also use plus 829 or minus 8@9 sins as prefi,es for decimal numbers 8aain with or without spaces9.
6f a decimal number is assined to an inteer &ariable) LibreOffice #asic rounds the fiure up or down.
+,ponential (riting #tyle
LibreOffice #asic allows numbers to be specified in the e,ponential writin style) for e,ample) you can write
115eH1D for the number H.( , HG
-10
8G.GGGGGGGGGH(9. The letter MeM can be lowercase or uppercase with or
without a plus sin 829 as a prefi,.
.ere are a few correct and incorrect e,amples of numbers in e,ponential format:
"i# $ $s "oub+e
$ = 1143E2 % 7orre'(
$ = + 1143E2 % 7orre'( (sp'e be(0een p+us n- bsi'
nu#ber)
$ = H 1143E2 % 7orre'( (sp'e be(0een #inus n- bsi'
nu#ber)
$ = 1143EH2 % 7orre'( (neg(i*e exponen()
$ = 1143E H2 % 6n'orre'( (sp'es no( per#i((e- 0i(&in (&e
nu#ber)
$ = 1<43EH2 % 6n'orre'( ('o##s no( per#i((e- s -e'i#+
poin(s)
$ = 1143E212 % 6n'orre'( (exponen( #us( be 0&o+e
nu#ber)
1ote) that in the first and third incorrect e,amples that no error messae is enerated e&en thouh the
&ariables return incorrect &alues. The e,pression
$ = 1143E H2
is interpreted as H.'! minus ") which corresponds to the &alue @G.(I. .owe&er) the &alue H.'! , HG
-2

8correspondin to G.GH'!9 was the intended &alue. %ith the &alue
$ = 1143E212
LibreOffice #asic inores the part of the e,ponent after the decimal point and interprets the e,pression as
$ = 1143E2
-e,adeci%al )alues
6n the he,adecimal system 8base HL system9) a "@diit number corresponds to precisely one byte. This
allows numbers to be handled in a manner which more closely reflects machine architecture. 6n the
he,adecimal system) the numbers G to K and the letters / to - are used as numbers. /n / stands for the
decimal number HG) while the letter - represents the decimal number H(. LibreOffice #asic lets you use
whole numbered he,adecimal &alues) so lon 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
Octal )alues
LibreOffice #asic also understands the octal system 8base J system9) which uses the numbers G to I. You
must use whole numbers that are preceded by G3.
Chapter $2 4orms $'
"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
!oolean )alues
#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 two@byte
inteer &alue) where G corresponds to the -alse and any other &alue to True. There is no type declaration
symbol for #oolean &ariables. The declaration can only be made usin the supplement $s 2oo+en.
4,ample declaration of a #oolean &ariable:
"i# 4rib+e $s 2oo+en
*ate and Ti%e
Date &ariables can contain date and time &alues. %hen sa&in date &alues) LibreOffice #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 usin the supplement $s
"(e.
4,ample declaration of a date &ariable:
"i# 4rib+e $s "(e
"rrays
6n addition to simple &ariables 8scalars9) LibreOffice #asic also supports arrays 8data fields9. / data field
contains se&eral &ariables) which are addressed throuh an inde,.
*efining "rrays
/rrays can be defined as follows:
i+,le Arra-s
/n array declaration is similar to that of a simple &ariable declaration. .owe&er) unlike the &ariable
declaration) the array name is followed by parentheses which contain the specifications for the number of
elements. The e,pression Dim +y/rray8!9 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 type@specific &ariables in an array. -or e,ample) the followin line declares an array
with four inteer &ariables:
"i# A.6n(eger(3) $s 6n(eger
6n the pre&ious e,amples) the inde, for the array always beins with the standard start &alue of <ero. /s an
alternati&e) a &alidity rane with start and end &alues can be specified for the data field declaration. The
followin e,ample declares a data field that has si, inteer &alues and which can be addressed usin the
inde,es ( to HG:
"i# A.6n(eger(5 To 1D) $s 6n(eger
The inde,es do not need to be positi&e &alues. The followin e,ample also shows a correct declaration) but
with neati&e data field limits:
"i# A.6n(eger(H1D To H5) $s 6n(eger
6t declares an inteer data field with L &alues that can be addressed usin the inde,es @HG to @(.
There are no practical limits on the inde,es or on the number of elements in an array) so lon as there is
enouh memory:
$+ LibreOffice 3 Basic %"i&e
"i# s(H53DDD (o 8LDDD) $s S(ring
s(H52DDD) = @@
s(7LLLL) = @bb@
prin( s(H52DDD)< s(7LLLL)
Note
Other limit &alues sometimes apply for data field inde,es in ;#/. The same also applies to
the ma,imum number of elements possible per dimension. The &alues &alid there can be
found in the rele&ant ;#/ documentation.
#pecified )alue for #tart $nde,
The start inde, of a data field usually beins with the &alue G. /lternati&ely) you can chane the start inde,
for all data field declarations to the &alue H by usin the call:
3p(ion 2se 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. .owe&er) this call does not affect the 01O se5uences that are defined throuh the LibreOffice /P6
whose inde, always beins with G. To impro&e clarity) you should a&oid usin Option #ase H.
The number of elements in an array is not affected if you use 3p(ion 2se 1) only the start inde,
chanes. The declaration
3p(ion 2se 1
% 111
"i# A.6n(eger(3)
creates ' inteer &ariables which can be described with the e,pressions A.6n(eger(1)) A.6n(eger(2))
A.6n(eger(3)) and A.6n(eger(4).
Note
6n LibreOffice #asic) the e,pression 3p(ion 2se 1 does not affect the number of
elements in an array as it does in ;#/. 6t is) rather) the start inde, which mo&es in
LibreOffice #asic. %hile the declaration A.6n(eger(3) creates three inteer &alues in
;#/ with the inde,es H to !) the same declaration in LibreOffice #asic creates four inteer
&alues with the inde,es H to '. #y usin 3p(ion 7o#p(ib+e) LibreOffice #asic beha&es
like ;#/.
Multi.*i%ensional *ata Fields
6n addition to sinle dimensional data fields) LibreOffice #asic also supports work with multi@dimensional data
fields. The correspondin dimensions are separated from one another by commas. The e,ample Dim
+y6nt/rray8() (9 /s 6nteer defines an inteer array with two dimensions) each with L inde,es 8can be
addressed throuh the inde,es G to (9. The entire array can record a total of L , L N !L inteer &alues.
You can define hundreds of dimensions in LibreOffice #asic /rraysF howe&er) the amount of a&ailable
memory limits the number of dimensions you can ha&e.
*yna%ic Changes in the *i%ensions of *ata Fields
The pre&ious e,amples are based on data fields of a specified dimension. You can also define arrays in
which the dimension of the data fields dynamically chanes. -or e,ample) you can define an array to contain
all of the words in a te,t that bein with the letter /. /s the number of these words is initially unknown) you
need to be able to subse5uently chane the field limits. To do this in LibreOffice #asic) use the followin call:
,e"i# A.$rr.(1D)
Note
0nlike ;#/) where you can only dimension dynamic arrays by usin "i# A.$rr.())
LibreOffice #asic lets you chane both static and dynamic arrays usin ,e"i#.
The followin e,ample chanes the dimension of the initial array so that it can record HH or "H &alues:
Chapter $2 4orms $,
"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'rese (o 11 e+e#en(s
% 111
,e"i# A.$rr.(2D) $s 6n(eger % 6n'rese (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 declarin multi@dimensional data fields and specifyin e,plicit start and end &alues. %hen the
dimensions of the data field are chaned) all contents are lost. 6f you want to keep the oriinal &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'rese 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
0nlike ;#/) where only the upper limit of the last dimension of a data field can be chaned
throuh Mreser*e) LibreOffice #asic lets you chane other dimensions as well.
6f you use ,e"i# with Mreser*e) you must use the same data type as specified in the oriinal data field
declaration.
*eter%ining the *i%ensions of *ata Fields
-unctions L#ound89 and 0#ound89 return respecti&ely the lowest permitted inde, &alue and the hihest
permitted inde, &alue of an array. This is useful when an array has chaned 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
-or a multi@dimensional array you need to specify the position 8H to n9 of the inde, you want to know 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
+%pty arrays
6n some cases) especially when dealin with the /P6) you need to declare an empty array. Such array is
declared without dimension) but may later be filled by an /P6 function or with a *edim statement:
"i# s() $s S(ring % -e'+re n e#p(. rr.
% HHH +(er in (&e progr# 111
,e-i# s(13) $s S(ring
You cannot assin a &alue to an empty array) since it does not contain any elements.
The MsinatureM of an empty array is that 0#ound89 returns @H and L#ound89 returns G:
"i# A.$rr.() $s 6n(eger
Asg2ox(L2oun-(A.$rr.)) % -isp+.s ! D
Asg2ox(N2oun-(A.$rr.)) % -isp+.s ! H1
Some /P6 functions return an array containin elements 8inde,ed from <ero9 or return an empty array. 0se
0#ound89 to check if the returned array is empty.
2> LibreOffice 3 Basic %"i&e
*efining values for arrays
;alues for the /rray fields can be stored like this:
A.$rr.(D) = @so#e*+ue@
"ccessing "rrays
/ccessin &alues in an array works like this:
Asg2ox(@4+ue!@ G A.$rr.(D))
"rray Creation/ value assign%ent and access e,a%ple
/nd e,ample containin all steps that show real array usae:
Sub Tes($rr.$xess "i# A.$rr.(3) A.$rr.(D)
= @++@ Asg2ox(@4+ue!@ G A.$rr.(D))En- Sub
#cope and ife #pan of )ariables
/ &ariable in LibreOffice #asic has a limited life span and a limited scope from which it can be read and used
in other proram framents. 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.
ocal )ariables
;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 lon as the function or the procedure is e,ecutin) and then are reset to
<ero. 4ach time the function is called) the &alues enerated pre&iously are not a&ailable.
To keep 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
0nlike ;#/) LibreOffice #asic ensures that the name of a local &ariable is not used
simultaneously as a lobal and a pri&ate &ariable in the module header. %hen you port a
;#/ application to LibreOffice #asic) you must chane any duplicate &ariable names.
Public *o%ain )ariables
Public domain &ariables are defined in the header section of a module by the keyword "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
Chapter $2 4orms 2$
+odule #:
Sub 8+op
$ = $ H 1
En- Sub
The &alue of &ariable $ is not chaned 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 chanes to the &ariable are lobal.
You can also use the keyword Mub+i' instead of "i# to declare a public domain &ariable:
Mub+i' $ $s 6n(eger
/ public domain &ariable is only a&ailable so lon as the associated macro is e,ecutin and then the &ariable
is reset.
&lobal )ariables
6n terms of their function) lobal &ariables are similar to public domain &ariables) e,cept that their &alues are
retained e&en after the associated macro has e,ecuted. $lobal &ariables are declared in the header section
of a module usin the keyword G+ob+:
G+ob+ $ $s 6n(eger
Private )ariables
Mri*(e &ariables are only a&ailable in the module in which they are defined. 0se the keyword Mri*(e to
define the &ariable:
Mri*(e A.6n(eger $s 6n(eger
6f se&eral modules contain a Mri*(e &ariable with the same name) LibreOffice #asic creates a different
&ariable for each occurrence of the name. 6n the followin e,ample) 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(s (&e *rib+e 7 )ro# #o-u+e $
Se(Ao-u+e2 % Se(s (&e *rib+e 7 )ro# #o-u+e 2
S&o04r$ % S&o0s (&e *rib+e 7 )ro# #o-u+e $ (=
1D)
S&o04r2 % S&o0s (&e *rib+e 7 )ro# #o-u+e 2 (=
2D)
En- Sub
Sub Se(Ao-u+e$
7 = 1D
En- Sub
Sub S&o04r$
Asg2ox 7 % S&o0s (&e *rib+e 7 )ro# #o-u+e $1
En- Sub
+odule #:
Mri*(e 7 $s 6n(eger

Sub Se(Ao-u+e2
7 = 2D
En- Sub
Sub S&o04r2
Asg2ox 7 % S&o0s (&e *rib+e 7 )ro# #o-u+e 21
En- Sub
Oeep in mind that Show;ar# only shows the e,pected &alue of 7 8"G9 because Sub Test is keepin it in
scope. 6f the calls to Set+odule# and Show;ar# are independent) e.. Set+odule# is triered from one
toolbar button and Show;ar# is triered from another toolbar button) then Show;ar# will display a 7 &alue
of G since module &ariables are reset after each macro completion.
Constants
7onstants are &alues which may be used but not chaned by the proram.
*efining Constants
6n LibreOffice #asic) use the keyword 7ons( to declare a constant.
7ons( $ = 1D
You can also specify the constant type in the declaration:
7ons( 2 $s "oub+e = 1D
#cope of Constants
7onstants ha&e the same scope as &ariables 8see )cope an& Life )pan of 1ariables9) but the synta, is
slihtly different. / 7ons( definition in the module header is a&ailable to the code in that module. To make
the definition a&ailable to other modules) add the Mub+i' keyword.
Mub+i' 7ons( one $s 6n(eger = 1
Predefined Constants
LibreOffice #asic predefines se&eral constants. /mon the most useful are:
True and 8+se) for #oolean assinment statements
M6 as a type "oub+e numeric &alue
"i# bBi( s 2oo+en
bBi( = True
"i# -$re s "oub+e< -,-ius s "oub+e
% 111 (ssign *+ue (o -,-ius)
-$re = M6 * -,-ius * -,-ius
Operators
LibreOffice #asic understands common mathematical) loical) and comparison operators.
Mathe%atical Operators
+athematical operators can be applied to all numbers types) whereas the 2 operator can also be used to
concatenate strins.
+
/ddition of numbers and date &alues) concatenation of strins
G
7oncatenation of strins
H
Subtraction of numbers and date &alues
*
+ultiplication of numbers
Chapter $2 4orms 23
O
Di&ision of numbers
P
Di&ision of numbers with a whole number result 8rounded9
Q
*aisin the power of numbers
A3"
modulo operation 8calculation of the remainder of a di&ision9
Note
/lthouh you can use the 2 operator to concatenate strins) the #asic interpreter can
become confused when concatenatin a number to a strin. The 3 operator is safer when
dealin with strins because it assumes that all aruments should be strins) and con&erts
the aruments to strins if they are not strins.
ogical Operators
Loical operators allow you to do operations on elements accordin to the rules of #oolean alebra. 6f the
operators are applied to #oolean &alues) the operation pro&ides the result re5uired directly. 6f used in
conjunction with inteer and lon inteer &alues) the operation is done at the bit le&el.
$5"
/nd operator
3,
Or operator
R3,
4,clusi&e Or operator
53T
1eation
ES4
45ui&alent test 8both parts True or 8+se9
6AM
6mplication 8if the first e,pression is true) then the second must also be
true9
Co%parison Operators
7omparison operators can be applied to all elementary &ariable types 8numbers) date details) strins) and
#oolean &alues9.
=
45uality of numbers) date &alues and strins
TU
6ne5uality of numbers) date &alues and strins
U
$reater than check for numbers) date &alues and strins
U=
$reater than or e5ual to check for numbers) date &alues and strins
T
Less than check for numbers) date &alues and strins
T=
Less than or e5ual to check for numbers) date &alues and strins
Note LibreOffice #asic does not support the ;#/ Li/e comparison operator.
!ranching
0se branchin statements to restrict the e,ecution of a code block until a particular condition is satisfied.
$f...Then...+lse
The most common branchin statement is the 6) statement as shown in the followin e,ample:
6) $ U 3 T&en
2 = 2
En- 6)
The 2 = 2 assinment only occurs when &alue of &ariable $ is reater 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)
6n this e,ample) the &ariable 2 is assined the &alue of " when $ is reater than !) otherwise 2 is assined
the &alue of G.
-or more comple, statements) you can cascade the 6) statement) for e,ample:
6) $ = D T&en
2 = D
E+se6) $ T 3 T&en
2 = 1
E+se
2 = 2
En- 6)
6f the &alue of &ariable $ e5uals <ero) 2 is assined the &alue G. 6f $ is less than ! 8but not e5ual to <ero9)
then 2 is assined the &alue H. 6n all other instances 8that is) if $ is reater than or e5ual to !9) 2 is assined
the &alue ".
/ complete 6f statement may be written on a sinle line) with a simpler synta,. The first e,ample of this pae
may be written as:
6) $ U 3 T&en 2 = 2
The second e,ample of this pae may be written as:
6) $ U 3 T&en 2 = 2 E+se 2 = D
#elect...Case
The Se+e'(1117se instruction is an alternati&e to the cascaded 6) statement and is used when you need
to check a &alue aainst &arious conditions:
Se+e'( 7se ".3)Cee/
7se 1!
5#e3)Cee/-. = @Sun-.@
7se 2!
5#e3)Cee/-. = @Aon-.@
7se 3!
5#e3)Cee/-. = @Tues-.@
7se 4!
5#e3)Cee/-. = @Ce-nes-.@
7se 5!
5#e3)Cee/-. = @T&urs-.@
7se 6!
5#e3)Cee/-. = @8ri-.@
7se 7!
5#e3)Cee/-. = @S(ur-.@
En- Se+e'(
6n this e,ample) the name of a weekday corresponds to a number) so that the ".3)Cee/ &ariable is
assined the &alue of H for Sun-.) " for Aon-. &alue) and so on.
Chapter $2 4orms 23
The Se+e'( command is not restricted to simple H:H assinments : you can also specify comparison
operators or lists of e,pressions in a 7se branch. The followin e,ample lists the most important synta,
&ariants:
Se+e'( 7se 4r
7se 1 To 5
% 111 4r is be(0een (&e nu#bers 1 n- 5 (in'+u-ing
(&e *+ues 1 n- 5)1
7se U 1DD
% 111 4r is gre(er (&n 1DD
7se 6< 7< 8
% 111 4r is 6< 7 or 8
7se 6< 7< 8< U 15< T D
% 111 4r is 6< 7< 8< gre(er (&n 15< or +ess (&n D
7se E+se
% 111 ++ o(&er ins(n'es
En- Se+e'(
1ow consider a misleadin 8ad&anced9 e,ample) and a common error:
Se+e'( 7se 4r
7se 4r = 8
% 111 4r is D
7se E+se
% 111 ++ o(&er ins(n'es
En- Se+e'(
The statement 8;ar N J9 e&aluates to T*04 if ;ar is J) and -/LS4 otherwise. T*04 is @H and -/LS4 is G.
The Select 7ase statement e&aluates the e,pression) which is T*04 or -/LS4) and then compares that
&alue to ;ar. %hen ;ar is G) there is a match. 6f you understand the last e,ample) then you also know why
this e,ample does not do what it appears
Se+e'( 7se 4r
7se 4r U 8 $n- 4r T 11
% 111 4r is D
7se E+se
% 111 ++ o(&er ins(n'es
En- Se+e'(
oops
/ loop e,ecutes a code block for the number of passes that are specified. You can also ha&e loops with an
undefined number of passes.
For...Ne,t
The 8or1115ex( loop has a fi,ed number of passes. The loop counter defines the number of times that the
loop is to be e,ecuted. 6n the followin e,ample) &ariable 6 is the loop counter) with an initial &alue of H. The
counter is incremented by H at the end of each pass. %hen &ariable 6 e5uals HG) the loop stops.
"i# 6
8or 6 = 1 To 1D
% 111 6nner pr( o) +oop
5ex( 6
6f you want to increment the loop counter by a &alue other than H at the end of each pass) use the S(ep
function:
"i# 6
8or 6 = 1 To 1D S(ep D15
5ex( 6
6n the precedin e,ample) the counter is increased by G.( at the end of each pass and the loop is e,ecuted
HK times.
2# LibreOffice 3 Basic %"i&e
You can also use neati&e step &alues:
"i# 6
8or 6 = 1D To 1 S(ep H1
5ex( 6
6n this e,ample) the counter beins at HG and is reduced by H at the end of each pass until the counter is H.
The Exi( 8or instruction allows you to e,it a 8or loop prematurely. 6n the followin e,ample) the loop is
terminated durin the fifth pass:
"i# 6
8or 6 = 1 To 1D
6) 6 = 5 T&en
Exi( 8or
En- 6)
5ex( 6
For +ach
The 8or E'&1115ex( loop &ariation in ;#/ is supported in LibreOffice #asic. 8or E'& loops do not use
an e,plicit counter like a 8or1115ex( loop does. / 8or E'& loop says Mdo this to e&erythin in this setM)
rather than Mdo this n timesM. -or e,ample:
7ons( -1 = 2
7ons( -2 = 3
7ons( -3 = 2
"i# i
"i# (-1< -2< -3)
8or E'& i 6n ()
5ex( i
The loop will e,ecute !L times.
*o...oop
The "o111Loop is not linked to a fi,ed number of passes. 6nstead) the "o111Loop is e,ecuted until a
certain condition is met. There are four &ersions of the "o111Loop. 6n the first two e,amples) the code within
the loop may not be e,ecuted at all 8Mdo G timesM loic9. 6n the latter e,amples) the code will be e,ecuted at
least once. 86n the followin e,amples) $ U 1D represents any condition9:
1The Do While...Loop version
"o C&i+e $ U 1D
% 111 +oop bo-.
Loop
checks whether the condition after the C&i+e is truebefore e&ery pass and only then e,ecutes the loop.
2The Do Until...Loop version
"o Nn(i+ $ U 1D
% 111 +oop bo-.
Loop
e,ecutes the loop as lon as the condition after the Nn(i+ e&aluates to false.
3The Do...Loop While version
"o
% 111 +oop bo-.
Loop C&i+e $ U 1D
Chapter $2 4orms 2'
only checks the condition after the first loop pass and terminates if the condition after the C&i+e e&aluates to
false.
4The Do...Loop Until version
"o
% 111 +oop bo-.
Loop Nn(i+ $ U 1D
also checks its condition after the first pass) but terminates if the condition after the Nn(i+ e&aluates to true.
/s in the 8or1115ex( loop) the "o111Loop also pro&ides a terminate command. The Exi( "o command
can e,it 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
6n some cases the loop may only terminate when a condition is met within the loop. Then you can use the
MperpetualM Do Loop:
"o
% 111 so#e in(ern+ '+'u+(ions
6) $ = 4 T&en Exi( "o
% 111 o(&er ins(ru'(ions
Loop
(hile...(end
The C&i+e111Cen- loop construct works e,actly the same as the "o C&i+e111Loop) but with the
disad&antae that there is no Exi( command a&ailable. The followin two loops produce identical results:
"o C&i+e $ U 1D
% 111 +oop bo-.
Loop
C&i+e $ U 1D
% 111 +oop bo-.
Cen-
Progra%%ing +,a%ple0 #orting (ith +%bedded oops
There are many ways to use loops) for e,ample) to search lists) return &alues) or e,ecute comple,
mathematical tasks. The followin e,ample is an alorithm 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
"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-0r-@
En(r.(L) = @7&ris(ine@
En(r.(1D) = @Werr.@
2+ LibreOffice 3 Basic %"i&e
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 interchaned as pairs se&eral times until they are finally sorted in ascendin order. Like
bubbles) the &ariables radually mirate to the riht position. -or this reason) this alorithm is also known as
a B"bble )ort.
Procedures and Functions
Procedures and functions form pi&otal points in the structure of a proram. They pro&ide the framework for
di&idin a comple, problem into &arious sub@tasks.
Procedures
/ proceduree,ecutes an action without pro&idin an e,plicit &alue. 6ts synta, is
Sub Tes(
% 111 &ere is (&e '(u+ 'o-e o) (&e pro'e-ure
En- Sub
The e,ample defines a procedure called Tes( that contains code that can be accessed from any point in the
proram. The call is made by enterin the procedure name at the rele&ant point of the proram.
Functions
/ function) just like a procedure) combines a block of prorams to be e,ecuted into one loical unit.
.owe&er) unlike a procedure) a function pro&ides a return &alue.
8un'(ion Tes(
% 111 &ere is (&e '(u+ 'o-e o) (&e )un'(ion
Tes( = 123
En- 8un'(ion
The return &alue is assined usin simple assinment. The assinment does not need to be placed at the
end of the function) but can be made anywhere in the function.
The precedin function can be called within a proram as follows:
"i# $
$ = Tes(
The code defines a &ariable $ and assins 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 assinment)
the function in this e,ample returns the &alue that was last assined to it.
8un'(ion Tes(
Tes( = 12
% 111
Tes( = 123
Chapter $2 4orms 2,
En- 8un'(ion
6n this e,ample) the return &alue of the function is H"!.
6f nothin is assined) the function returns a Xero &alue 8number G for numerical &alues and a blank for
strins9.
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
6f the return type is not specified 8see first e,ample of this pae9) the function returns a &ariant.
Ter%inating Procedures and Functions Pre%aturely
6n LibreOffice #asic) you can use the Exi( Sub and Exi( 8un'(ion commands to terminate a procedure
or function prematurely) for e,ample) for error handlin. These commands stop the procedure or function and
return the proram to the point at which the procedure or function was called up.
The followin e,ample shows a procedure which terminates implementation when the Error3''ure-
&ariable has the &alue True.
Sub Tes(
"i# Error3''ure- $s 2oo+en
% 111
6) Error3''ure- T&en
Exi( Sub
En- 6)
% 111
En- Sub
Passing Para%eters
-unctions and procedures can recei&e one or more parameters. 4ssential parameters must be enclosed in
parentheses after the function or procedure names. The followin e,ample defines a procedure that e,pects
an inteer &alue $ and a strin 2 as parameters.
Sub Tes( ($ $s 6n(eger< 2 $s S(ring)
% 111
En- Sub
Parameters are normally passe& by .eference in LibreOffice #asic. 7hanes made to the &ariables are
retained when the procedure or function is e,ited:
Sub Tes(
"i# $ $s 6n(eger
$ = 1D
7&nge4+ue($)
% T&e pr#e(er $ no0 &s (&e *+ue 2D
En- Sub
Sub 7&nge4+ue(T&e4+ue $s 6n(eger)
T&e4+ue = 2D
En- Sub
6n this e,ample) the &alue $ that is defined in the Tes( function is passed as a parameter to the
7&nge4+ue function. The &alue is then chaned to "G and passed to T&e4+ue) which is retained when
the function is e,ited.
You can also pass a parameter as a valueif you do not want subse5uent chanes to the parameter to affect
the &alue that is oriinally passed. To specify that a parameter is to be passed as a &alue) ensure that the
2.4+ keyword precedes the &ariable declaration in the function header.
6n the precedin e,ample) if we replace the 7&nge4+ue function then the superordinate &ariable /
remains unaffected by this chane. /fter the call for the 7&nge4+ue function) &ariable $ retains the &alue
HG.
Sub 7&nge4+ue(2.4+ T&e4+ue $s 6n(eger)
T&e4+ue = 2D
En- Sub
Note
The method for passin parameters to procedures and functions in LibreOffice #asic is
&irtually identical to that in ;#/. #y default) the parameters are passed by reference. To
pass parameters as &alues) use the 2.4+ keyword. 6n ;#/) you can also use the keyword
2.,e) to force a parameter to be passed by reference. LibreOffice #asic reconi<es but
inores this keyword) because this is already the default procedure in LibreOffice #asic.
Optional Para%eters
-unctions and procedures can only be called up if all the necessary parameters are passed durin the call.
LibreOffice #asic lets you define parameters as optional) that is) if the correspondin &alues are not included
in a call) LibreOffice #asic passes an empty parameter. 6n the followin e,ample the $ parameter is
obliatory) whereas the 2 parameter is optional.
Sub Tes(($ $s 6n(eger< 3p(ion+ 2 $s 6n(eger)
% 111
En- Sub
The 6sAissing function checks 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 pr#e(er is '(u++. presen(
6) 5o( 6sAissing (2) T&en
2_Lo'+ = 2 % 2 pr#e(er presen(
E+se
2_Lo'+ = D % 2 pr#e(er #issing HU -e)u+(
*+ue D
En- 6)
% 111 S(r( (&e '(u+ )un'(ion
En- Sub
The e,ample first tests whether the 2 parameter has been passed and) if necessary) passes the same
parameter to the internal 2_Lo'+ &ariable. 6f the correspondin parameter is not present) then a default
&alue 8in this instance) the &alue G9 is passed to 2_Lo'+ rather than the passed parameter.
Note
The Mr#$rr. keyword present in ;#/ is not supported in LibreOffice #asic.
1ecursion
/ 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 followin e,ample uses a recursi&e function to calculate the factorial of the numbers 42) H42) and 3114:
Sub Ain
Asgbox 7+'u+(e8'(ori+( 42 ) % "isp+.s
1<4D5DD611775288E+51
Asgbox 7+'u+(e8'(ori+( H42 ) % "isp+.s @6n*+i-
nu#ber )or )'(ori+I@
Asgbox 7+'u+(e8'(ori+( 3114 ) % "isp+.s @6n*+i-
nu#ber )or )'(ori+I@
En- Sub
Chapter $2 4orms 3$
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 e,ample returns the factorial of the number 42 by recursi&ely callin 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. -or %indows
the recursion le&el is (JGG. -or Solaris and Linu,) an e&aluation of the stacksi<e is
performed and the recursion le&el is calculated.
+rror -andling
7orrect handlin of error situations is one of the most time@consumin tasks of prorammin. LibreOffice
#asic pro&ides a rane of tools for simplifyin error handlin.
The On +rror $nstruction
The 3n Error instruction is the key to any error handlin:
Sub Tes(
3n Error Go(o ErrorBn-+er
% 111 un-er(/e (s/ -uring 0&i'& n error #. o''ur
Exi( Sub
ErrorBn-+er!
% 111 in-i*i-u+ 'o-e )or error &n-+ing
En- Sub
The 3n Error Go(o ErrorBn-+er line defines how LibreOffice #asic proceeds in the e&ent of an error.
The Go(o ErrorBn-+er ensures that LibreOffice #asic e,its the current proram line and then e,ecutes
the ErrorBn-+er! code.
The 1esu%e Co%%and
The ,esu#e 5ex( command continues the proram from the line that follows where the error occurred in
the proram after the code in the error handler has been e,ecuted:
ErrorBn-+er!
,esu#e 5ex(
0se the ,esu#e Mro'ee- command to specify a jump point for continuin the proram after error handlin:
ErrorBn-+er!
,esu#e Mro'ee-

Mro'ee-!
% 111 (&e progr# 'on(inues &ere )(er (&e error
The term Proceed is a label. 6t could be for e,ample) /"'I. The synta, for label names is the same as for
&ariable names.
To continue a proram without an error messae when an error occurs) use the followin format:
Sub Tes(
3n Error ,esu#e 5ex(
% 111 per)or# (s/ -uring 0&i'& n error #. o''ur
En- Sub
0se the 3n Error ,esu#e 5ex( command with caution as its effect is lobal.
2ueries 1egarding +rror $nfor%ation
6n error handlin) it is useful to ha&e a description of the error and to know 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 +s#o, M4rror M 3 4rr 3 M: M 3 4rrorP 3 M 8line : M 3 4rl 3 M9M shows how the error information can be
displayed in a messae window.
Note
%hereas ;#/ summari<es the error messaes in a statistical object called Err)
OpenOffice.or #asic pro&ides the Err< ErrorF) and Er+ &ariables.
The status information remains &alid until the proram encounters a ,esu#e or 3n Error command)
whereupon the information is reset.
Note
6n ;#/) the Err17+er method of the Err object resets the error status after an error
occurs. 6n OpenOffice.or #asic) this is accomplished with the 3n Error or ,esu#e
commands.
Tips for #tructured +rror -andling
#oth the definition command) 3n Error) and the return command) ,esu#e) are &ariants of the Go(o
construct.
6f you want to cleanly structure your code to pre&ent eneratin errors when you use this construct) you
should not use jump commands without monitorin them.
7are should be taken when you use the 3n Error ,esu#e 5ex( command as this dismisses all open
error messaes.
The best solution is to use only one approach for error handlin within a proram @ keep error handlin
separate from the actual proram code and do not jump back to the oriinal code after the error occurs.
The followin code is an e,ample of an error handlin procedure:
Sub Ex#p+e
% "e)ine error &n-+er ( (&e s(r( o) (&e )un'(ion
3n Error Go(o ErrorBn-+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
ErrorBn-+er!
% 7&e'/ 0&e(&er error 0s expe'(e-
6) Err = Expe'(e-Error5o T&en
% 111 Mro'ess error
E+se
% 111 Crning o) unexpe'(e- error
En- 6)
3n Error Go(o D % "e'(i*(e error &n-+ing
En- Sub
Chapter $2 4orms 33
This procedure beins with the definition of an error handler) followed by the actual proram code. /t the end
of the proram code) the error handlin is deacti&ated by the 3n Error Go(o D call and the procedure
implementation is ended by the Exi( Sub command 8not to be confused with En- Sub9.
The e,ample first checks if the error number corresponds to the e,pected number 8as stored in the imainary
Expe'(e-Error5o constant9 and then handles the error accordinly. 6f another error occurs) the system
outputs a warnin. 6t is important to check 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 8the error code
in the Err system &ariables9 so that an error occurrin at a later date can be clearly reconi<ed.
Other $nstructions
Type...+nd Type
/ str"ct is a collection of data fields) that can be manipulated as a sinle item. 6n older terms) you may think
of a struct as a record) or part of a record.
The (P* often uses pre@defined structs) but these are UO str"cts) a hihly@speciali<ed kind of struct.
/efinition
%ith the T.pe111En- T.pe statements) you can define your own 8non@01O9 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
$nstance
The T.pe definition is only a pattern or template) not a set of actual &ariables. To make 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#
#cope
/s shown in the e,ample below) the T.pe definition may be written at the start of a module 8before the first
Sub or 8un'(ion9. The definition will then be a&ailable to all routines in the module.
/s of LibreOffice ;ersion !.G) unlike &ariables) there is no way to make the definition accessible outside of
the module.
/n instance of the new type is a &ariable) and follows the usual rules for &ariable scope 8see )cope an& Life
)pan of 1ariables9.
/n e,ample of how to use the definition) and how to reference the fields within an instance) appears in the
section on Ci(&111En- Ci(&.
(ith...+nd (ith
0ualifiers
6n eneral) #asic does not look inside a container) such as an 3b:e'() to see what names miht be defined
there. 6f you want to use such a name) you must tell #asic where to look. You do that by usin the name of
the object as a F"alifier. %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 5ualifier. %rite the 5ualifiers in
order) from outer to inner:
3u(er3b:e'(16nner3b:e'(18r6nsi-e3b:e'(1So#e5#e
These names may also be described as) Mconcatenated with the dot@operator 8>.>9M.
The (ith "lternative
The Ci(&111En- Ci(& bracketin statements pro&ide an alternati&e to writin out all the 5ualifiers) e&ery
time @ and some of the 5ualifiers in the /P6 can be 5uite lon. You specify the 5ualifiers in the Ci(&
statement. 0ntil #asic encounters the En- Ci(& statement) it looks for partly@F"alifie& names: names that
bein with a period 8unary dot@operator9. The compiler uses the 5ualifiers from the Ci(& as thouh they were
written in front of the partly@5ualified name.
+,a%ple 30 " 'ser.defined #truct
This e,ample shows how you may define and use a struct) and how to reference the items within it) both with
and without Ci(&. 4ither way) the names of the data fields 8from the T.pe definition9 must be 5ualified by the
name of the instance 8from the "i# statement9.
T.pe Aenu6(e#
7o##n- s S(ring
Tex( s S(ring
En- T.pe

Sub Ain
%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#
17o##n- = @1uno!7op.@
1Tex( = @Y7op.@
En- Ci(&

Asg2ox @7o##n-! @ G #6(e#17o##n- G 7&r(13) _
G @Tex(! @ G #6(e#1Tex(
En- Sub
+,a%ple 40 Case state%ent
6n Cells an& 7anges) the followin e,ample has the 5ualifiers in the 7se 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'(
"o' = T&is7o#ponen(
S&ee( = "o'1S&ee(s(D)
7e++ = S&ee(1ge(7e++2.Mosi(ion(1<1) %7e++ @22@ (DH
bse-I)
7e++14+ue = 1DDD
Ci(& 'o#1sun1s(r1(b+e17e++7on(en(T.pe
Se+e'( 7se 7e++1T.pe
7se 1EAMTZ
Asg2ox @7on(en(! E#p(.@
7se 14$LNE
Chapter $2 4orms 33
Asg2ox @7on(en(! 4+ue@
7se 1TERT
Asg2ox @7on(en(! Tex(@
7se 183,ANL$
Asg2ox @7on(en(! 8or#u+@
En- Se+e'(
En- Ci(&
1otice that the Ci(& construct must be entirely outside of the Se+e'( construct.
#asic $uide
Chapter 3
7"ntime Library
1unti%e ibrary
The followin sections present the central functions of the runtime library:
H.7on&ersion -unctions
".Strins
!.Date and Time
'.-iles and Directories
(.+essae and 6nput #o,es
L.Other -unctions
Conversion Functions
6n many situations) circumstances arise in which a &ariable of one type has to be chaned into a &ariable of
another type.
$%plicit and +,plicit Type Conversions
The easiest way to chane a &ariable from one type to another is to use an assinment.
"i# $ $s S(ring
"i# 2 $s 6n(eger
2 = 1D1
$ = 2
6n this e,ample) &ariable $ is a strin) and &ariable 2 is an inteer. LibreOffice #asic ensures that &ariable 2
is con&erted to a strin durin assinment to &ariable $. This con&ersion is much more elaborate than it
appears: the inteer 2 remains in the workin memory in the form of a two@byte lon number. $) on the other
hand) is a strin) and the computer sa&es a one@ or two@byte lon &alue for each character 8each number9.
Therefore) before copyin the content from 2 to $) 2 has to be con&erted into $>s internal format.
0nlike most other prorammin lanuaes) #asic performs type con&ersion automatically. .owe&er) this may
ha&e fatal conse5uences. 0pon closer inspection) the followin code se5uence
"i# $ $s S(ring
"i# 2 $s 6n(eger
"i# 7 $s 6n(eger
2 = 1
7 = 1
$ = 2 + 7
which at first lance seems straihtforward) ultimately pro&es to be somethin of a trap. The #asic interpreter
first calculates the result of the addition process and then con&erts this into a strin) which) as its result)
produces the strin ".
6f) on the other hand) the #asic interpreter first con&erts the start &alues 2 and 7 into a strin and applies the
plus operator to the result) it produces the strin 11.
The same applies when usin &ariant &ariables:
"i# $
"i# 2
"i# 7
2 = 1
7 = @1@
$ = 2 + 7
Since &ariant &ariables may contain both numbers and strins) it is unclear whether &ariable $ is assined
the number " or the strin HH.
The error sources noted for implicit type con&ersions can only be a&oided by careful proramminF for
e,ample) by not usin the &ariant data type.
To a&oid other errors resultin from implicit type con&ersions) LibreOffice #asic offers a rane 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 strin.
CInt(Var)
con&erts any data types into an inteer &alue.
CLng(Var)
con&erts any data types into a lon &alue.
CSng(Var)
con&erts any data types into a sinle &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 LibreOffice #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) % 2 n- 7 re --e- (oge(&er
)irs(< (&en
% 'on*er(e- (o (&e s(ring @2@
$ = 7S(r(2) + 7S(r(7) % 2 n- 7 re 'on*er(e- in(o
s(ring<(&en
% 'o#bine- (o pro-u'e (&e s(ring
@11@
Durin the first addition in the e,ample) LibreOffice #asic first adds the inteer &ariables and then con&erts
the result into a chain of characters. $ is assined the strin 2. 6n the second instance) the inteer &ariables
are first con&erted into two strins and then linked with one another by means of the assinment. $ is
therefore assined the strin 11.
The numerical 7Sng and 7"b+ con&ersion functions also accept decimal numbers. The symbol defined in
the correspondin country@specific settins must be used as the decimal point symbol. 7on&ersely) the 7S(r
methods use the currently selected country@specific settins when formattin numbers) dates and time
details.
The 4+ function is different from the 7sng< 7-b+ and 7s(r methods. 6t con&erts a strin into a numberF
howe&er it always e,pects a period to be used as the decimal point symbol.
"i# $ $s S(ring
"i# 2 $s "oub+e
$ = @2122@
Chapter $2 4orms 3,
2 = 4+($) % 6s 'on*er(e- 'orre'(+. regr-+ess o) (&e
% 'oun(r.Hspe'i)i' se((ings
Checking the Content of )ariables
6n some instances) the date cannot be con&erted:
"i# $ $s S(ring
"i# 2 $s "(e
$ = @(es(@
2 = $ % 7re(es error #essge
6n the e,ample shown) the assinment of the (es( strin to a date &ariable makes no sense) so the #asic
interpreter reports an error. The same applies when attemptin to assin a strin to a #oolean &ariable:
"i# $ $s S(ring
"i# 2 $s 2oo+en
$ = @(es(@
2 = $ % 7re(es error #essge
/ain) the basic interpreter reports an error.
These error messaes can be a&oided by checkin the proram before an assinment) in order to establish
whether the content of the &ariable to be assined matches the type of the taret &ariable. LibreOffice #asic
pro&ides the followin test functions for this purpose:
IsNumeric(Value)
checks whether a &alue is a number.
IsDate(Value)
checks whether a &alue is a date.
IsArra(Value)
checks whether a &alue is an array.
These functions are especially useful when 5ueryin user input. -or e,ample) you can check 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 #essge1@
En- 6)
6n the pre&ious e,ample) if the Nser6npu( &ariable contains a &alid numerical &alue) then this is assined to
the 4+i-6npu( &ariable. 6f Nser6npu( does not contain a &alid number) 4+i-6npu( is assined the
&alue D and an error messae is returned.
%hile test functions e,ist for checkin numbers) date details and arrays in LibreOffice #asic) a correspondin
function for checkin #oolean &alues does not e,ist. The functionality can) howe&er) be imitated by usin the
6s2oo+en function:
8un'(ion 6s2oo+en(4+ue $s 4rin() $s 2oo+en
3n Error Go(o Error6s2oo+en!
"i# "u##. $s 2oo+en
"u##. = 4+ue
6s2oo+en = True
3n Error Go(o D
Exi( Sub
Error6s2oo+en!
6s2oo+en = 8+se
3n Error Go(o D
En- 8un'(ion
The 6s2oo+en function defines an internal "u##. help &ariable of the #oolean type and tries to assin this
to the transferred &alue. 6f assinment is successful) the function returns True. 6f it fails) a runtime error is
produced) the error handler intercepts the error) and the function returns 8+se.
Note
6f a strin in LibreOffice #asic contains a non@numerical &alue and if this is assined to a
number) LibreOffice #asic does not produce an error messae) but stops con&ertin the
strin at the first in&alid character. This procedure differs from ;#/. There) an error is
triered and proram implementation terminated if a correspondin assinment is
e,ecuted.
#trings
(orking with #ets of Characters
%hen administerin strins) LibreOffice #asic uses the set of 0nicode characters. The $s' and 7&r
functions allow the 0nicode &alue belonin to a character to be established andQor the correspondin
character to be found for a 0nicode &alue. The followin e,pressions assin the &arious 0nicode &alues to
the code &ariable:
7o-e = $s'(@$@) % L(in +e((er $ (Nni'o-eH*+ue
65)
7o-e = $s'(@[@) % Euro '&r'(er (Nni'o-eH*+ue
8364)
7o-e = $s'(@\@) % 7.ri++i' +e((er \ (Nni'o-eH*+ue
1D83)
7on&ersely) the e,pression +yStrin N 7hr8H!9 ensures that the A.S(ring strin is initiali<ed with the &alue
of the number 13) which stands for a hard line break.
The 7&r command is often used in #asic lanuaes to insert control characters in a strin. The assinment
+yStrin N 7hr8K9 2 MThis is a testM 2 7hr8H!9 therefore ensures that the te,t is preceded by a tab character
80nicode@&alue K9 and that a hard line break 80nicode@&alue H!9 is added after the te,t.
"ccessing Parts of a #tring
LibreOffice #asic pro&ides three functions that return partial strins) plus a lenth 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.
.ere are a few e,ample calls for the named functions:
"i# A.,esu+( $s S(ring
"i# A.Len $s 6n(eger
A.S(ring = @T&is is s#++ (es(@
Chapter $2 4orms 2$
A.,esu+( = Le)((A.S(ring<5) % Mro*i-es (&e s(ring
@T&is @
A.,esu+( = ,ig&((A.S(ring< 5) % Mro*i-es (&e s(ring @
(es(@
A.,esu+( = Ai-(A.S(ring< 8< 5) % Mro*i-es (&e s(ring @
s#@
A.Len = Len(A.S(ring) % Mro*i-es (&e *+ue 2D
#earch and 1eplace
LibreOffice #asic pro&ides the 6nS(r function for searchin for a partial strin within another strin:
,esu+(S(ring = 6nS(r (A.S(ring< Ser'&S(ring)
The Ser'&S(ring parameter specifies the strin to be searched for within A.S(ring. The function
returns a number that contains the position at which the Ser'&S(ring first appears within A.S(ringF a
return &alue of <ero indicates no match. 6f you want to find other matches for the strin) the function also
pro&ides the opportunity to specify an optional start position from which LibreOffice #asic beins the search.
6n this case) the synta, of the function is:
,esu+(S(ring = 6nS(r(S(r(Mosi(ion< A.S(ring<
Ser'&S(ring)
6n the pre&ious e,amples) 6nS(r inores uppercase and lowercase characters. To chane the search so
that 6nS(r is case sensiti&e) add the parameter D) as shown in the followin e,ample:
,esu+(S(ring = 6nS(r(A.S(ring< Ser'&S(ring< D)
0sin the pre&ious functions for editin strins) prorammers can search for and replace one strin in
another strin:
8un'(ion ,ep+'e(Sour'e $s S(ring< Ser'& $s S(ring<
5e0Mr( $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) Ser'& = @@ T&en
,esu+( = Sour'e
E+se
"o C&i+e 7urren(Mos TU D
7urren(Mos = 6nS(r(S(r(Mos< Sour'e< Ser'&)
6) 7urren(Mos TU D T&en
,esu+( = ,esu+( + Ai-(Sour'e< S(r(Mos< _
7urren(Mos H S(r(Mos)
,esu+( = ,esu+( + 5e0Mr(
S(r(Mos = 7urren(Mos + Len(Ser'&)
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 throuh the transferred Ser'& strin in a loop by means of 6nS(r in the oriinal
term Sour'e. 6f it finds the search term) it takes the part before the e,pression and writes it to the ,esu+(
return buffer. 6t adds the 5e0Mr( section at the point of the search term Ser'&. 6f no more matches are
found for the search term) the function establishes the part of the strin still remainin and adds this to the
return buffer. 6t returns the strin produced in this way as the result of the replacement process.
Since replacin parts of character se5uences is one of the most fre5uently used functions) the Ai- function
in LibreOffice #asic has been e,tended so that this task is performed automatically. The followin e,ample
replaces three characters with the strin is from the si,th position of the A.S(ring strin.

A.S(ring = @T&is 0s #. (ex(@
Ai-(A.S(ring< 6< 3< @is@)
(arning
%hen it is used with ' aruments) to replace a sub@strin in a strin) Ai- is an instruction)
not a function : it does not return any &alue R
For%atting #trings
The 8or#( function formats numbers as a strin. To do this) the function e,pects a 8or#( e,pression to
be specified) which is then used as the template for formattin the numbers. 4ach place holder within the
template ensures that this item is formatted correspondinly in the output &alue. The fi&e most important
place holders within a template are the <ero 8D9) pound sin 8J9) period 819) comma 8<9 and dollar sin 8F9
characters.
The D character within the template ensures that a number is always placed at the correspondin point. 6f a
number is not pro&ided) G is displayed in its place.
/ 1 stands for the decimal point symbol defined by the operatin system in the country@specific settins.
The e,ample below shows how the D and 1 characters can define the diits after the decimal point in an
e,pression:
A.8or#( = @D1DD@
A.S(ring = 8or#((H157L18< A.8or#() % Mro*i-es @H
157L<8D@
A.S(ring = 8or#((157L18< A.8or#() % Mro*i-es
@157L<8D@
A.S(ring = 8or#((D14< A.8or#() % Mro*i-es @D<4D@
A.S(ring = 8or#((D1434< A.8or#() % Mro*i-es @D<43@
6n the same way) <eros can be added in front of a number to achie&e the desired lenth:
A.8or#( = @DDDD1DD@
157L<8D@
@157L<8D@
A.S(ring = 8or#((D14< A.8or#() % Mro*i-es
@DDDD<4D@
A.S(ring = 8or#((D1434< A.8or#() % Mro*i-es
@DDDD<43@
/ < represents the character that the operatin system uses for a thousands separator) and the J stands for
a diit or place that is only displayed if it is re5uired by the input strin.
A.8or#( = @J<JJD1DD@
1157L<8D@
@1157L<8D@
A.S(ring = 8or#((D14< A.8or#() % Mro*i-es @D<4D@
A.S(ring = 8or#((D1434< A.8or#() % Mro*i-es @D<43@
Chapter $2 4orms 23
6n place of the F place holder) the 8or#( function displays the rele&ant currency symbol defined by the
system 8this e,ample assumes a 4uropean locale has been defined9:
A.8or#( = @J<JJD1DD F@
1157L<8D [@
@1157L<8D [@
A.S(ring = 8or#((D14< A.8or#() % Mro*i-es @D<4D
[@
A.S(ring = 8or#((D1434< A.8or#() % Mro*i-es @D<43
[@
The format instructions used in ;#/ for formattin 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
*ate and Ti%e
LibreOffice #asic pro&ides the "(e data type) which sa&es the date and time details in binary format.
#pecification of *ate and Ti%e *etails within the Progra% Code
You can assin a date to a date &ariable throuh the assinment of a simple strin:
"i# A."(e $s "(e
A."(e = @241112DD2@
This assinment can function properly because LibreOffice #asic automatically con&erts the date &alue
defined as a strin into a date &ariable. This type of assinment) howe&er) can cause errors) date and time
&alues are defined and displayed differently in different countries.
Since LibreOffice #asic uses the country@specific settins of the operatin system when con&ertin a strin
into a date &alue) the e,pression shown pre&iously only functions correctly if the country@specific settins
match the strin e,pression.
To a&oid this problem) the "(eSeri+ function should be used to assin a fi,ed &alue to a date &ariable:
"i# A.4r $s "(e
A."(e = "(eSeri+ (2DD1< 1< 24)
The function parameter must be in the se5uence: year) month) day. The function ensures that the &ariable is
actually assined the correct &alue reardless of the country@specific settins
The Ti#eSeri+ function formats time details in the same way that the "(eSeri+ function formats
dates:
"i# A.4r $s "(e
A."(e = Ti#eSeri+(11< 23< 45)
Their parameters should be specified in the se5uence: hours) minutes) seconds.
+,tracting *ate and Ti%e *etails
The followin 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 weekday 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 e,tract the date or time sections from a specified "(e &ariable. The followin e,ample
checks whether the date sa&ed in A."(e is in the year "GG!.
"i# A."(e $s "(e
% 111 6ni(i+iX(ion o) A."(e
6) Zer(A."(e) = 2DD3 T&en
% 111 Spe'i)ie- -(e is in (&e .er 2DD3
En- 6)
6n the same way) the followin e,ample checks whether A.Ti#e is between H" and H' 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 weekday for the transferred date:
"i# A."(e $s "(e
"i# A.Cee/-. $s S(ring
% 111 ini(i+iXe A."(e
Se+e'( 7se Cee/".(A."(e)
'se 1
A.Cee/-. = @Sun-.@
'se 2
A.Cee/-. = @Aon-.@
'se 3
A.Cee/-. = @Tues-.@
'se 4
A.Cee/-. = @Ce-nes-.@
'se 5
A.Cee/-. = @T&urs-.@
'se 6
A.Cee/-. = @8ri-.@
'se 7
A.Cee/-. = @S(ur-.@
En- Se+e'(
Chapter $2 4orms 23
Note Sunday is considered the first day of the week.
1etrieving #yste% *ate and Ti%e
The followin functions are a&ailable in LibreOffice #asic to retrie&e the system time and system date:
Date
returns the present date as a strin. The format depends on locali<ation settins.
)ime
returns the present time as a strin.
No*
returns the present point in time 8date and time9 as a combined &alue of type
"(e.
Files and *irectories
%orkin with files is one of the basic tasks of an application. The LibreOffice /P6 pro&ides you with a whole
rane of objects with which you can create) open and modify Office documents. These are presented in
detail in the 6ntroduction to the /P6. *eardless of this) in some instances you will ha&e to directly access the
file system) search throuh directories or edit te,t files. The runtime library from LibreOffice #asic pro&ides
se&eral fundamental functions for these tasks.
Note
Some DOS@specific file and directory functions are no loner pro&ided in LibreOffice) or
their function is only limited. -or e,ample) support for the 7&"ir) 7&"ri*e and 7ur"ir
functions is not pro&ided. Some DOS@specific properties are no loner used in functions
that e,pect file properties as parameters 8for e,ample) to differentiate from concealed files
and system files9. This chane became necessary to ensure the reatest possible le&el of
platform independence for LibreOffice.
"d%inistering Files
!o+,atibilit- Mode
The 7o#p(ibi+i(.Ao-e statement and function pro&ide reater compatibility with ;#/) by chanin 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 ) takes 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) %'+er #o-e
"i# bAo-e s 2oo+en
bAo-e = 7o#p(ibi+i(.Ao-e()
#earching Through *irectories
The "ir function in LibreOffice #asic is responsible for searchin throuh directories for files and sub@
directories. %hen first re5uested) a strin containin the path of the directories to be searched must be
assined to "ir as its first parameter. The second parameter of "ir specifies the file or directory to be
searched for. LibreOffice #asic returns the name of the first directory entry found. To retrie&e the ne,t entry)
the "ir function should be re5uested without parameters. 6f the "ir function finds no more entries) it returns
an empty strin.
The followin e,ample shows how the "ir function can be used to re5uest 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 messae
bo,.
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
5ex(8i+e = "ir
Cen-
Asg2ox $++8i+es
En- Sub
The D 8<ero9 used as the second parameter in the "ir function ensures that "ir only returns the names of
files and directories are inored. The followin parameters can be specified here:
D : returns normal files
16 : sub@directories
The followin e,ample is &irtually the same as the precedin e,ample) but the "ir function transfers the
&alue HL as a parameter) which returns the sub@directories 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
5ex("ir = "ir
Cen-
Asg2ox $++"irs
En- Sub
Note
%hen re5uested in LibreOffice #asic) the "ir function) usin the parameter HL) only returns
the sub@directories of a folder. 6n ;#/) the function also returns the names of the standard
files so that further checkin is needed to retrie&e the directories only. %hen usin the
7o#p(ibi+i(.Ao-e ( (rue ) function) LibreOffice #asic beha&es like ;#/ and the
Dir function) usin parameter HL) returns sub@directories and standard files.
Note
The options pro&ided in ;#/ for searchin throuh directories specifically for files with the
concealed) system file) archived) and volume nameproperties does not e,ist in LibreOffice
#asic because the correspondin file system functions are not a&ailable on all operatin
systems.
Note
The path specifications listed in "ir may use the S and T place holders in both ;#/ and
LibreOffice #asic. 6n LibreOffice #asic) the S place holder may howe&er only be the last
character of a file name andQor file e,tension) which is not the case in ;#/.
Chapter $2 4orms 2'
Creating and *eleting *irectories
LibreOffice #asic pro&ides the A/"ir function for creatin directories.
A/"ir (@7!PSub"ir1@)
This function creates directories and sub@directories. /ll directories needed within a hierarchy are also
created) if re5uired. -or e,ample) if only the 7!PSub"ir1 directory e,ists) 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@)
6f the directory contains sub@directories or files) these are also deleted.You should therefore be careful when
usin ,#"ir.
Note
6n ;#/) the A/"ir and ,#"ir functions only relate to the current directory. 6n LibreOffice
#asic on the other hand) A/"ir and ,#"ir can be used to create or delete le&els of
directories.
Note
6n ;#/) ,#"ir produces an error messae if a directory contains a file. 6n LibreOffice
#asic) the directory and all its filesare deleted. 6f you use the 7o#p(ibi+i(.Ao-e
( (rue ) function) LibreOffice #asic will beha&e like ;#/.
Copying/ 1ena%ing/ *eleting and Checking the +,istence of Files
The followin 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 followin function you can rename the 3+-5#e file with 5e05#e. The $s keyword
synta,) and the fact that a comma is not used) oes back to the roots of the #asic lanuae.
5#e 3+-5#e $s 5e05#e
The followin call deletes the 8i+en#e file. 6f you want to delete directory 8includin its files9 use the ,#"ir
function.
Vi++(8i+en#e)
The 8i+eExis(s function can be used to check whether a file e,ists:
6) 8i+eExis(s(8i+en#e) T&en
Asg2ox @)i+e exis(s1@
En- 6)
1eading and Changing File Properties
%hen workin with files) it is sometimes important to be able to establish the file properties) the time the file
was last chaned and the lenth of the file.
The followin 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 mask in which the followin &alues are possible:
H : read@only file
HL : name of a directory
The followin e,ample determines the bit mask of the (es(1(x( file and checks whether this is read@only
whether it is a directory. 6f neither of these apply) 8i+e"es'rip(ion is assined the MnormalM strin.
"i# 8i+eAs/ $s 6n(eger
"i# 8i+e"es'rip(ion $s S(ring
8i+eAs/ = Ge($((r(@(es(1(x(@)
6) (8i+eAs/ $5" 1) U D T&en
8i+e"es'rip(ion = 8i+e"es'rip(ion G @ re-Hon+. @
En- 68
6) (8i+eAs/ $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
The flas used in ;#/ for 5ueryin the concealed) system file,archivedand volume namefile
properties are not supported in LibreOffice #asic because these are %indows@specific and
are not or are only partially a&ailable on other operatin systems.
The Se($((r function permits the properties of a file to be chaned. The followin call can therefore be
used to pro&ide a file with read@only status:
Se($((r(@(es(1(x(@< 1)
/n e,istin read@only status can be deleted with the followin 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 country@specific settins 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 lenth of a file in bytes 8as lon inteer &alue9.
8i+eLen(@(es(1(x(@) % Mro*i-es (&e +eng(& o) (&e )i+e
in b.(es
(riting and 1eading Te,t Files
LibreOffice #asic pro&ides a whole rane of methods for readin and writin files. The followin e,planations
relate to workin with te,t files 8notte,t documents9.
Writin1 Text 2iles
#efore a te,t file is accessed) it must first be opened. To do this) a free file handleis needed) which clearly
identifies the file for subse5uent file access.
The 8ree8i+e function is used to create a free file handle:
8i+e5o = 8ree8i+e
8i+e5o is an inteer &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 te,t file) the 3pen call is:
3pen 8i+en#e 8or 3u(pu( $s J8i+e5o
8i+en#e is a strin containin the name of the file. 8i+e5o is the handle created by the 8ree8i+e
function.
Chapter $2 4orms 2,
Once 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 te,t that is to be sa&ed as a
line of the te,t file.
Once the writin process has been completed) the file must be closed usin a 7+ose call:
7+ose J8i+e5o
/ain here) the file handle should be specified.
The followin e,ample shows how a te,t 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(@ % "e)ine )i+e n#e
8i+e5o = 8ree8i+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
1eading Te,t Files
Te,t files are read in the same way that they are written. The 3pen instruction used to open the file contains
the 8or 6npu( e,pression in place of the 8or 3u(pu( e,pression and) rather than the Print command for
writin data) the Line 6nput instruction should be used to read the data.
-inally) when callin up a te,t file) the eo) instruction is used to check whether the end of the file has been
reached:
eo)(8i+e5o)
The followin e,ample shows how a te,t file can be read:
"i# 8i+e5o $s 6n(eger
"i# 7urren(Line $s S(ring
"i# 8i+e $s S(ring
"i# 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)
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 messae bo,.
Message and $nput !o,es
LibreOffice #asic pro&ides the Asg2ox and 6npu(2ox functions for basic user communication.
*isplaying Messages
Asg2ox displays a basic information bo,) which can ha&e one or more buttons. 6n its simplest &ariant the
Asg2ox only contains te,t and an OO button:
Asg2ox @T&is is pie'e o) in)or#(ionI@
The appearance of the information bo, can be chaned usin a parameter. The parameter pro&ides the
option of addin additional buttons) definin the pre@assined button) and addin an information symbol.
Note
#y con&ention) the symbolic names i&en below are written in 0PP4*7/S4) to mark them
as predefined) rather than user@defined. .owe&er) the names are not case@sensiti&e.
The &alues for selectin the buttons are:
D< A2_3V @ OO button
1< A2_3V7$57EL @ OO and 7ancel button
2< A2_$23,T,ET,Z6G53,E @ /bort) *etry) and 6nore buttons
3< A2_ZES537$57EL @ Yes) 1o) and 7ancel buttons
4< A2_ZES53 @ Yes and 1o buttons
5< A2_,ET,Z7$57EL @ *etry and 7ancel buttons
To set a button as the default button) add one of the followin &alues to the parameter &alue from the list of
button selections. -or e,ample) to create Yes) 1o and 7ancel buttons 8&alue !9 where 7ancel is the default
8&alue (H"9) the parameter &alue is ! 2 (H" N (H(. The e,pression A2_ZES537$57EL + A2_"E82NTT353
is harder to write) but easier to understand.
D< A2_"E82NTT351 @ -irst button is default &alue
256< A2_"E82NTT352 @ Second button is default &alue
512< A2_"E82NTT353 @ Third button is default &alue
-inally) the followin information symbols are a&ailable and can also be displayed by addin the rele&ant
parameter &alues:
16< A2_6735ST3M @ Stop sin
32< A2_6735SNEST635 @ Uuestion mark
48< A2_6735ER7L$A$T635 @ 4,clamation point
H964< A2_67356583,A$T635 @ Tip icon
The followin call displays an information bo, with the Yes and 1o buttons 8&alue '9) of which the second
button 81o9 is set as the default &alue 8&alue "(L9 and which also recei&es a 5uestion mark 8&alue !"9)
'2"(L2!"N"K".
Asg2ox @"o .ou 0n( (o 'on(inue]@< 2L2
% or<
Asg2ox @"o .ou 0n( (o 'on(inue]@< A2_ZES53 +
Chapter $2 4orms 3$
A2_"E82NTT352 + A2_6735SNEST635
4ig"re $: Display of the !essage Bo8
6f an information bo, contains se&eral buttons) then a return &alue should be 5ueried to determine which
button has been pressed. The followin return &alues are a&ailable in this instance:
1< 6"3V @ Ok
2< 6"7$57EL @ 7ancel
3< 6"$23,T @ /bort
4< 6",ET,Z @ *etry
5 @ 6nore
6< 6"ZES @ Yes
7< 6"53 @ 1o
6n the pre&ious e,ample) checkin the return &alues could be as follows:
"i# i2ox s 6n(eger
i2ox = A2_ZES53 + A2_"E82NTT352 + A2_6735SNEST635
6) Asg2ox (@"o .ou 0n( (o 'on(inue]@< i2ox) = 6"ZES T&en
% or<
6) Asg2ox (@"o .ou 0n( (o 'on(inue]@< 2L2) = 6 T&en
% Zes bu((on presse-
E+se
% 5o bu((on presse-
En- 68
6n addition to the information te,t and the parameter for arranin the information bo,)
Asg2ox also permits a third parameter) which defines the te,t for the bo, title:
Asg2ox @"o .ou 0n( (o 'on(inue]@< 2L2< @2ox Ti(+e@
6f no bo, title is specified) the default is VsofficeW.
$nput !o, For 2uerying #i%ple #trings
The 6npu(2ox function 5ueries simple strins from the user. 6t is therefore a simple alternati&e to
confiurin dialos. 6npu(2ox recei&es three standard parameters:
/n information te,t.
/ bo, title.
H./ default &alue which can be added within the input area.
6npu(4+ = 6npu(2ox(@M+ese en(er *+ue!@< @Tes(@<
@-e)u+( *+ue@)
4ig"re 2: Display of the *np"t Bo8
The dimensions of the 6npu(2ox window cannot be chaned.
6f the user clicks the OO button) the 6npu(2ox returns the strin typed by the user 8or the default strin if it
was not chaned9.
6f the user clicks the 7ancel button or closes the window) the 6npu(2ox returns an empty strin.
Other Functions
!eep
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
#hell
4,ternal prorams can be started usin the Shell function.
S&e++(M(&n#e< Cin-o0s(.+e< Mr#< bS.n')
Pathname
the path of the proram to be e,ecuted.
6n +S@%indows) use 7on*er(ToN,L(M(&n#e) otherwise the command will
not work if M(&n#e contains spaces or national characters.
Windowstyle
the window in which the proram is started.
The followin &alues are possible:
G @ The proram recei&es the focus and is started in a concealed window.
H @ The proram recei&es the focus and is started in a normal@si<ed window.
" @ The proram recei&es the focus and is started in a minimi<ed window.
! @ The proram recei&es the focus and is started in a ma,imi<ed window.
' @ The proram is started in a normal@si<ed window) without recei&in the focus.
L @ The proram is started in a minimi<ed window) the focus remains in the
current window.
HG @ The proram is started in full screen mode.
Param
command line parameters to be transferred to the proram to be started.
bSync
wait for shell command to finish fla
(rue @ wait for shell command to finish
)+se @ don>t wait for shell command to finish
(ait and (ait'ntil
The Ci( statement suspends proram e,ecution for a specified time. The waitin period is specified in
milliseconds. The command:
Ci( 2DDD
specifies a delay of " seconds 8"GGG milliseconds9.
The Ci(Nn(i+ statement pro&ides a reater deree of compatibility with ;#/ parameter usae.
Ci(Nn(i+ takes a parameter of type "(e) with a combined date and time &alue. The command:
Ci(Nn(i+ 5o0 + Ti#e4+ue(@DD!DD!D2@)
specifies the same delay) " seconds) as the pre&ious e,ample.
+nviron
The En*iron function returns the en&ironmental &ariables of the operatin system. Dependin on the
system and confiuration) &arious types of data are sa&ed here. The followin call determines the
en&ironment &ariables of temporary directory of the operatin system:
"i# Te#p"ir
Te#p"ir=En*iron (@TEAM@)
Chapter $2 4orms 33
#asic $uide
Chapter 2
*ntro&"ction to the (P*
$ntroduction to the "P$
LibreOffice objects and methods) such as pararaphs) spreadsheets) and fonts) are accessible to LibreOffice
#asic throuh the LibreOffice application prorammin interface) or /P6. Throuh the /P6) for e,ample)
documents can be created) opened) modified and printed. The /P6 can be used not only by LibreOffice
#asic) but also by other prorammin lanuaes) such as =a&a and 722. The interface between the /P6 and
&arious prorammin lanuaes is pro&ided by somethin called Universal Network Objects801O9.
This chapter pro&ides a backround on the /P6. #uildin on this backround) the followin chapters will show
how the /P6 can be used to make LibreOffice do what you want it to do.
'niversal Network Ob5ects 6'NO7
LibreOffice pro&ides a prorammin interface in the form of the 0ni&ersal 1etwork Objects 801O9. This is an
object@oriented prorammin interface which LibreOffice sub@di&ides into &arious objects which for their part
ensure proram@controlled access to the Office packae.
Since LibreOffice #asic is a procedural prorammin lanuae) se&eral linuistic constructs ha&e had to be
added to it which enable the use of 01O.
To use a 0ni&ersal 1etwork Object in LibreOffice #asic) you will need a &ariable declaration for the
associated object. The declaration is made usin the "i# instruction 8see The Lanuae of LibreOffice
#asic9. The 3b:e'( type desination 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 initiali<ed so that it can be used. This can be done usin the
're(eNnoSer*i'e function:
3b: = 're(eNnoSer*i'e(@'o#1sun1s(r1)r#e1"es/(op@)
This call assins to the 3b: &ariable a reference to the newly created object.
'o#1sun1s(r1)r#e1"es/(op resembles an object typeF howe&er in 01O terminoloy it is called a
ser&ice rather than a type. 6n accordance with 01O philosophy) an Obj 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 LibreOffice #asic therefore corresponds to the type and class terms used
in other prorammin lanuaes.
There is) howe&er) one main difference: a 0ni&ersal 1etwork Object may support se&eral ser&ices at the
same time. Some 01O ser&ices in turn support other ser&ices so that) throuh one object) you are pro&ided
with a whole rane of ser&ices. -or e,ample) that the aforementioned object) which is based on the
ser&ice) can also include other ser&ices for loadin documents and for endin the proram.
Note
%hereas the structure of an object in ;#/ is defined by the class to which it belons) in
LibreOffice #asic the structure is defined throuh the ser&ices which it supports. / ;#/
object is always assined to precisely one sinle class. / LibreOffice #asic object can)
howe&er) support se&eral ser&ices.
Properties and Methods
/n object in LibreOffice #asic pro&ides a rane of properties and methods which can be called by means of
the object.
Chapter $2 4orms 33
Properties
Propertiesare like the properties of an objectF for e,ample) 8i+en#e and Ti(+e for a "o'u#en( object.
The properties are set by means of a simple assinment:
"o'u#en(1Ti(+e = @Libre3))i'e 2si' Mrogr##er%s Gui-e@
"o'u#en(18i+en#e = @bsgui-e1o-(@
/ property) just like a normal &ariable) has a type that defines which &alues it can record. The precedin
8i+en#e and Ti(+e properties are of the strin type.
.eal 3ro,erties and "+itated 3ro,erties
+ost of the properties of an object in LibreOffice #asic are defined as such in the 01O description of the
ser&ice. 6n addition to these MrealM properties) there are also properties in LibreOffice #asic which consist of
two methods at the 01O le&el. One of these is used to 5uery the &alue of the property and the other is
issued to set it 8ge( and se( methods9. The property has been &irtually imitated from two methods.
7haracter objects in 01O) for e,ample) pro&ide the ge(Mosi(ion and se(Mosi(ion methods throuh
which the associated key point can be called up and chaned. The LibreOffice #asic prorammer can
access the &alues throuh the Mosi(ion property. *eardless of this) the oriinal methods are also
a&ailable 8in our e,ample) ge(Mosi(ion and se(Mosi(ion9.
Methods
+ethods can be understood as functions that relate directly to an object and throuh which this object is
called. The precedin "o'u#en( object could) for e,ample) pro&ide a S*e method) which can be called as
follows:
"o'u#en(1S*e()
+ethods) just like functions) may contain parameters and return &alues. The synta, of such method calls is
oriented towards classic functions. The followin call also specifies the True parameter for the document
object when re5uestin the Sa&e method.
3/ = "o'u#en(1S*e(True)
Once the method has been completed) S*e sa&es a return &alue in the 3/ &ariable.
Modules/ #ervices and $nterfaces
LibreOffice 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 LibreOffice #asic
prorammers. %hen specifyin 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 e,pression) which specifies that it is a LibreOffice 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
e,ample would be:
6n addition to the module and ser&ice terms) 01O introduces the term 'interface>. %hile this term may be
familiar to =a&a prorammers) it is not used in #asic.
/n interface combines se&eral methods. 6n the strictest sense of the word) a ser&ice in 01O does not
support methods) but rather interfaces) which in turn pro&ide different methods. 6n other words) the methods
are assined 8as combinations9 to the ser&ice in interfaces. This detail may be of interest in particular to
=a&a@ or 722 prorammers) since in these lanuaes) the interface is needed to re5uest a method. 6n
LibreOffice #asic) this is irrele&ant. .ere) the methods are called directly by means of the rele&ant object.
-or an understandin of the /P6) it is) howe&er) useful to ha&e the assinment of methods to &arious
interfaces handy) since many interfaces are used in the different ser&ices. 6f you are familiar with an
interface) then you can transfer your knowlede from one ser&ice to another.
Some central interfaces are used so fre5uently) triered by different ser&ices) that they are shown aain at
the end of this chapter.
Tools for (orking with 'NO
The 5uestion remains as to which objects : or ser&ices if we are oin to remain with 01O terminoloy :
support which properties) methods and interfaces and how these can be determined. 6n addition to this
uide) you can et more information about objects from the followin sources: the suppor(sSer*i'e
method) the debu methods as well as the De&eloper>s $uide) and the /P6 reference.
The supports#ervice Method
/ number of 01O objects support the suppor(sSer*i'e method) with which you can establish whether an
object supports a particular ser&ice. The followin call) for e,ample) determines whether the Tex(E+e#en(
object supports the com.sun.star.te,t.Pararaph ser&ice.
3/ =
Tex(E+e#en(1suppor(sSer*i'e(@'o#1sun1s(r1(ex(1Mrgrp&@)
*ebug Properties
4&ery 01O object knows what properties) methods and interfaces it already contains. LibreOffice #asic
pro&ides properties that return these in the form of a strin containin a list. The correspondin properties
are:
DB+,properties
returns a strin containin all properties of an object
DB+,metho%s
returns a strin containin all methods of an object
DB+,supporte%Inter!aces
returns a strin containin all interfaces which support an object.
The followin proram code shows how "2G_proper(ies and "2G_#e(&o-s can be used in real@life
applications. 6t first creates the com.sun.star.frame.Desktop ser&ice and then displays the supported
properties and methods in messae bo,es.
"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 usin "2G_proper(ies) note that the function returns all properties that the ser&ices offered by the
object can theoretically support. 1o assurances are) howe&er) pro&ided for whether these can also be used
by the object in 5uestion. 6n &ery rare cases) before callin up some property) use the 6sE#p(. function to
check whether it is actually a&ailable.
*ebugging tools
0sin the "2G_ properties is a &ery crude method to disco&er the contents of an /P6 objects.
The watch window of the #asic 6D4 can display the properties of a 0no object 8but not the methods) not the
interfaces9.
To display all information a&ailable from an object and link to the correspondin /P6 documentation) use
instead 4ra- tool or M." tool.
Note
LibreOffice #asic does notpro&ide code completion. Only at run@time can you find out which
properties or methods are a&ailable for an object. /ll the abo&e debu tools work on a
runnin proram.
Chapter $2 4orms 3'
"P$ 1eference
+ore information about the a&ailable ser&ices) and their interfaces) methods and properties can be found in
the reference for the LibreOffice (P*.
Overview of Central $nterfaces
Some interfaces of LibreOffice can be found in many parts of the LibreOffice /P6. They define sets of
methods for abstract tasks which can be applied to &arious problems. .ere) you will find an o&er&iew of the
most common of these interfaces.
The oriin of the objects is e,plained at a later point in this uide. /t this point) only some of the abstract
aspects of objects) for which the LibreOffice /P6 pro&ides some central interfaces) are discussed.
Creating Conte,t.*ependent Ob5ects
The LibreOffice /P6 pro&ides two options for creatin objects. One 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 known as conte,t@independent ser&ices.
6n addition to conte,t@independent ser&ices) there are also conte,t@dependent ser&ices whose objects are
only useful when used in conjunction with another object. / drawin object for a spreadsheet document) for
e,ample) can therefore only e,ist in conjunction with this one document.
co+5sun5star5lan154Multiervice2actor- "nterface
7onte,t@dependent 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 drawin object can) for e,ample) be created as follows usin 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-r0ing1,e'(ng+e
S&pe@)
/ pararaph template in a te,t 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(.+e1Mrgrp&S
(.+e@)
Na%ed "ccess to #ubordinate Ob5ects
The R5#e$''ess and R5#e7on(iner interfaces are used in objects that contain subordinate objects)
which can be addressed usin a natural lanuae name.
%hile R5#e-$''ess permits access to the indi&idual objects) R5#e7on(iner takes on the insertion)
modification and deletion of elements.
co+5sun5star5container54#a+eAccess "nterface
/n e,ample of the use of R5#e$''ess is pro&ided by the s&ee(s object of a spreadsheet. 6t combines all
the paes within the spreadsheet. The indi&idual paes are accessed from the s&ee(s object) by usin 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 containin the names. The followin e,ample shows how all element names of a spreadsheet can
thereby be determined and displayed in a loop:
"i# S&ee(5#es
"i# 6 $s 6n(eger
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 e,ists within the basic object. The followin e,ample therefore displays a messae that
informs the user whether the Spre-s&ee( object contains a pae of the name S&ee(1.
6) S&ee(s1Bs2.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)
co+5sun5star5container54#a+e!ontainer "nterface
The R5#e7on(iner interface takes 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 followin is a practical e,ample of this. 6t calls a te,t document) which contains a S(.+e8#i+ies
object and uses this to in turn make the pararaph templates 8PararaphStyles9 of the document a&ailable.
"i# S(.+e8#i+ies $s 3b:e'(
"i# Mrgrp&S(.+es $s 3b:e'(
"i# 5e0S(.+e $s 3b:e'(
S(.+e8#i+ies = Tex(-o'1S(.+e8#i+ies
Mrgrp&S(.+es =
S(.+e8#i+ies1ge(2.5#e(@Mrgrp&S(.+es@)
Mrgrp&S(.+es1inser(2.5#e(@5e0S(.+e@< 5e0S(.+e)
Mrgrp&S(.+es1rep+'e2.5#e(@7&ngingS(.+e@< 5e0S(.+e)
Mrgrp&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
Mrgrp&S(.+es object. The rep+'e2.5#e line chanes the object behind 7&ngingS(.+e into
5e0S(.+e. -inally) the re#o*e2.5#e call remo&es the object behind 3+-S(.+e from
Mrgrp&S(.+es.
$nde,.!ased "ccess to #ubordinate Ob5ects
The R6n-ex$''ess and R6n-ex7on(iner interfaces are used in objects which contain subordinate
objects and which can be addressed usin an inde,.
R6n-ex$''ess pro&ides the methods for accessin indi&idual objects. R6n-ex7on(iner pro&ides
methods for insertin and remo&in elements.
Chapter $2 4orms 3,
co+5sun5star5container54"ndexAccess "nterface
R6n-ex$''ess pro&ides the ge(2.6n-ex and ge(7oun( methods for callin the subordinate objects.
ge(2.6n-ex pro&ides an object with a particular inde,. ge(7oun( returns how many objects are a&ailable.
"i# S&ee( $s 3b:e'(
"i# 6 $s 6n(eger
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 e,ample shows a loop that runs throuh all sheet elements one after another and sa&es a reference to
each in the S&ee( object &ariable. %hen workin with the inde,es) note that ge(7oun( returns the number
of elements. The elements in ge(2.6n-ex howe&er are numbered beinnin with G. The countin &ariable
of the loop therefore runs from G to ge(7oun(()H1.
co+5sun5star5container54"ndex!ontainer "nterface
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 correspondin functions in R5#e7on(iner.
$terative "ccess to #ubordinate Ob5ects
6n some instances) an object may contain a list of subordinate objects that cannot be addressed by either a
name or an inde,. 6n these situations) the REnu#er(ion and Renu#er(ion$''ess interfaces are
appropriate. They pro&ide a mechanism throuh which all subordinate elements of an objects can be
passed) step by step) without ha&in to use direct addressin.
co+5sun5star5container54Enu+eration and 4enu+erationAccess "nterfaces
The basic object must pro&ide the REnu#er(ion$''ess interface) which contains only a
're(eEnu#er(ion method. This returns an au,iliary object) which in turn pro&ides the REnu#er(ion
interface with the &sAoreE+e#en(s and nex(E+e#en( methods. Throuh these) you then ha&e access to
the subordinate objects.
The followin e,ample steps throuh all the pararaphs of a te,t:
"i# Mrgrp&Enu#er(ion $s 3b:e'(
"i# Mrgrp& $s 3b:e'(
Mrgrp&Enu#er(ion = Tex(-o'1Tex(1're(eEnu#er(ion
C&i+e Mrgrp&Enu#er(ion1&sAoreE+e#en(s()
Mrgrp& = Mrgrp&Enu#er(ion1nex(E+e#en(()
Cen-
The e,ample first creates a Mrgrp&Enu#er(ion au,iliary object. This radually returns the indi&idual
pararaphs of the te,t in a loop. The loop is terminated as soon as the &sAoreE+e#en(s method returns
the 8+se &alue) sinalin that the end of the te,t has been reached.
#> LibreOffice 3 Basic %"i&e
#asic $uide
Chapter 3
/or0ing with Doc"ments

(orking with *ocu%ents
The LibreOffice /P6 has been structured so that as many of its parts as possible can be used
uni&ersally for different tasks. This includes the interfaces and ser&ices for creatin) openin)
sa&in) con&ertin) and printin documents and for template administration. Since these function
areas are a&ailable in all types of documents) they are e,plained first in this chapter.
HThe StarDesktop
"Styles and Templates
The current docu%ent
6n pre&ious &ersions of the #asic Prorammin $uide 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 drawback : it does not work if the macro is started from the 6D4 because it
then refers to the 6D4) not the document. This code works only if the macro is started from the
document itselfR
You should instead use #asic object T&is7o#ponen(. 6t returns the document object on which
the macro is run. 6f you start the macro from the 6D4) 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 2si'
The #tar*esktop
%hen workin with documents) two ser&ices are used most fre5uently:
XThe com.sun.star.frame.Desktop ser&ice) which is similar to the core ser&ice
of LibreOffice. 6t pro&ides the functions for the frame object of LibreOffice)
under which all document windows are classified. Documents can also be
created) opened and imported usin this ser&ice.
XThe basic functionality for the indi&idual document objects is pro&ided by the
com.sun.star.document.OfficeDocument ser&ice. This pro&ides the methods
for sa&in) e,portin and printin documents.
The com.sun.star.frame.Desktop ser&ice is created automatically when LibreOffice is started. This
ser&ice can be addressed in LibreOffice #asic usin the lobal name S(r"es/(op.
The most important interface of the S(r"es/(op is com.sun.star.frame.Y7omponentLoader.
This basically co&ers the +o-7o#ponen(8ro#N,L method) which is responsible for creatin)
importin) and openin documents.
Note
The name of the S(r"es/(op object dates back to StarOffice () in which all document
windows were embedded in one common application called S(r"es/(op. 6n the present
&ersion of LibreOffice) a &isible S(r"es/(op is no loner used. The name S(r"es/(op
was) howe&er) retained for the frame object of LibreOffice 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 StarOffice ( which
pre&iously applied as a root object. .owe&er) unlike the old $pp+i'(ion object)
S(r"es/(op is primarily responsible for openin new documents. The functions resident
in the old $pp+i'(ion object for controllin the on@screen depiction of LibreOffice 8for
e,ample) 8u++S'reen) 8un'(ion2r4isib+e) Beig&() Ci-(&) Top) 4isib+e9 are no
loner used.
Note
%hereas the acti&e document in %ord is accessed throuh
$pp+i'(ion1$'(i*e"o'u#en( and in 4,cel throuh
$pp+i'(ion1$'(i*eCor/boo/< in LibreOffice) the S(r"es/(op is responsible for
this task. The acti&e document object is accessed in LibreOffice throuh the
S(r"es/(op17urren(7o#ponen( property) or throuh T&is7o#ponen(.
ThisCo%ponent
The lobal name T&is7o#ponen( enerally returns the same object as
S(r"es/(op17urren(7o#ponen() with one sinificant ad&antae. 6f you are runnin from
within the #asic 6D4) debuin or e,plorin) then S(r"es/(op returns the #asic 6D4 itself. This
is probably not what you want. T&is7o#ponen( returns the last pre&iously acti&e document.
#2 LibreOffice 3 Basic %"i&e
Basic "nfor+ation about /ocu+ents in LibreOffice
%hen workin with LibreOffice documents) it is useful to deal with some of the basic issues of
document administration in LibreOffice. This includes the way in which file names are structured
for LibreOffice documents) as well as the format in which files are sa&ed.
2ile #a+es in 6.L #otation
Since LibreOffice is a platform@independent application) it uses 0*L notation 8which is
independent of any operatin system9) as defined in the 6nternet Standard *-7 HI!J for file
names. Standard file names usin this system bein with the prefi, )i+e!OOO followed by the
local path. 6f the file name contains sub@directories) then these are separated by a sinle forward
slash) not with a backslash usually used under %indows. The followin path references the
(es(1o-( file in the doc directory on the 7: dri&e.
)i+e!OOO7!O-o'O(es(1o-(
To con&ert local file names into an 0*L) LibreOffice pro&ides the 7on*er(ToNr+ function. To
con&ert a 0*L into a local file name) LibreOffice 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 e,ample con&erts a local file name into a 0*L and displays it in a messae bo,. 6t then
con&erts a 0*L into a local file name and also displays this.
The 6nternet Standard *-7 HI!J) upon which this is based) permits use of the DHL) HX) and $H^
characters. /ll other characters are inserted as escape codin in the 0*Ls. To do this) they are
con&erted into their he,adecimal &alue in the 0T-@J set of characters and are preceded by a
percent sin. / space in a local file name therefore) for e,ample) becomes a E2D in the 0*L.
4ML 2ile 2or+at
LibreOffice documents are based on the Y+L file format. Y+L@based files can be opened and
edited with other prorams.
!o+,ression of 2iles
Since Y+L is based on standard te,t files) the resultant files are usually &ery lare. LibreOffice
therefore compresses the files and sa&es them as a Z6P file. #y means of a s(ore$sN,L method
option) the user can sa&e the oriinal Y+L files directly. See store/s0*L +ethod Options) below.
Creating/ Opening and $%porting *ocu%ents
Documents are opened) imported and created usin the method
StarDesktop.load7omponent-rom0*L80*L) -rame) Search-las) -ileProperties9 The first
parameter of +o-7o#ponen(8ro#N,L specifies the 0*L of the associated file.
/s the second parameter) +o-7o#ponen(8ro#N,L e,pects a name for the frame object of the
window that LibreOffice creates internally for its administration. The predefined _b+n/ name is
usually specified here) and this ensures that LibreOffice creates a new window.
0sin these parameters) the user can open a LibreOffice document) since place holders 8dummy
&alues9 can be assined 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 precedin call opens the (es(1o-( file and displays this in a new window.
Chapter $2 4orms #3
/ny number of documents can be opened in this way in LibreOffice #asic and then edited usin
the returned document objects.
Note
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 LibreOffice /P6.
.e,lacin1 the !ontent of the /ocu+ent Window
The named _b+n/ &alue for the 8r#e parameter ensures that LibreOffice creates a new
window for e&ery call from +o-7o#ponen(8ro#N,L. 6n some situations) it is useful to replace
the content of an e,istin window. 6n this case) the frame object of the window should contain an
e,plicit name. 1ote that this name must not bein with an underscore. -urthermore) the
Ser'&8+gs parameter must be set so that the correspondin framework is created) if it does
not already e,ist. The correspondin constant for Ser'&8+gs is:
Ser'&8+gs =
'o#1sun1s(r1)r#e18r#eSer'&8+g17,E$TE + _

'o#1sun1s(r1)r#e18r#eSer'&8+g1$LL
The followin e,ample shows how the content of an opened window can be replaced with the help
of the frame parameter and Ser'&8+gs:
"i# "o' $s 3b:e'(
"i# "u##.()
"i# Nr+ $s S(ring
"i# Ser'&8+gs $s Long

Ser'&8+gs =
'o#1sun1s(r1)r#e18r#eSer'&8+g17,E$TE + _

'o#1sun1s(r1)r#e18r#eSer'&8+g1$LL
Nr+ = @)i+e!OOO7!O(es(1o-(@
@A.8r#e@< Ser'&8+gs< "u##.)
Asg2ox @Mress 3V (o -isp+. (&e se'on- -o'u#en(1@
Nr+ = @)i+e!OOO7!O(es(21o-(@
@A.8r#e@< _
Ser'&8+gs< "u##.)
The e,ample first opens the (es(1o-( file in a new window with the frame name of A.8r#e.
Once the messae bo, has been confirmed) it replaces the content of the window with the
(es(21o-( file.
load!o+,onent2ro+6.L Method O,tions
The fourth parameter of the +o-7o#ponen(8ro#N,L function is a Mroper(.4+ue data field.
which pro&ides LibreOffice with &arious options for openin and creatin 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 strin as well as the associated &alue.
+o-7o#ponen(8ro#N,L supports the followin options:
As)emplate (Boolean)
if true) loads a new) untitled document from the i&en 0*L. 6f is false)
template files are loaded for editin.
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
#2 LibreOffice 3 Basic %"i&e
Ps&reP'on)igPregis(r.Pins(n'ePorgPopeno))i'ePo))i'e
PT.pe"e(e'(ion1x#+ file.
-ilterData (String)
defines additional options for filters.
-ilter.ptions (String)
defines additional options 8used by old filters9.
(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+ark.
"acro01ecution"o%e (Integer)
indicates if document macros may be e,ecuted. ;alues : see
com.sun.star.document.+acro4,ec+ode
2ass*or% (String)
transfers a password for a protected file.
$ea%.nl (Boolean)
&alue true loads a document in read@only mode.
Up%ateDoc"o%e (Integer)
indicates howQif links will be updated. ;alues : see
com.sun.star.document.0pdateDoc+ode
The followin e,ample shows how a te,t file separated by a comma in LibreOffice 7alc can be
opened usin the 8i+(er5#e option.
"i# "o' $s 3b:e'(
"i# 8i+eMroper(ies(1) $s 5e0
'o#1sun1s(r1bens1Mroper(.4+ue
"i# Nr+ $s S(ring
Nr+ = @)i+e!OOO7!O-o'1's*@
8i+eMroper(ies(D)15#e = @8i+(er5#e@
8i+eMroper(ies(D)14+ue =@Tex( H (x( H 's*
(S(r7+')@
8i+eMroper(ies(1)15#e = @8i+(er3p(ions@
8i+eMroper(ies(1)1*+ue = @44<34<D<1@
@_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 LibreOffice uses a LibreOffice 7alc te,t filter to open files. The
8i+(er3p(ions property contains the description of the synta, of the cs& file.
!reatin1 #ew /ocu+ents
LibreOffice automatically creates a new document if the document specified in the 0*L is a
template.
/lternati&ely) if only an empty document without any adaptation is needed) a pri*(e!)'(or.
0*L can be specified:
"i# "u##.()
"i# Nr+ $s S(ring
"i# "o' $s 3b:e'(
Chapter $2 4orms #3
Nr+ = @pri*(e!)'(or.Os0ri(er@
@_b+n/@< D< "u##.())
The call creates an empty LibreOffice writer document.
*ocu%ent Ob5ects
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.OfficeDocument ser&ice) which in turn pro&ides
two central interfaces:
The com.sun.star.frame.YStorable interface) which is responsible for sa&in documents.
The com.sun.star.&iew.YPrintable interface) which contains the methods for printin documents.
avin1 and Ex,ortin1 /ocu+ents
LibreOffice documents are sa&ed directly throuh the document object. The s(ore method of the
com.sun.star.frame.YStorable interface is a&ailable for this purpose:
"o'1s(ore()
This call functions pro&ided that the document has already been assined a memory space. This is
not the case for new documents. 6n this instance) the s(ore$sN,L method is used. This method
is also defined in com.sun.star.frame.YStorable 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##.())
6n addition to the precedin methods) com.sun.star.frame.YStorable also pro&ides some help
methods which are useful when sa&in documents. These are:
hasLocation()
specifies whether the document has already been assined a 0*L.
is$ea%onl()
specifies whether a document has read@only protection.
is"o%i!ie%()
specifies whether a document has been modified since it was last
sa&ed.
The code for sa&in a document can be e,tended by these options so that the document is only
sa&ed if the object has actually been modified and the file name is only 5ueried 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 e,ample first checks whether the rele&ant document has been modified since it was last
sa&ed. 6t only continues with the sa&in process if this is the case. 6f the document has already
been assined a 0*L and is not a read@only document) it is sa&ed under the e,istin 0*L. 6f it
does not ha&e a 0*L or was opened in its read@only status) it is sa&ed under a new 0*L.
## LibreOffice 3 Basic %"i&e
storeAs6.L Method O,tions
/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 usin the s(ore$sN,L method. These determine the procedure
LibreOffice uses when sa&in a document. s(ore$sN,L pro&ides the followin 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'e
PT.pe"e(e'(ion1x#+ file.
-ilterData (String)
defines additional options for filters.
-ilter.ptions (String)
defines additional options 8used by old filters9.
.3er*rite (Boolean)
allows a file which already e,ists to be o&erwritten without a 5uery.
2ass*or% (String)
transfers the password for a protected file.
Unpac'e% (Boolean)
sa&es the document 8not compressed9 in sub@directories.
The possibility to store documents in unpacked way is not currently
supported) the M0npackedM property is just inored) see *ss"e #23#2 .
The followin e,ample 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
"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 e,ample then sa&es "o' under the specified file name if a file already e,ists under the name.
3rintin1 /ocu+ents
Similar to sa&in) documents are printed out directly by means of the document object. The Mrin(
method of the com.sun.star.&iew.Yprintable interface is pro&ided for this purpose. 6n 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 throuh which LibreOffice can specify se&eral options for printin.
Chapter $2 4orms #'
The o,tions of the ,rint +ethod
The prin( method e,pects a Mroper(.4+ue data field as a parameter) which reflects the
settins of the print dialo of LibreOffice:
CopCount (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 paes of the copies.
Sort (Boolean)
sorts the paes when printin out se&eral copies 87op.7oun( [ H9.
2ages (String)
contains the list of the paes to be printed 8synta, as specified in print
dialo9.
Wait (Boolean)
if set to True the print method will return after the job is stored on the
waitin list for the printer. 0se this option if you want to close the
document after print.
The followin e,ample shows how se&eral paes of a document can be printed out usin the
Mges option:
"i# "o' $s 3b:e'(
"i# Mrin(Mroper(ies(1) $s 5e0
Mrin(Mroper(ies(D)15#e=@Mges@
Mrin(Mroper(ies(D)14+ue=@1H3_ 7_ L@
Mrin(Mroper(ies(1)15#e=@Ci(@
Mrin(Mroper(ies(1)14+ue=True
"o'1prin((Mrin(Mroper(ies())
3rinter selection and settin1s
The com.sun.star.&iew.YPrintable interface pro&ides the Mrin(er property) which selects the
printer. This property recei&es a Mroper(.4+ue data field with the followin settins:
Name (String)
specifies the name of printer.
2aper.rientation (0num)
specifies the paper orientation
8com.sun.star.&iew.PaperOrientation.PO*T*/6T &alue for portrait
format) com.sun.star.&iew.PaperOrientation.L/1DS7/P4 for landscape
format9.
2aper-ormat (0num)
specifies the paper format 8for e,ample)
com.sun.star.&iew.Paper-ormat./' for D61 /' or
com.sun.star.&iew.Paper-ormat.Letter for 0S letters9.
2aperSi4e (Si4e)
specifies the paper si<e in hundredths of a millimeter.
The followin e,ample shows how a printer can be chaned and the paper si<e set with the help of
the Mrin(er property.
#+ LibreOffice 3 Basic %"i&e
"i# "o' $s 3b:e'(
"i# Mrin(erMroper(ies(1) $s 5e0
"i# MperSiXe $s 5e0 'o#1sun1s(r10(1SiXe
MperSiXe1Ci-(& = 2DDDD % 'orrespon-s (o 2D '#
MperSiXe1Beig&( = 2DDDD % 'orrespon-s (o 2D '#
Mrin(erMroper(ies (D)15#e=@5#e@
Mrin(erMroper(ies (D)14+ue=@A. BM Lser:e(@
Mrin(erMroper(ies (1)15#e=@MperSiXe@
Mrin(erMroper(ies (1)14+ue=MperSiXe
"o'1Mrin(er = Mrin(erMroper(ies()
The e,ample defines an object named MperSiXe with the com.sun.star.awt.Si<e type. This is
needed to specify the paper si<e. -urthermore) it creates a data field for two Mroper(.4+ue
entries named Mrin(erMroper(ies. This data field is then initiali<ed with the &alues to be set
and assined the Mrin(er property. -rom the standpoint of 01O) the printer is not a real property
but an imitated one.
#tyles and Te%plates
#tyles
Styles are named lists containin formattin attributes. They work in all applications of LibreOffice
and help to sinificantly simplify formattin. 6f the user chanes one of the attributes of a style) then
LibreOffice automatically adjusts all document sections dependin on the attribute. The user can
therefore) for e,ample) chane the font type of all le&el one headers by means of a central
modification in the document.
t-le T-,es
Dependin on the rele&ant document types) LibreOffice reconi<es a whole rane of different
types of styles.
LibreOffice %riter supports the followin types of styles:
7haracter styles
Pararaph styles
-rame styles
Pae styles
1umberin styles
LibreOffice 7alc supports the followin types of styles:
7ell styles
Pae styles
LibreOffice 6mpress supports the followin types of styles:
7haracter element styles
Presentation styles
6n LibreOffice terminoloy) the different types of styles are called S(.+e8#i+ies in accordance
with the com.sun.star.style.Style-amily ser&ice on which they are based. The S(.+e8#i+ies
are accessed by means of the document object:
"i# "o' $s 3b:e'(
"i# S&ee( $s 3b:e'(
"i# S(.+e8#i+ies $s 3b:e'(
"i# 7e++S(.+es $s 3b:e'(
"o' = T&is7o#ponen(
S(.+e8#i+ies = "o'1S(.+e8#i+ies
Chapter $2 4orms #,
7e++S(.+es = S(.+e8#i+ies1ge(2.5#e(@7e++S(.+es@)
The e,ample uses the S(.+e8#i+ies property of a spreadsheet document to establish a list
containin all a&ailable cell styles.
The indi&idual styles can be accessed directly by means of an inde,:
"i# "o' $s 3b:e'(
"i# S&ee( $s 3b:e'(
"i# S(.+e8#i+ies $s 3b:e'(
"i# 7e++S(.+es $s 3b:e'(
"i# 7e++S(.+e $s 3b:e'(
"i# 6 $s 6n(eger
"o' = T&is7o#ponen(
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 e,ample displays the names of all cell styles one after another
in a messae bo,.
Note
The reference 7e++S(.+es(6) corresponds to the method ge(2.6n-ex()) which is
optional for these style container objects. 6t may not be a&ailable in all types of documents.
The method ge(2.5#e() is mandatory) and should always be a&ailable.
/etails about various for+attin1 o,tions
4ach type of style pro&ides a whole rane of indi&idual formattin properties. .ere is an o&er&iew
of the most important formattin properties and the points at which they are e,plained:
7haracter Properties ) com.sun.star.style.7haracterProperties ser&ice
Pararaph Properties ) com.sun.star.te,t.Pararaph ser&ice
7ell Properties ) com.sun.star.table.7ellProperties ser&ice
Pae Properties ) com.sun.star.style.PaeProperties ser&ice
7haracter element properties) ;arious ser&ices
The format properties are by no means restricted to the applications in which these are e,plained)
but instead can be used uni&ersally. -or e,ample) most of the pae properties described in
Spreadsheet can therefore be used not only in LibreOffice 7alc) but also in LibreOffice %riter.
+ore information about workin with styles can be found in the Defalut &alues for character an%
paragraph properties section in Te,t Documents.
Te%plates
Templates are au,iliary documents. They pro&ide a &ery con&enient way to store) maintain) and
distribute styles) macros) boiler@plate te,t) and other useful thins.
/ocu+ent and Te+,late T-,es
4ach major type of LibreOffice document has its own associated template type. 6n eneral) and for
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. 6n other words) code 8like the
abo&e e,amples9 that works in a particular document type should also work for the associated
template type.
Auto+atic 6,date
+ost template types ? Draw templates are the e,ception ? ha&e an automatic@update feature. 6f a
style in the template has been chaned) and you open a document created with that template) you
'> LibreOffice 3 Basic %"i&e
will see a messae askin whether to update the styles in the document. 6f you click on Yes) the
new or chaned styles will be copied into the document. Styles deleted from the template are not
remo&ed from documents.
/ problem may arise if you click on No: the styles will not be updated) and the automatic@update
feature will be turned off. /s of LibreOffice ;ersion !.H) this status does not show in the $06) nor is
there any $06 way to re@enable the feature. 8-or %riter documents only) you can use the -emplate
Changer e8tension to set this feature aain.9
The followin subroutine) adapted from the Template 7haner e,tension) will re@enable 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
Chapter $2 4orms '$
#asic $uide
Chapter #
-e8t Doc"ments
Te,t *ocu%ents
6n addition to pure strins) te,t documents also contain formattin information. These may appear
at any point in the te,t. The structure is further complicated by tables. These include not only
sinle@dimensional strins) but also two@dimensional fields. +ost word processin prorams now
finally pro&ide the option of placin drawin objects) te,t frames and other objects within a te,t.
These may be outside the flow of te,t and can be positioned anywhere on the pae.
This chapter presents the central interfaces and ser&ices of te,t documents.
The Structure of Te,t Documents
4ditin Te,t Documents
+ore Than =ust Te,t
The first section deals with the anatomy of te,t documents and concentrates on how a LibreOffice
#asic proram can be used to take iterati&e steps throuh a LibreOffice document. 6t focuses on
pararaphs) pararaph portions and their formattin.
The second section focuses on efficiently workin with te,t documents. -or this purpose)
LibreOffice pro&ides se&eral help objects) such as the Tex(7ursor object) which e,tend beyond
those specified in the first section.
The third section mo&es beyond work with te,ts. 6t concentrates on tables) te,t frames) te,t fields)
bookmarks) content directories and more.
6nformation about how to create) open) sa&e and print documents is described in /or0ing with
Doc"ments) because it can be used not only for te,t documents) but also for other types of
documents.
The #tructure of Te,t *ocu%ents
/ te,t document can essentially contain four types of information:
The actual te,t
Templates for formattin characters) pararaphs) and paes
1on@te,t elements such as tables) raphics and drawin objects
$lobal settins for the te,t document
This section concentrates on the te,t and associated formattin options.
Paragraphs and Paragraph Portions
The core of a te,t document consists of a se5uence of pararaphs. These are neither named nor
inde,ed and there is therefore no possible way of directly accessin indi&idual pararaphs. The
pararaphs can howe&er be se5uentially tra&ersed with the help of the Enu#er(ion object
described in 6ntroduction to the /P6 This allows the pararaphs to be edited.
%hen workin with the Enu#er(ion object) one special scenario should) howe&er) be noted: it
not only returns pararaphs) but also tables 8strictly speakin) in LibreOffice %riter) a table is a
special type of pararaph9. #efore accessin a returned object) you should therefore check
whether the returned object supports the com.sun.star.te,t.Pararaph ser&ice for pararaphs or
the com.sun.star.te,t.Te,tTable ser&ice for tables.
The followin e,ample tra&erses the contents of a te,t document in a loop and uses a messae in
each instance to inform the user whether the object in 5uestion is a pararaph 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(
Tb+e@) T&en
Asg2ox @T&e 'urren( b+o'/ 'on(ins (b+e1@
Chapter $2 4orms '3
En- 6)

6)
Tex(E+e#en(1suppor(sSer*i'e(@'o#1sun1s(r1(ex(1Mr
grp&@) T&en
Asg2ox @T&e 'urren( b+o'/ 'on(ins
prgrp&1@
En- 6)
Cen-
The e,ample creates a "o' document object which references the current LibreOffice document.
%ith the aid of "o') the e,ample then creates an Enu#er(ion object that tra&erses throuh the
indi&idual parts of the te,t 8pararaphs and tables9 and assins the current element to
Tex(E+e#en( object. The e,ample uses the suppor(sSer*i'e method to check whether the
Tex(E+e#en( is a pararaph or a table.
3ara1ra,hs
The com.sun.star.te,t.Pararaph ser&ice rants access to the content of a pararaph. The te,t in
the pararaph can be retrie&ed and modified usin the Strin property:
"i# "o' $s 3b:e'(
"i# Enu# $s 3b:e'(
"o' = T&is7o#ponen(
Enu# = "o'1Tex(1're(eEnu#er(ion

6)
grp&@) T&en
Tex(E+e#en(1S(ring =
,ep+'e(Tex(E+e#en(1S(ring< @.ou@< @N@)
,ep+'e(Tex(E+e#en(1S(ring< @(oo@< @2@)
,ep+'e(Tex(E+e#en(1S(ring< @)or@< @4@)
En- 6)
Cen-
The e,ample opens the current te,t document and passes throuh it with the help of the
4numeration object. 6t uses the Tex(E+e#en(1S(ring property in all pararaphs to access the
rele&ant pararaphs and replaces the .ou< (oo n- )or strins with the N< 2 n- 4
characters. The ,ep+'e function used for replacin does not fall within the standard linuistic
scope of LibreOffice #asic. This is an instance of the e,ample function described in )earch an&
7eplace.
Note
The content of the procedure described here for accessin the pararaphs of a te,t is
comparable with the Pararaphs listin used in ;#/) which is pro&ided in the ,nge and
"o'u#en( objects a&ailable there. %hereas in ;#/ the pararaphs are accessed by their
number 8for e,ample) by the Mrgrp&(1) call9) in LibreOffice #asic) the Enu#er(ion
object described pre&iously should be used.
There is no direct counterpart in LibreOffice #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 switchin to a Tex(7ursor which
allows for na&iation at the le&el of characters) sentences and words.
'2 LibreOffice 3 Basic %"i&e
Paragraph Portions
The pre&ious e,ample may chane the te,t as re5uested) but it may sometimes also destroy the
formattin.
This is because a pararaph in turn consists of indi&idual sub@objects. 4ach of these sub@objects
contains its own formattin information. 6f the center of a pararaph) for e,ample) contains a word
printed in bold) then it will be represented in LibreOffice by three pararaph portions: the portion
before the bold type) then the word in bold) and finally the portion after the bold type) which is
aain depicted as normal.
6f the te,t of the pararaph is now chaned usin the pararaph>s S(ring property) then
LibreOffice first deletes the old pararaph portions and inserts a new pararaph portion. The
formattin of the pre&ious sections is then lost.
To pre&ent this effect) the user can access the associated pararaph portions rather than the entire
pararaph. Pararaphs pro&ide their own Enu#er(ion object for this purpose. The followin
e,ample shows a double loop which passes o&er all pararaphs of a te,t document and the
pararaph portions they contain and applies the replacement processes from the pre&ious
e,ample:
"i# "o' $s 3b:e'(
"i# Enu#1 $s 3b:e'(
"i# Enu#2 $s 3b:e'(
"i# Tex(Mor(ion $s 3b:e'(
"o' = T&is7o#ponen(
Enu#1 = "o'1Tex(1're(eEnu#er(ion

% +oop o*er ++ prgrp&s

6)
grp&@) T&en
Enu#2 = Tex(E+e#en(1're(eEnu#er(ion
% +oop o*er ++ subHprgrp&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@)
,ep+'e(Tex(Mor(ion1S(ring< @(oo@< @2@)
,ep+'e(Tex(Mor(ion1S(ring< @)or@< @4@)
Cen-
En- 6)
Cen-
The e,ample runs throuh a te,t document in a double loop. The outer loop refers to the
pararaphs of the te,t. The inner loop processes the pararaph portions in these pararaphs. The
e,ample code modifies the content in each of these pararaph portions usin the S(ring property
of the strin. as is the case in the pre&ious e,ample for pararaphs. Since howe&er) the pararaph
portions are edited directly) their formattin information is retained when replacin the strin.
For%atting
There are &arious ways of formattin te,t. The easiest way is to assin the format properties
directly to the te,t se5uence. This is called direct formattin. Direct formattin is used in particular
with short documents because the formats can be assined by the user with the mouse. You can)
for e,ample) hihliht a certain word within a te,t usin bold type or center a line.
Chapter $2 4orms '3
6n addition to direct formattin) you can also format te,t usin templates. This is called indirect
formattin. %ith indirect formattin) the user assins a pre@defined template to the rele&ant te,t
portion. 6f the layout of the te,t is chaned at a later date) the user only needs to chane the
template. LibreOffice then chanes the way in which all te,t portions which use this template are
depicted.
Note
6n ;#/) the formattin properties of an object are usually spread o&er a rane of sub@
objects 8for e,ample) ,nge18on() ,nge12or-ers) ,nge1S&-ing)
,nge1Mrgrp&8or#(9. The properties are accessed by means of cascadin
e,pressions 8for e,ample) ,nge18on(1$++7ps9. 6n LibreOffice #asic) the formattin
properties on the other hand are a&ailable directly) usin the rele&ant objects
8Tex(7ursor< Mrgrp&) and so on9. You will find an o&er&iew of the character and
pararaph properties a&ailable in LibreOffice in the followin two sections.
Note
The formattin properties can be found in each object 8Mrgrp&< Tex(7ursor) and so
on9 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. Objects that allow character properties to be set ha&e to
support the com.sun.star.style.7haracterProperties ser&ice. LibreOffice reconi<es a whole rane
of ser&ices that support this ser&ice. These include the pre&iously described
com.sun.star.te,t.Pararaph ser&ices for pararaphs as well as the com.sun.star.te,t.Te,tPortion
ser&ices for pararaph portions.
The com.sun.star.style.7haracterProperties ser&ice does not pro&ide any interfaces) but instead
offers a rane of properties throuh which character properties can be defined and called. /
complete list of all character properties can be found in the LibreOffice /P6 reference. The
followin list describes the most important properties:
Char-ontName (String)
name of font type selected.
CharColor (Long)
te,t color.
Char(eight (-loat)
character heiht in points 8pt9.
CharUn%erline (Constant group)
type of underscore 8constants in accordance with
com.sun.star.awt.-ont0nderline9.
CharWeight (Constant group)
font weiht 8constants in accordance with
com.sun.star.awt.-ont%eiht9.
CharBac'Color (Long)
backround color.
Char5eep)ogether (Boolean)
suppression of automatic line break.
CharStleName (String)
name of character template.
Paragraph Properties
-ormattin information that does not refer to indi&idual characters) but to the entire pararaph is
considered to be a pararaph property. This includes the distance of the pararaph from the ede
'# LibreOffice 3 Basic %"i&e
of the pae as well as line spacin. The pararaph properties are a&ailable throuh the
com.sun.star.style.PararaphProperties ser&ice.
4&en the pararaph properties are a&ailable in &arious objects. /ll objects that support the
com.sun.star.te,t.Pararaph ser&ice also pro&ide support for the pararaph properties in
com.sun.star.style.PararaphProperties.
/ complete list of the pararaph properties can be found in the LibreOffice /P6 reference. The
most common pararaph properties are:
2araA%6ust (enum)
&ertical te,t orientation 8constants in accordance with
com.sun.star.style.Pararaph/djust9.
2araLineSpacing (struct)
line spacin 8structure in accordance with
com.sun.star.style.LineSpacin9.
2araBac'Color (Long)
backround color.
2araLe!t"argin (Long)
left marin in HGGths of a millimeter.
2ara$ight"argin (Long)
riht marin in HGGths of a millimeter.
2ara)op"argin (Long)
top marin in HGGths of a millimeter.
2araBottom"argin (Long)
bottom marin in HGGths of a millimeter.
2ara)abStops (Arra o! struct)
type and position of tabs 8array with structures of the type
com.sun.star.style.TabStop9.
2araStleName (String)
name of the pararaph template.
+,a%ple0 si%ple -TM e,port
The followin e,ample demonstrates how to work with formattin information. 6t iterates throuh a
te,t document and creates a simple .T+L file. 4ach pararaph is recorded in its own .T+L
element TMU for this purpose. Pararaph portions displayed in bold type are marked usin a T2U
.T+L element when e,portin.
"i# 8i+e5o $s 6n(eger< 8i+en#e $s S(ring< 7urLine
$s S(ring
"i# "o' $s 3b:e'(
"i# Enu#1 $s 3b:e'(< Enu#2 $s 3b:e'(
"i# 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@
"o' = T&is7o#ponen(
Chapter $2 4orms ''

6)
grp&@) T&en
7urLine = @TMU@
% +oop o*er ++ prgrp& por(ions

6) Tex(Mor(ion17&rCeig&( =
'o#1sun1s(r10(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 e,ample is oriented towards the e,amples for runnin thouh the
pararaph portions of a te,t already discussed pre&iously. The functions for writin the .T+L file)
as well as a test code that checks the font weiht of the correspondin te,t portions and pro&ides
pararaph portions in bold type with a correspondin .T+L ta) ha&e been added.
*efault values for character and paragraph properties
Directformattin always takes priority o&er indirectformattin. 6n other words) formattin usin
templates is assined a lower priority than direct formattin in a te,t.
4stablishin whether a section of a document has been directly or indirectly formatted is not easy.
The symbol bars pro&ided by LibreOffice show the common te,t properties such as font type)
weiht and si<e. .owe&er) whether the correspondin settins are based on template or direct
formattin in the te,t is still unclear.
LibreOffice #asic pro&ides the ge(Mroper(.S((e method) with which prorammers can check
how a certain property was formatted. /s a parameter) this takes the name of the property and
returns a constant that pro&ides information about the oriin of the formattin. The followin
responses) which are defined in the com.sun.star.beans.PropertyState enumeration) are possible:
com.sun.star.beans.2ropertState.DI$0C),VALU0
the property is defined directly in the te,t 8direct formattin9
com.sun.star.beans.2ropertState.D0-AUL),VALU0
the property is defined by a template 8indirect formattin9
com.sun.star.beans.2ropertState.A"BI+U.US,VALU0
the property is unclear. This status arises) for e,ample) when 5ueryin
the bold type property of a pararaph) which includes both words
depicted in bold and words depicted in normal font.
The followin e,ample shows how format properties can be edited in LibreOffice. 6t searches
throuh a te,t for pararaph portions which ha&e been depicted as bold type usin direct
'+ LibreOffice 3 Basic %"i&e
formattin. 6f it encounters a correspondin pararaph portion) it deletes the direct formattin usin
the se(Mroper(.To"e)u+( method and assins a A.2o+- character template to the
correspondin pararaph portion.
"i# "o' $s 3b:e'(
"i# Enu#1 $s 3b:e'(
"i# Enu#2 $s 3b:e'(
"i# Tex(Mor(ion $s 3b:e'(

"o' = T&is7o#ponen(

6)
grp&@) T&en
% +oop o*er ++ prgrp& por(ions
6) Tex(Mor(ion17&rCeig&( = _
'o#1sun1s(r10(18on(Ceig&(123L" $5" _
Tex(Mor(ion1ge(Mroper(.S((e(@7&rCeig&(@)
= _

'o#1sun1s(r1bens1Mroper(.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)
Cen-
En- 6)
Cen-
+diting Te,t *ocu%ents
The pre&ious section has already discussed a whole rane of options for editin te,t documents)
focusin on the com.sun.star.te,t.Te,tPortion and com.sun.star.te,t.Pararaph ser&ices) which
rant access to pararaph portions as well as pararaphs. These ser&ices are appropriate for
applications in which the content of a te,t is to be edited in one pass throuh a loop. .owe&er) this
is not sufficient for many problems. LibreOffice pro&ides the com.sun.star.te,t.Te,t7ursor ser&ice
for more complicated tasks) includin na&iatin backward within a document or na&iatin based
on sentences and words rather than Tex(Mor(ions.
The Te,tCursor
/ Tex(7ursor in the LibreOffice /P6 is comparable with the &isible cursor used in a LibreOffice
document. 6t marks a certain point within a te,t document and can be na&iated in &arious
directions throuh the use of commands. The Tex(7ursor objects a&ailable in LibreOffice #asic
should not) howe&er) be confused with the &isible cursor. These are two &ery different thins.
Note
Terminoloy differs from that used in ;#/: 6n terms of scope of function) the *ane object
from ;#/ can be compared with the Te,t7ursor object in LibreOffice and not : as the
name possibly suests : with the *ane object in LibreOffice.
The Te,t7ursor object in LibreOffice) for e,ample) pro&ides methods for na&iatin and chanin
te,t which are included in the *ane object in ;#/ 8for e,ample) +o&eStart) +o&e4nd)
Chapter $2 4orms ',
6nsert#efore) 6nsert/fter9. The correspondin counterparts of the Te,t7ursor object in LibreOffice
are described in the followin sections.
#avi1atin1 within a Text
The Tex(7ursor object in LibreOffice #asic acts independently from the &isible cursor in a te,t
document. / proram@controlled position chane of a Tex(7ursor object has no impact
whatsoe&er on the &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 usin 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 7ursor object created in this way supports the 'o#1sun1s(r1(ex(1Tex(7ursor ser&ice)
which in turn pro&ides a whole rane of methods for na&iatin within te,t documents. The
followin e,ample first mo&es the Tex(7ursor ten characters to the left and then three characters
to the riht:
7ursor1goLe)((1D< 8+se)
7ursor1go,ig&((3< 8+se)
/ Tex(7ursor can hihliht a complete area. This can be compared with hihlihtin a point in
the te,t usin 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 hihlihted. -or e,ample) the Tex(7ursor in the
followin e,ample
7ursor1go,ig&((1D< 8+se)
7ursor1goLe)((3< True)
first mo&es ten characters to the riht without hihlihtin) and then mo&es back three characters
and hihlihts this. The area hihlihted by the Tex(7ursor therefore beins after the se&enth
character in the te,t and ends after the tenth character.
.ere are the central methods that the com.sun.star.te,t.Te,t7ursor ser&ice pro&ides for na&iation:
goLe!t (Count# 01pan%)
jumps 7ount characters to the left.
go$ight (Count# 01pan%)
jumps 7ount characters to the riht.
gotoStart (01pan%)
jumps to the start of the te,t document.
goto0n% (01pan%)
jumps to the end of the te,t document.
goto$ange ()e1t$ange# 01pan%)
jumps to the specified Tex(,nge@Object.
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 ne,t word.
goto2re3iousWor% (01pan%)
jumps to the start of the pre&ious word.
+> LibreOffice 3 Basic %"i&e
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.
goto0n%.!Sentence (01pan%)
jumps to the end of the current sentence.
gotoNe1tSentence (01pan%)
jumps to the start of the ne,t 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 pararaph.
goto0n%.!2aragraph (01pan%)
jumps to the end of the current pararaph.
gotoNe1t2aragraph (01pan%)
jumps to the start of the ne,t pararaph.
goto2re3ious2aragraph (01pan%)
jumps to the start of the pre&ious pararaph.
isStart.!2aragraph ()
returns True if the Tex(7ursor is at the start of a pararaph.
is0n%.!2aragraph ()
returns True if the Tex(7ursor is at the end of a pararaph.
The te,t is di&ided into sentences on the basis of sentence symbols. Periods are) for e,ample)
interpreted as symbols indicatin the end of sentences. 86n 4nlish) at least) they must be followed
by a space) tab) or return for this to work.9
The Expn- parameter is a #oolean &alue which specifies whether the area passed o&er durin
na&iation is to be hihlihted. /ll na&iation methods furthermore return a #oolean parameter
which specifies whether the na&iation was successful or whether the action was terminated for
lack of te,t.
The followin is a list of se&eral methods for editin hihlihted areas usin a Tex(7ursor and
which also support the com.sun.star.te,t.Te,t7ursor ser&ice:
collapse)oStart ()
resets the hihlihtin and positions the Tex(7ursor at the start of the
pre&iously hihlihted area.
collapse)o0n% ()
resets the hihlihtin and positions the Tex(7ursor at the end of the
pre&iously hihlihted area.
Chapter $2 4orms +$
isCollapse% ()
returns True if the Tex(7ursor does not co&er any hihlihtin at
present.
2or+attin1 Text with Text!ursor
The com.sun.star.te,t.Te,t7ursor ser&ice supports all the character and pararaph properties that
were presented at the start of this chapter.
The followin e,ample shows how these can be used in conjunction with a Tex(7ursor. 6t
passes throuh a complete document and formats the first word of e&ery sentence in bold type.
"i# "o' $s 3b:e'(
"i# Mro'ee- $s 2oo+en
"o' = T&is7o#ponen(
7ursor = "o'1Tex(1're(eTex(7ursor
"o
7ursor1go(oEn-3)Cor-(True)
7ursor17&rCeig&( =
'o#1sun1s(r10(18on(Ceig&(123L"
Mro'ee- = 7ursor1go(o5ex(Sen(en'e(8+se)
7ursor1go(o5ex(Cor-(8+se)
Loop C&i+e Mro'ee-
The e,ample first creates a document object for the te,t that has just been opened. Then it iterates
throuh the entire te,t) sentence by sentence) and hihlihts each of the first words and formats
this in bold.
.etrievin1 and Modif-in1 Text !ontents
6f a Tex(7ursor contains a hihlihted area) then this te,t is a&ailable by means of the S(ring
property of the Tex(7ursor object. The followin e,ample uses the S(ring property to display
the first words of a sentence in a messae bo,:
"i# "o' $s 3b:e'(
"o' = T&is7o#ponen(
"o
Asg2ox 7ursor1S(ring
Loop C&i+e Mro'ee-
The first word of each sentence can be modified in the same way usin the S(ring property:
"i# "o' $s 3b:e'(
"o' = T&is7o#ponen(
"o
7ursor1S(ring = @Nps@
Loop C&i+e Mro'ee-
+2 LibreOffice 3 Basic %"i&e
6f the Tex(7ursor contains a hihlihted area) an assinment to the S(ring property replaces
this with the new te,t. 6f there is no hihlihted area) the te,t is inserted at the present
Tex(7ursor position.
"nsertin1 !ontrol !odes
6n some situations) it is not the actual te,t of a document) but rather its structure that needs
modifyin. LibreOffice pro&ides control codes for this purpose. These are inserted in the te,t and
influence its structure. The control codes are defined in the com.sun.star.te,t.7ontrol7haracter
roup of constants. The followin control codes are a&ailable in LibreOffice:
2A$A+$A2(,B$0A5
pararaph break.
LIN0,B$0A5
line break within a pararaph.
S.-),(&2(0N
possible point for syllabification.
(A$D,(&2(0N
obliatory point for syllabification.
(A$D,S2AC0
protected space that is not spread out or compressed in justified te,t.
To insert the control codes) you need not only the cursor but also the associated te,t document
objects. The followin e,ample inserts a pararaph after the "Gth character of a te,t:
"i# "o' $s 3b:e'(
"o' = T&is7o#ponen(
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 hihlihted by the Tex(7ursor remains after the insert operation. 6f the True
parameter is passed here) then inser(7on(ro+7&r'(er replaces the current te,t.
#earching for Te,t Portions
6n many instances) it is the case that a te,t is to be searched for a particular term and the
correspondin point needs to be edited. /ll LibreOffice 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 Ser'&"es'rip(or must first be created.
This defines what LibreOffice searches for in a document. / Ser'&"es'rip(or is an object
which supports the 'o#1sun1s(r1u(i+1 Ser'&"es'rip(or ser&ice and can be created by
means of the 're(eSer'&"es'rip(or method of a document:
"i# Ser'&"es' $s 3b:e'(
Ser'&"es' = "o'1're(eSer'&"es'rip(or
Once the Ser'&"es'rip(or has been created) it recei&es the te,t to be searched for:
Ser'&"es'1ser'&S(ring=@n. (ex(@
6n terms of its function) the Ser'&"es'rip(or is best compared with the search dialo from
LibreOffice. 6n a similar way to the search window) the settins needed for a search can be set in
the Ser'&"es'rip(or object.
The properties are pro&ided by the com.sun.star.util.SearchDescriptor ser&ice:
Chapter $2 4orms +3
SearchBac'*ar%s (Boolean)
searches throuh the te,t backward rather than forward.
SearchCaseSensiti3e (Boolean)
takes uppercase and lowercase characters into consideration durin
the search.
Search$egular01pression (Boolean)
treats the search e,pression like a reular e,pression.
SearchStles (Boolean)
searches throuh the te,t for the specified pararaph template.
SearchWor%s (Boolean)
only searches for complete words.
The LibreOffice Ser'&Si#i+ri(. 8or Vfu<<y matchW9 function is also a&ailable in LibreOffice
#asic. %ith this function) LibreOffice searches for an e,pression that may be similar to but not
e,actly the same as the search e,pression. The number of additional) deleted and modified
characters for these e,pressions can be defined indi&idually. .ere are the associated properties of
the 'o#1sun1s(r1u(i+1Ser'&"es'rip(or ser&ice:
SearchSimilarit (Boolean)
performs a similarity search.
SearchSimilaritA%% (Short)
number of characters which may be added for a similarity search.
SearchSimilarit01change (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)
takes all de&iation rules into consideration at the same time for the
search e,pression.
Once the Ser'&"es'rip(or has been prepared as re5uested) it can be applied to the te,t
document. The LibreOffice documents pro&ide the )in-8irs( and )in-5ex( methods for this
purpose:
8oun- = "o'1)in-8irs( (Ser'&"es')
"o Nn(i+ 6s5u++(8oun-)
% E-i( ser'& resu+(s111
8oun- = "o'1)in-5ex(( 8oun-1En-< Ser'&"es')
Loop
The e,ample finds all matches in a loop and returns a Tex(,nge object) which refers to the
found te,t passae.
Exa+,le7 i+ilarit- earch
This e,ample shows how a te,t can be searched for the word Mturno&erM and the results formatted
in bold type. / similarity search is used so that not only the word Vturno&erW) but also the plural form
Mturno&ersM and declinations such as Mturno&er>sM are found. The found e,pressions differ by up to
two letters from the search e,pression:
"i# Ser'&"es' $s 3b:e'(
"i# "o' $s 3b:e'(
+2 LibreOffice 3 Basic %"i&e
"o' = T&is7o#ponen(
Ser'&"es' = "o'1're(eSer'&"es'rip(or
Ser'&"es'1Ser'&S(ring=@(urno*er@
Ser'&"es'1Ser'&Si#i+ri(. = True
Ser'&"es'1Ser'&Si#i+ri(.$-- = 2
Ser'&"es'1Ser'&Si#i+ri(.Ex'&nge = 2
Ser'&"es'1Ser'&Si#i+ri(.,e#o*e = 2
Ser'&"es'1Ser'&Si#i+ri(.,e+x = 8+se
8oun- = "o'1)in-8irs( (Ser'&"es')
"o Nn(i+ 6s5u++(8oun-)
8oun-17&rCeig&( =
8oun- = "o'1)in-5ex(( 8oun-1En-< Ser'&"es')
Loop
Note
The basic idea of search and replace in LibreOffice is comparable to that used in ;#/. #oth
interfaces pro&ide you with an object) throuh which the properties for searchin and
replacin can be defined. This object is then applied to the re5uired te,t area in order to
perform the action. %hereas the responsible au,iliary object in ;#/ can be reached
throuh the -ind property of the *ane object) in LibreOffice #asic it is created by the
're(eSer'&"es'rip(or or 're(e,ep+'e"es'rip(or call of the document
object. 4&en the search properties and methods a&ailable differ.
/s in the old /P6 from LibreOffice) searchin and replacin te,t in the new /P6 is also performed
usin the document object. %hereas pre&iously there was an object called Ser'&Se((ings
especially for definin the search options) in the new object searches are now performed usin a
Ser'&"es'rip(or or ,ep+'e"es'rip(or object for automatically replacin te,t. These
objects co&er not only the options) but also the current search te,t and) if necessary) the
associated te,t replacement. The descriptor objects are created usin the document object)
completed in accordance with the rele&ant re5uests) and then transferred back to the document
object as parameters for the search methods.
1eplacing Te,t Portions
=ust as with the search function) the replacement function from LibreOffice is also a&ailable in
LibreOffice #asic. The two functions are handled identically. / special object which records the
parameters for the process is also first needed for a replacement process. 6t is called a
,ep+'e"es'rip(or and supports the com.sun.star.util.*eplaceDescriptor ser&ice. /ll the
properties of the Ser'&"es'rip(or described in the pre&ious pararaph are also supported by
,ep+'e"es'rip(or1 -or e,ample) durin a replacement process) case sensiti&ity can also be
acti&ated and deacti&ated) and similarity searches can be performed.
The followin e,ample demonstrates the use of ,ep+'e"es'rip(ors for a search within a
LibreOffice document.
"i# 6 $s Long
"i# "o' $s 3b:e'(
"i# ,ep+'e $s 3b:e'(
"i# 2ri(is&Cor-s(5) $s S(ring
"i# 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+'e1Ser'&S(ring = 2ri(is&Cor-s(6)
,ep+'e1,ep+'eS(ring = NSCor-s(6)
Chapter $2 4orms +3
"o'1rep+'e$++(,ep+'e)
5ex( 6
The e,pressions for searchin and replacin are set usin the Ser'&S(ring and
,ep+'eS(ring properties of the ,ep+'e"es'rip(ors. The actual replacement process is
finally implemented usin the rep+'e$++ method of the document object) which replaces all
occurrences of the search e,pression.
Exa+,le7 searchin1 and re,lacin1 text with re1ular ex,ressions
The replacement function of LibreOffice is particularly effecti&e when used in conjunction with
reular e,pressions. These pro&ide the option of definin a &ariable search e,pression with place
holders and special characters rather than a fi,ed &alue.
The reular e,pressions supported by LibreOffice are described in detail in the online help section
for LibreOffice. .ere are a few e,amples:
/ period within a search e,pression stands for any character. The search e,pression sh.rt
therefore can stand for both for s&ir( and for s&or(.
The character \ marks the start of a pararaph. /ll occurrences of the name Me(er that are at
the start of a pararaph can therefore be found usin the search e,pression QMe(er.
The character P marks a pararaph end. /ll occurrences of the name Me(er that are at the end
of a pararaph can therefore be found usin the search e,pression Me(erF.
/ S indicates that the precedin character may be repeated any number of times. 6t can be
combined with the period as a place holder for any character. The (e#per1*e e,pression) for
e,ample) can stand for the e,pressions (e#pern'e and (e#per(ure.
The followin e,ample shows how all empty lines in a te,t document can be remo&ed with the help
of the reular e,pression \P:
"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+'e1Ser'&,egu+rExpression = True
,ep+'e1Ser'&S(ring = @QF@
,ep+'e1,ep+'eS(ring = @@
"o'1rep+'e$++(,ep+'e)
More Than 8ust Te,t
So far) this chapter has only dealt with te,t pararaphs and their portions. #ut te,t documents may
also contain other objects. These include tables) drawins) te,t fields and directories. /ll of these
objects can be anchored to any point within a te,t.
Thanks to these common features) all of these objects in LibreOffice support a common basic
ser&ice called com.sun.star.te,t.Te,t7ontent. This pro&ides the followin properties:
Anchor)pe (0num)
determines the anchor type of a Tex(7on(en( object 8default &alues in
accordance with com.sun.star.te,t.Te,t7ontent/nchorType
enumeration9.
Anchor)pes (se7uence o! 0num)
enumeration of all $n'&orT.pes which support a special
Tex(7on(en( object.
)e1tWrap (0num)
determines the te,t wrap type around a Tex(7on(en( object 8default
&alues in accordance with com.sun.star.te,t.%rapTe,t+ode
+# LibreOffice 3 Basic %"i&e
enumeration9.
The Tex(7on(en( objects also share some methods ? in particular) those for creatin) insertin
and deletin objects.
/ new Tex(7on(en( object is createdusin the 're(e6ns(n'e method of the document
object.
/n object is insertedusin the inser(Tex(7on(en( method of the te,t object.
Tex(7on(en( objects are deletedusin the re#o*eTex(7on(en( method.
You will find a rane of e,amples which use these methods in the followin sections.
Tables
The followin e,ample creates a table with the help of the create6nstance method described
pre&iously.
"i# "o' $s 3b:e'(
"i# Tb+e $s 3b:e'(
"o' = T&is7o#ponen(
Tb+e =
"o'1're(e6ns(n'e(@'o#1sun1s(r1(ex(1Tex(Tb+e@)
Tb+e1ini(i+iXe(5< 4)
"o'1Tex(1inser(Tex(7on(en((7ursor< Tb+e< 8+se)
Once created) the table is set to the number of rows and columns re5uested usin an
ini(i+iXe call and then inserted in the te,t document usin inser(Tex(7on(en(1
/s can be seen in the e,ample) the inser(Tex(7on(en( method e,pects 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 8True &alue9 or is to be inserted before the current selection in the te,t
88+se9
Note
%hen creatin and insertin tables in a te,t document) objects similar to those a&ailable in
;#/ are used in LibreOffice #asic: The document object and a Tex(7ursor object in
LibreOffice #asic) or the ,nge object as the ;#/ counterpart. %hereas the
"o'u#en(1Tb+es1$-- method takes on the task of creatin and settin the table in
;#/) this is created in LibreOffice #asic in accordance with the pre&ious e,ample usin
're(e6ns(n'e) initiali<ed) and inserted in the document throuh
inser(Tex(7on(en(.
The tables inserted in a te,t document can be determined usin a simple loop. The method
ge(Tex(Tb+es() of the te,t document object is used for this purpose:
"i# "o' $s 3b:e'(
"i# Tex(Tb+es $s 3b:e'(
"i# Tb+e $s 3b:e'(
"i# 6 $s 6n(eger
"o' = T&is7o#ponen(
Tex(Tb+es = "o'1ge(Tex(Tb+es()
8or 6 = D (o Tex(Tb+es1'oun( H 1
Tb+e = Tex(Tb+es(6)
% E-i(ing (b+e
5ex( 6
Chapter $2 4orms +'
Note
Te,t tables are a&ailable in LibreOffice throuh the Tex(Tb+es list of the document object.
The pre&ious e,ample shows how a te,t table can be created. The options for accessin
te,t tables are described in the followin section.
Editin1 Tables
/ table consists of indi&idual rows. These in turn contain the &arious cells. Strictly speakin) there
are no table columns in LibreOffice. These are produced implicitly by arranin the rows 8one
under another9 ne,t to one another. To simplify access to the tables) LibreOffice) howe&er)
pro&ides some methods which operate usin columns. These are useful if no cells ha&e been
mered in the table.
Let us first take the properties of the table itself. These are defined in the
com.sun.star.te,t.Te,tTable ser&ice. .ere is an list of the most important properties of the table
object:
Bac'Color (Long)
backround 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 pae.
Wi%th (Long)
absolute width of the table in HGGths of a millimeter.
.ows
/ table consists of a list containin rows. The followin e,ample shows how the rows of a table can
be retrie&ed and formatted.
"i# "o' $s 3b:e'(
"i# Tb+e $s 3b:e'(
"i# ,o0s $s 3b:e'(
"i# ,o0 $s 3b:e'(
"i# 6 $s 6n(eger

"o' = T&is7o#ponen(
Tb+e =
,o0s = Tb+e1ge(,o0s
8or 6 = D To ,o0s1ge(7oun(() H 1
,o0 = ,o0s1ge(2.6n-ex(6)
,o012'/7o+or = GB88DD88
5ex(
++ LibreOffice 3 Basic %"i&e
The e,ample first creates a list containin all rows usin a Tb+e1ge(,o0s call. The ge(7oun(
and ge(2.6n-ex methods allow the list to be further processed and belons 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.te,t.Te,tTable*ow ser&ice.
.ere are the central methods of the com.sun.star.table.Ytable*ows interface:
getBIn%e1(Integer)
returns a row object for the specified inde,.
getCount()
returns the number of row objects.
insertBIn%e1(In%e1# Count)
inserts 7ount rows in the table as of the 6n-ex position.
remo3eBIn%e1(In%e1# Count)
deletes 7ount 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
mered cells.
The com.sun.star.te,t.Te,tTable*ow ser&ice pro&ides the followin properties:
Bac'Color (Long)
backround color of row.
(eight (Long)
heiht of line in HGGths of a millimeter.
IsAuto(eight (Boolean)
table heiht is dynamically adapted to the content.
Vert.rient (const)
&ertical orientation of the te,t frame : details on &ertical orientation of
the te,t within the table 8&alues in accordance with
com.sun.star.te,t.;ertOrientation9
!olu+ns
7olumns are accessed in the same way as rows) usin 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
throuh ge(7o+u#ns. They can) howe&er) only be used in tables that do not contain mered table
cells. 7ells cannot be formatted by column in LibreOffice #asic. To do so) the method of formattin
indi&idual table cells must be used.
!ells
4ach cell of a LibreOffice document has a uni5ue name. 6f the cursor of LibreOffice is in a cell)
then the name of that cell can be seen in the status bar. The top left cell is usually called /H and
the bottom riht 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 throuh the ge(7e++2.5#e() method
of the table object. The followin e,ample shows a loop that passes throuh all the cells of a table
and enters the correspondin row and column numbers into the cells.
"i# "o' $s 3b:e'(
"i# Tb+e $s 3b:e'(
"i# ,o0s $s 3b:e'(
"i# ,o06n-ex $s 6n(eger
"i# 7o+s $s 3b:e'(
"i# 7o+6n-ex $s 6n(eger
"i# 7e++5#e $s S(ring
Chapter $2 4orms +,
"i# 7e++ $s 3b:e'(
"o' = T&is7o#ponen(
Tb+e =
,o0s = Tb+e1ge(,o0s
7o+s = Tb+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++ = Tb+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 te,t. 6t supports the 're(eTex(7ursor interface for
creatin an associated Tex(7ursor object.
7e++7ursor = 7e++1're(eTex(7ursor()
/ll formattin options for indi&idual characters and pararaphs are therefore automatically
a&ailable.
The followin e,ample searches throuh all tables of a te,t document and applies the riht@alin
format to all cells with numerical &alues by means of the correspondin pararaph property.
"i# "o' $s 3b:e'(
"i# Tb+e $s 3b:e'(
"i# 7e++5#es
"i# 7e++ $s 3b:e'(
"i# 7e++7ursor $s 3b:e'(
"i# 6 $s 6n(eger
"i# W $s 6n(eger
"o' = T&is7o#ponen(
Tex(Tb+es = "o'1ge(Tex(Tb+es()
8or 6 = D (o Tex(Tb+es1'oun( H 1
Tb+e = Tex(Tb+es(6)
7e++5#es = Tb+e1ge(7e++5#es()
8or W = D (o N2oun-(7e++5#es)
7e++ = Tb+e1ge(7e++2.5#e(7e++5#es(W))
6) 6s5u#eri'(7e++1S(ring) T&en
7e++7ursor = 7e++1're(eTex(7ursor()
7e++7ursor1pr$-:us( =
'o#1sun1s(r1s(.+e1Mrgrp&$-:us(1,6GBT
En- 6)
5ex(
5ex(
The e,ample creates a Tex(Tb+es list containin all tables of a te,t that are tra&ersed in a loop.
LibreOffice then creates a list of the associated cell names for each of these tables. There are
passed throuh in turn in a loop. 6f a cell contains a numerical &alue) then the e,ample chanes
the formattin correspondinly. To do this) it first creates a Tex(7ursor object which makes
reference to the content of the table cell and then adapts the pararaph properties of the table cell.
,> LibreOffice 3 Basic %"i&e
Te,t Fra%es
Te,t frames are considered to be Tex(7on(en( objects) just like tables and raphs. They may
essentially consist of standard te,t) but can be placed at any position on a pae and are not
included in the te,t flow.
/s with all Tex(7on(en( objects) a distinction is also made with te,t frames between the actual
creation and insertion in the document.
"i# "o' $s 3b:e'(
"i# 8r#e $s 3b:e'(
"o' = T&is7o#ponen(
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 te,t frame is created usin the 're(e6ns(n'e method of the document object. The te,t
frame created in this way can then be inserted in the document usin the inser(Tex(7on(en(
method of the Tex( object. 6n so doin) the name of the proper com.sun.star.te,t.Te,t-rame
ser&ice should be specified.
The te,t frame>s insert position is determined by a 7ursor object) which is also e,ecuted when
inserted.
Note
Te,t frames are LibreOffice>s counterpart to the position frame used in %ord. %hereas ;#/
uses the "o'u#en(18r#es1$-- method for this purpose) creation in LibreOffice #asic is
performed usin the pre&ious procedure with the aid of a Tex(7ursor as well as the
're(e6ns(n'e method of the document object.
Te,t frame objects pro&ide a rane 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.te,t.#ase-rameProperties ser&ice) which is also supported by each Tex(8r#e
ser&ice. The central properties are:
Bac'Color (Long)
backround color of the te,t frame.
Bottom"argin (Long)
Le!t"argin (Long)
$ight"argin (Long)
)op"argin (Long)
(eight (Long)
heiht of te,t frame in HGGths of a millimeter.
Wi%th (Long)
width of te,t frame in HGGths of a millimeter.
(ori.rient (const)
hori<ontal orientation of te,t frame 8in accordance with
com.sun.star.te,t..oriOrientation9.
Chapter $2 4orms ,$
Vert.rient (const)
&ertical orientation of te,t frame 8in accordance with
com.sun.star.te,t.;ertOrientation9.
The followin e,ample creates a te,t frame usin the properties described pre&iously:
"i# "o' $s 3b:e'(
"i# 8r#e $s 3b:e'(
"o' = T&is7o#ponen(
8r#e =
8r#e1Ci-(& = 3DDD
8r#e1Beig&( = 1DDD
8r#e1$n'&orT.pe =
'o#1sun1s(r1(ex(1Tex(7on(en($n'&orT.pe1$S_7B$,$7TE
,
8r#e1TopArgin = D
8r#e12o((o#Argin = D
8r#e1Le)(Argin = D
8r#e1,ig&(Argin = D
8r#e12or-er"is(n'e = D
8r#e1Bori3rien( =
'o#1sun1s(r1(ex(1Bori3rien((ion1535E
8r#e14er(3rien( =
'o#1sun1s(r1(ex(14er(3rien((ion1L65E_T3M
The e,ample creates a Tex(7ursor as the insertion mark for the te,t frame. This is positioned
between the first and second word of the te,t. The te,t frame is created usin
"o'1're(e6ns(n'e. The properties of the te,t frame objects are set to the startin &alues
re5uired.
The interaction between the $n'&orT.pe 8from the Tex(7on(en( Ser&ice9 and 4er(3rien(
8from the 2se8r#eMroper(ies Ser&ice9 properties should be noted here. $n'&orT.pe
recei&es the $S_7B$,$7TE, &alue. The te,t frame is therefore inserted directly in the te,t flow and
beha&es like a character. 6t can) for e,ample) be mo&ed into the ne,t line if a line break occurs.
The L65E_T3M &alue of the 4er(3rien( property ensures that the upper ede of the te,t frame
is at the same heiht as the upper ede of the character.
Once initiali<ation is complete) the te,t frame is finally inserted in the te,t document usin a call
from inser(Tex(7on(en(.
To edit the content of a te,t frame) the user uses the Tex(7ursor) which has already been
mentioned numerous times and is also a&ailable for te,t frames.
"i# "o' $s 3b:e'(
"i# 8r#e $s 3b:e'(
"i# 8r#e7ursor $s 3b:e'(
"o' = T&is7o#ponen(
8r#e =
8r#e1Ci-(& = 3DDD
8r#e1Beig&( = 1DDD
,2 LibreOffice 3 Basic %"i&e
8r#e7ursor = 8r#e1're(eTex(7ursor()
8r#e7ursor1'&rCeig&( =
8r#e7ursor1pr$-:us( =
'o#1sun1s(r1s(.+e1Mrgrp&$-:us(17E5TE,
8r#e7ursor1S(ring = @T&is is s#++ Tes(I@
The e,ample creates a te,t frame) inserts this in the current document and opens a Tex(7ursor
for the te,t frame. This cursor is used to set the frame font to bold type and to set the pararaph
orientation to centered. The te,t frame is finally assined the VThis is a small testRW strin.
Te,t Fields
Te,t fields are Tex(7on(en( objects because they pro&ide additional loic e,tendin beyond pure
te,t. Te,t fields can be inserted in a te,t document usin the same methods as those used for
other Tex(7on(en( objects:
"i# "o' $s 3b:e'(
"i# "(eTi#e8ie+- $s 3b:e'(
"o' = T&is7o#ponen(
"(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 e,ample inserts a te,t field with the current date at the start of the current te,t document. The
True &alue of the 6s"(e property results in only the date and not time bein displayed. The
8+se &alue for 6s8ixe- ensures that the date is automatically updated when the document is
opened.
Note
%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 5uestion defines it in
LibreOffice #asic.
Note
6n the past) te,t fields were accessed usin a whole rane of methods that LibreOffice
made a&ailable in the old Se+e'(ion object 8for e,ample 6nser(8ie+-)
"e+e(eNser8ie+-) Se(7ur8ie+-).
6n LibreOffice) the fields are administered usin an object@oriented concept. To create a te,t field) a
te,t field of the type re5uired should first be created and initiali<ed usin the properties re5uired.
The te,t field is then inserted in the document usin the inser(Tex(7on(en( method. /
correspondin source te,t can be seen in the pre&ious e,ample. The most important field types
and their properties are described in the followin sections.
6n addition to insertin te,t fields) searchin a document for the fields can also be an important
task. The followin e,ample shows how all te,t fields of a te,t document can be tra&ersed in a loop
and checked for their rele&ant type.
"i# "o' $s 3b:e'(
"i# Tex(8ie+-Enu# $s 3b:e'(
"i# Tex(8ie+- $s 3b:e'(
"i# 6 $s 6n(eger
"o' = T&is7o#ponen(
Tex(8ie+-Enu# = "o'1ge(Tex(8ie+-s1're(eEnu#er(ion
Chapter $2 4orms ,3
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()i
e+-1"(eTi#e@) T&en
Asg2ox @"(eO(i#e@
E+se6)
Tex(8ie+-1suppor(sSer*i'e(@'o#1sun1s(r1(ex(1(ex()i
e+-1$nno((ion@) T&en
Asg2ox @$nno((ion@
E+se
Asg2ox @un/no0n@
En- 6)
Cen-
The startin point for establishin the te,t fields present is the Tex(8ie+-s list of the document
object. The e,ample creates an Enu#er(ion object on the basis of this list) with which all te,t
fields can be 5ueried in turn in a loop. The te,t fields found are checked for the ser&ice supported
usin the suppor(sSer*i'e method. 6f the field pro&es to be a dateQtime field or an annotation)
then the correspondin field type is displayed in an information bo,. 6f on the other hand) the
e,ample encounters another field) then it displays the information VunknownW.
#elow) you will find a list of the most important te,t fields and their associated properties. /
complete list of all te,t fields is pro&ided in the /P6 reference in the
'o#1sun1s(r1(ex(1(ex()ie+- module. 8%hen listin the ser&ice name of a te,t field)
uppercase and lowercase characters should be used in LibreOffice #asic) as in the pre&ious
e,ample.9
#u+ber of 3a1es8 Words and !haracters
The te,t fields
com.sun.star.te,t.te,tfield.Pae7ount
com.sun.star.te,t.te,tfield.%ord7ount
com.sun.star.te,t.te,tfield.7haracter7ount
return the number of paes) words) or characters of a te,t. They support the followin property:
Numbering)pe (const)
numberin format 8uidelines in accordance with constants from
com.sun.star.style.1umberinType9.
!urrent 3a1e
The number of the current pae can be inserted in a document usin the
com.sun.star.te,t.te,tfield.Pae1umber te,t field. The followin properties can be specified:
Numbering)pe (const)
number format 8uidelines in accordance with constants from
com.sun.star.style.1umberinType9.
.!!set (short)
offset added to the number of paes 8neati&e specification also
possible9.
The followin e,ample shows how the number of paes can be inserted into the footer of a
document.
"i# "o' $s 3b:e'(
"i# "(eTi#e8ie+- $s 3b:e'(
"i# MgeS(.+es $s 3b:e'(
"i# S(-Mge $s 3b:e'(
,2 LibreOffice 3 Basic %"i&e
"i# 8oo(er7ursor $s 3b:e'(
"i# Mge5u#ber $s 3b:e'(
"o' = T&is7o#ponen(
Mge5u#ber =
"o'1're(e6ns(n'e(@'o#1sun1s(r1(ex(1(ex()ie+-1Mg
e5u#ber@)
Mge5u#ber15u#beringT.pe =
'o#1sun1s(r1s(.+e15u#beringT.pe1$,$267
MgeS(.+es =
"o'1S(.+e8#i+ies1ge(2.5#e(@MgeS(.+es@)
S(-Mge = MgeS(.+es(@"e)u+(@)
S(-Mge18oo(er6s3n = True
8oo(er7ursor =
S(-Mge18oo(erTex(Le)(1Tex(1're(eTex(7ursor()
S(-Mge18oo(erTex(Le)(1Tex(1inser(Tex(7on(en((8oo(e
r7ursor< Mge5u#ber< 8+se)
The e,ample first creates a te,t field which supports the com.sun.star.te,t.te,tfield.Pae1umber
ser&ice. Since the header and footer lines are defined as part of the pae templates of LibreOffice)
this is initially established usin the list of all MgeS(.+es.
To ensure that the footer line is &isible) the 8oo(er6s3n property is set to True. The te,t field is
then inserted in the document usin the associated te,t object of the left@hand footer line.
Annotations
/nnotation fields 8com.sun.star.te,t.te,tfield./nnotation9 can be seen by means of a small yellow
symbol in the te,t. 7lickin on this symbol opens a te,t field) in which a comment on the current
point in the te,t can be recorded. /n annotation field has the followin properties.
Author (String)
name of author.
Content (String)
comment te,t.
Date (Date)
date on which annotation is written.
/ate / Ti+e
/ date Q time field 8com.sun.star.te,t.te,tfield.DateTime9 represents the current date or the current
time. 6t supports the followin properties:
Is-i1e% (Boolean)
if True) the time details of the insertion remain unchaned) 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 8com.sun.star.util.DateTime structure9
Number-ormat (const)
format in which the time or date is depicted.
Chapter $2 4orms ,3
!ha,ter #a+e / #u+ber
The name of the current chapter is a&ailable throuh a te,t field of the
com.sun.star.te,t.te,tfield.7hapter type. The form can be defined usin two properties.
Chapter-ormat (const)
determines whether the chapter name or the chapter number is
depicted 8in accordance with com.sun.star.te,t.7hapter-ormat9
Le3el (Integer)
determines the chapter le&el whose name andQor chapter number is to
be displayed. The &alue G stands for hihest le&el a&ailable.
!ook%arks
#ookmarks 8Ser&ice com.sun.star.te,t.#ookmark9 are Tex(7on(en( objects. #ookmarks are
created and inserted usin the concept already described pre&iously:
"i# "o' $s 3b:e'(
"i# 2oo/#r/ $s 3b:e'(
"o' = T&is7o#ponen(
2oo/#r/ =
"o'1're(e6ns(n'e(@'o#1sun1s(r1(ex(12oo/#r/@)
2oo/#r/15#e = @A. boo/#r/s@
"o'1Tex(1inser(Tex(7on(en((7ursor< 2oo/#r/< True)
The e,ample creates a 7ursor) which marks the insert position of the bookmark and then the
actual bookmark object 82oo/#r/9. The bookmark is then assined a name and is inserted in the
document throuh inser(Tex(7on(en( at the cursor position.
The bookmarks of a te,t are accessed throuh a list called 2oo/#r/s. The bookmarks can either
be accessed by their number or their name.
The followin e,ample shows how a bookmark can be found within a te,t) and a te,t inserted at its
position.
"i# "o' $s 3b:e'(
"i# 2oo/#r/ $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/@
6n this e,ample) the ge(2.5#e method is used to find the bookmark re5uired by means of its
name. The 're(eTex(7ursor2.,nge call then creates a 7ursor) which is positioned at the
anchor position of the bookmark. The cursor then inserts the te,t re5uired at this point.
,# LibreOffice 3 Basic %"i&e
#asic $uide
Chapter '
)prea&sheet Doc"ments
#preadsheet *ocu%ents
LibreOffice #asic pro&ides an e,tensi&e interface for proram@controlled creation and editin of
spreadsheets. This chapter describes how to control the rele&ant ser&ices) methods and properties
of spreadsheet documents:
The Structure of Spreadsheet
4ditin 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 focusin on cell areas
and the options for searchin and replacin cell contents.
Note
The ,nge object allows you to address any table area and has been e,tended in the new
/P6.
The #tructure of #preadsheets
The document object of a spreadsheet is based on the com.sun.star.sheet.SpreadsheetDocument
ser&ice. 4ach of these documents may contain se&eral spreadsheets. 6n this uide) a table@based
document or spreadsheet document is the entire document) whereas a spreadsheet 8or sheet for
short9 is a sheet 8table9 in the document.
Note
Different terminoloy for spreadsheets and their content is used in ;#/ and LibreOffice
#asic. %hereas the document object in ;#/ is called a %orkbook and its indi&idual paes
%orksheets) they are called SpreadsheetDocument and Sheet in LibreOffice #asic.
#preadsheets
You can access the indi&idual sheets of a spreadsheet document throuh the S&ee(s list.
The followin e,amples show you how to access a sheet either throuh its number or its name.
Example 1: access by means of the number (numbering begins with 0)
"i# "o' $s 3b:e'(
"i# S&ee( $s 3b:e'(
"o' = T&is7o#ponen(
S&ee( = "o'1S&ee(s (D)
Note
T&is7o#ponen( returns the currently acti&e document.
The e,pression "o'1S&ee(s(D) is a #asic simplification of the /P6 call :
"o'1ge(S&ee(s1ge(2.6n-ex(D)
Example 2: access by means of the name
"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@)
6n the first e,ample) the sheet is accessed by its number 8countin beins at G9. 6n the second
e,ample) 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. 6n addition to pro&idin se&eral interfaces for editin the
content) this ser&ice pro&ides the followin properties:
IsVisible (Boolean)
&alue True if the spreadsheet is &isible.
2ageStle (String)
name of the pae template for the spreadsheet.
.ena+in1 heets
/ sheet pro&ides methods ge(5#e and se(5#e to read and modify its name. #asic can handle
both methods like a property 5#e. .ere we rename the first sheet of the spreadsheet document.
"i# "o' $s 3b:e'(
,+ LibreOffice 3 Basic %"i&e
"i# S&ee( $s 3b:e'(

"o' = T&is7o#ponen(
S&ee(15#e = @8irs(@
!reatin1 and /eletin1 heets
The S&ee(s container of a spre-s&ee( document is also used to create and delete indi&idual
sheets. The followin e,ample uses the &s2.5#e method to check if a sheet called MySheet
e,ists. 6f it does) the method determines a correspondin object reference by usin the
ge(2.5#e method and then sa&es the reference in a &ariable in S&ee(. 6f the correspondin
sheet does not e,ist) 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.Y1ame7ontainer interface as described in *ntro&"ction to the (P*.
The interface com.sun.star.sheet.Spreadsheets pro&ides a better method to create a new sheet:
inser(5e02.5#e. 6t inserts a new sheet with the name specified by the first arument) at the
position specified by the second arument.
"i# "o' $s 3b:e'(

"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.Y1ame7ontainer interface pro&ides a method to remo&e a sheet of a
i&en name:
"i# "o' $s 3b:e'(

"o' = T&is7o#ponen(
"o'1S&ee(s1re#o*e2.5#e(@3(&erS&ee(@)
1ows and Colu%ns
4ach sheet contains a list of its rows and columns. These are a&ailable throuh the ,o0s and
7o+u#ns properties of the spreadsheet object and support the com.sun.star.table.Table7olumns
andQor com.sun.star.table.Table*ows ser&ices.
The followin e,ample 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# "o' $s 3b:e'(
"i# S&ee( $s 3b:e'(
"i# 8irs(,o0 $s 3b:e'(
"i# 8irs(7o+ $s 3b:e'(
"o' = T&is7o#ponen(
Chapter $2 4orms ,,
8irs(7o+ = S&ee(17o+u#ns(D)
8irs(,o0 = S&ee(1,o0s(D)
The column objects support the com.sun.star.table.Table7olumn ser&ice that has the followin
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 printin) creates a pae break before a column.
The width of a column is only optimi<ed when the 3p(i#+Ci-(& property is set to True. 6f the
width of an indi&idual cell is chaned) the width of the column that contains the cell is not chaned.
6n 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 followin
properties:
(eight (long)
heiht of the row in HGGths of a millimeter.
.ptimal(eight (Boolean)
sets the row to its optimum heiht.
IsVisible (Boolean)
displays the row.
IsStart.!Ne*2age (Boolean)
when printin) creates a pae break before the row.
6f the 3p(i#+Beig&( property of a row is set to the True) the row heiht chanes automatically
when the heiht of a cell in the row is chaned. /utomatic optimi<ation continues until the row is
assined an absolute heiht throuh the Beig&( property.
The followin e,ample acti&ates the automatic heiht optimi<ation for the first fi&e rows in the
sheet and makes the second column in&isible.
"i# "o' $s 3b:e'(
"i# S&ee( $s 3b:e'(
"i# ,o0 $s 3b:e'(
"i# 7o+ $s 3b:e'(
"i# 6 $s 6n(eger
"o' = T&is7o#ponen(
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 *ows and 7olumns lists can be accessed throuh an inde, in LibreOffice #asic. The
real /P6 call is : S&ee(1ge(7o+u#ns1ge(2.6n-ex(1)
$>> LibreOffice 3 Basic %"i&e
Note 0nlike in ;#/) the first column has the inde, G and not the inde, H.
"nsertin1 and /eletin1 .ows and !olu+ns
The ,o0s and 7o+u#ns objects of a sheet can access e,istin 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(17o+u#ns1inser(2.6n-ex(3< 1)
S&ee(17o+u#ns1re#o*e2.6n-ex(5< 1)
This e,ample uses the inser(2.6n-ex method to insert a new column into the fourth column
position in the sheet 8inde, ! @ numberin starts at G9. The second parameter specifies the number
of columns to be inserted 8in this e,ample: one9.
The re#o*e2.6n-ex method deletes the si,th column 8inde, (9. /ain) the second parameter
specifies the number of columns that you want to delete.
The methods for insertin and deletin rows use the ,o0s object function in the same way as the
methods shown for editin columns usin the 7o+u#ns object.
Cells and 1anges
/ spreadsheet consists of a two@dimensional list containin cells. 4ach cell is defined by its Y and
Y@position with respect to the top left cell which has the position 8G)G9.
Addressin1 and Editin1 "ndividual !ells
The followin e,ample creates an object that references the top left cell and inserts a te,t in the
cell:
"i# "o' $s 3b:e'(
"i# S&ee( $s 3b:e'(
"i# 7e++ $s 3b:e'(
"o' = T&is7o#ponen(
7e++ = S&ee(1ge(7e++2.Mosi(ion(D< D)
7e++1S(ring = @Tes(@
6n addition to numerical coordinates) each cell in a sheet has a name) for e,ample) the top left cell
8G)G9 of a spreadsheet is called $1. The letter $ stands for the column and the number H for the
row. 6t is important that the nameand positionof a cell are not confused because row countin for
names beins with H but the countin for position beins with G.
6f the position of the cell is fi,ed) it is more clear to use the followin code:
"i# "o' $s 3b:e'(
"i# S&ee( $s 3b:e'(
"i# 7e++ $s 3b:e'(
"o' = T&is7o#ponen(
7e++ = S&ee(1ge(7e++,nge2.5#e(@$1@)
The abo&e code also works with a named cell.
6n LibreOffice) a table cell can be empty or contain te,t) 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
Chapter $2 4orms $>$
for its entry. 1umbers can be inserted and called up with the 4+ue property) te,t 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(
7e++14+ue = 1DD
7e++ = S&ee(1ge(7e++2.Mosi(ion(D< 1)
7e++18or#u+ = @=$1@
The e,ample inserts one number) one te,t) and one formula in the fields /H to /!.
Note
The ;alue) Strin) and -ormula properties supersede the old Mu(7e++ method of
StarOffice ( for settin the &alues of a table cell.
LibreOffice treats cell content that is entered usin the S(ring property as te,t) e&en if the content
is a number. 1umbers are left@alined in the cell instead of riht@alined. You should also note the
difference between te,t 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(
7e++14+ue = 1DD
7e++1S(ring = 1DDD
7e++18or#u+ = @=$1+$2@
Asg2ox 7e++14+ue
/lthouh cell /H contains the &alue HGG and cell /" contains the &alue HGGG) the /H2/" formula
returns the &alue HGG. This is because the contents of cell /" were entered as a strin and not as
a number.
To check if the contents of a cell contains a number or a strin) 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(
7e++ = S&ee(1ge(7e++2.Mosi(ion(1<1)
7e++14+ue = 1DDD
Se+e'( 7se 7e++1T.pe
7se 'o#1sun1s(r1(b+e17e++7on(en(T.pe1EAMTZ
Asg2ox @7on(en(! E#p(.@
7se 'o#1sun1s(r1(b+e17e++7on(en(T.pe14$LNE
Asg2ox @7on(en(! 4+ue@
$>2 LibreOffice 3 Basic %"i&e
7se 'o#1sun1s(r1(b+e17e++7on(en(T.pe1TERT
Asg2ox @7on(en(! Tex(@
7se '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.7ell7ontentType enumeration
which identifies the contents type of a cell. The possible &alues are:
0"2)&
no &alue
VALU0
number
)08)
strins
-.$"ULA
formula
"nsertin18 /eletin18 !o,-in1 and Movin1 !ells
6n addition to directly modifyin cell content) LibreOffice 7alc also pro&ides an interface that allows
you to insert) delete) copy) or mere cells. The interface 8com.sun.star.sheet.Y*ane+o&ement9 is
a&ailable throuh the spreadsheet object and pro&ides four methods for modifyin 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(
7e++,nge$--ress1S&ee( = D
7e++,nge$--ress1S(r(7o+u#n = 1
7e++,nge$--ress1S(r(,o0 = 1
7e++,nge$--ress1En-7o+u#n = 2
7e++,nge$--ress1En-,o0 = 2
S&ee(1inser(7e++s(7e++,nge$--ress<
'o#1sun1s(r1s&ee(17e++6nser(Ao-e1"3C5)
This e,ample inserts a cells rane that is two rows by two columns in si<e into the second column
and row 8each bear the number H9 of the first sheet 8number G9 in the spreadsheet. /ny e,istin
&alues in the specified cell rane are mo&ed below the rane.
To define the cell rane that you want to insert) use the com.sun.star.table.7ell*ane/ddress
structure. The followin &alues are included in this structure:
Sheet (short)
number of the sheet 8numberin beins with G9.
StartColumn (long)
first column in the cell rane 8numberin beins with G9.
Start$o* (long)
first row in the cell rane 8numberin beins with G9.
0n%Column (long)
final column in the cell rane 8numberin beins with G9.
Chapter $2 4orms $>3
0n%$o* (long)
final row in the cell rane 8numberin beins with G9.
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.7ell6nsert+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 reconi<es the
followin &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 riht of the insert position are mo&ed to the riht.
$.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 riht.
The re#o*e,nge method is the counterpart to the inser(7e++s method. This method deletes
the rane that is defined in the 7e++,nge$--ress structure from the sheet.
"i# "o' $s 3b:e'(
"i# S&ee( $s 3b:e'(
"o' = T&is7o#ponen(
S&ee(1re#o*e,nge(7e++,nge$--ress<
'o#1sun1s(r1s&ee(17e++"e+e(eAo-e1NM)
This e,ample remo&es the 22!73 cell rane from the sheet and then shifts the underlyin cells up
by two rows. The type of remo&al is defined by one of the followin &alues from the
com.sun.star.sheet.7ellDelete+ode enumeration:
N.N0
the current &alues remain in their current position.
U2
the cells at and below the insert position are mo&ed upwards.
L0-)
the cells at and to the riht 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.
$>2 LibreOffice 3 Basic %"i&e
The R,ngeAo*e#en( interface pro&ides two additional methods for mo&in 8#o*e,nge9 or
copyin 8'op.,nge9 cell ranes. The followin e,ample mo&es the 22!73 rane so that the
rane starts at position $6:
"i# "o' $s 3b:e'(
"i# S&ee( $s 3b:e'(
"i# 7e++$--ress $s 5e0
'o#1sun1s(r1(b+e17e++$--ress
"o' = T&is7o#ponen(
7e++$--ress1S&ee( = D
7e++$--ress17o+u#n = D
7e++$--ress1,o0 = 5
S&ee(1#o*e,nge(7e++$--ress< 7e++,nge$--ress)
6n addition to the 7e++,nge$-ress structure) the #o*e,nge method e,pects a
com.sun.star.table.7ell/ddress structure to define the oriin of the mo&e>s taret reion. The
7e++$--ress method pro&ides the followin &alues:
Sheet (short)
number of the spreadsheet 8numberin beins with G9.
Column (long)
number of the addressed column 8numberin beins with G9.
$o* (long)
number of the addressed row 8numberin beins with G9.
The cell contents in the taret rane are always o&erwritten by the #o*e,nge method. 0nlike in
the 6nser(7e++s method ) a parameter for performin 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) e,cept that
'op.,nge inserts a copy of the cell rane instead of mo&in it.
Note
6n terms of their function) the LibreOffice #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 correspondin *ane object) in LibreOffice #asic they are applied to the associated
Sheet object.
For%atting #preadsheet *ocu%ents
/ spreadsheet document pro&ides properties and methods for formattin cells and paes.
!ell 3ro,erties
There are numerous options for formattin cells) such as specifyin the font type and si<e for te,t.
4ach cell supports the com.sun.star.style.7haracterProperties and
com.sun.star.style.PararaphProperties ser&ices) the main properties of which are described in
-e8t Doc"ments. Special cell formattin is handled by the com.sun.star.table.7ellProperties
ser&ice. The main properties of this ser&ice are described in the followin sections.
You can apply all of the named properties to indi&idual cells and to cell ranes.
Chapter $2 4orms $>3
Note
The 7e++Mroper(ies object in the LibreOffice /P6 is comparable with the 6nterior object
from ;#/ which also defines cell@specific properties.
Bac91round !olor and hadows
The com.sun.star.table.7ellProperties ser&ice pro&ides the followin properties for definin
backround colors and shadows:
CellBac'Color (Long)
backround color of the table cell
IsCellBac'groun%)ransparent (Boolean)
sets the backround color to transparent
Sha%o*-ormat (struct)
specifies the shadow for cells 8structure in accordance with
com.sun.star.table.Shadow-ormat9
The com.sun.star.table.Shadow-ormat structure and the detailed specifications for cell shadows
ha&e the followin structure:
Location (enum)
position of shadow 8&alue from the com.sun.star.table.ShadowLocation
structure9.
Sha%o*Wi%th (Short)
si<e of shadow in hundredths of a millimeter
Is)ransparent (Boolean)
sets the shadow to transparent
Color (Long)
color of shadow
The followin e,ample writes the number HGGG to the #" cell) chanes the backround color to red
usin the 7e++2'/7o+or property) and then creates a liht ray shadow for the cell that is
mo&ed H mm to the left and down.
"i# "o' $s 3b:e'(
"i# S&ee( $s 3b:e'(
"i# 7e++ $s 3b:e'(
"i# S&-o08or#( $s 5e0
'o#1sun1s(r1(b+e1S&-o08or#(
"o' = T&is7o#ponen(
7e++14+ue = 1DDD
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#(
:ustification
LibreOffice pro&ides &arious functions that allow you to chane the justification of a te,t in a table
cell.
$># LibreOffice 3 Basic %"i&e
The followin properties define the hori<ontal and &ertical justification of a te,t:
(ori/usti! (enum)
hori<ontal justification of the te,t 8&alue from
com.sun.star.table.7ell.ori=ustify9
Vert/usti! (enum)
&ertical justification of the te,t 8&alue from
com.sun.star.table.7ell;ert=ustify9
.rientation (enum)
orientation of te,t 8&alue in accordance with
com.sun.star.table.7ellOrientation9
Is)e1tWrappe% (Boolean)
permits automatic line breaks within the cell
$otateAngle (Long)
anle of rotation of te,t in hundredths of a deree
The followin e,ample shows how you can MstackM 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(
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"
#u+ber8 /ate and Text 2or+at
LibreOffice pro&ides a whole rane of predefined date and time formats. 4ach of these formats has
an internal number that is used to assin the format to cells usin the 5u#ber8or#( property.
LibreOffice pro&ides the ?uer.Ve. and --5e0 methods so that you can access e,istin number
formats as well as create your own number formats. The methods are accessed throuh the
followin object call:
5u#ber8or#(s = "o'15u#ber8or#(s
/ format is specified usin a format strin that is structured in a similar way to the format function
of LibreOffice #asic. .owe&er there is one major difference: whereas the command format e,pects
4nlish abbre&iations and decimal points or characters as thousands separators) the country@
specified abbre&iations must be used for the structure of a command format for the
5u#ber8or#(s object.
The followin e,ample 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'(
"i# 5u#ber8or#(s $s 3b:e'(
"i# 5u#ber8or#(S(ring $s S(ring
"i# 5u#ber8or#(6- $s Long
Chapter $2 4orms $>'
"i# Lo'+Se((ings $s 5e0 'o#1sun1s(r1+ng1Lo'+e
"o' = T&is7o#ponen(
7e++14+ue = 234DD13523565
Lo'+Se((ings1Lnguge = @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#(6-
7e++15u#ber8or#( = 5u#ber8or#(6-
The Format Cellsdialo in LibreOffice 7alc pro&ides an o&er&iew of the different formattin options
for cells.
3a1e 3ro,erties
Pae properties are the formattin options that position document content on a pae as well as
&isual elements that are repeated pae after pae. These include
Paper formats
Pae marins
.eaders and footers.
The procedure for definin pae formats differs from other forms of formattin. %hereas cell)
pararaph) and character elements can be formatted directly) pae formats can also be defined
and indirectly applied usin pae styles. -or e,ample) headers or footers are added to the pae
style.
The followin sections describe the main formattin options for spreadsheet paes. +any of the
styles that are described are also a&ailable for te,t documents. The pae properties that are &alid
for both types of documents are defined in the com.sun.star.style.PaeProperties ser&ice. The
pae properties that only apply to spreadsheet documents are defined in the
com.sun.star.sheet.TablePaeStyle ser&ice.
Note
The pae properties 8pae marins) borders) and so on9 for a +icrosoft Office document
are defined by means of a MgeSe(up object at the %orksheet object 84,cel9 or
Document object 8%ord9 le&el. 6n LibreOffice) these properties are defined usin a pae
style which in turn is linked to the associated document.
3a1e Bac91round
The com.sun.star.style.PaeProperties ser&ice defines the followin properties of a paes
backround:
Bac'Color (long)
color of backround
Bac'+raphicU$L (String)
0*L of the backround raphics that you want to use
$>+ LibreOffice 3 Basic %"i&e
Bac'+raphic-ilter (String)
name of the filter for interpretin the backround raphics
Bac'+raphicLocation (0num)
position of the backround raphics 8&alue accordin to enumeration9
Bac')ransparent (Boolean)
makes the backround transparent
3a1e 2or+at
The pae format is defined usin the followin properties of the com.sun.star.style.PaeProperties
ser&ice:
IsLan%scape (Boolean)
landscape format
Wi%th (long)
width of pae in hundredths of a millimeter
(eight (long)
heiht of pae in hundredths of a millimeter
2rinter2aper)ra (String)
name of the printer paper tray that you want to use
The followin e,ample sets the pae si<e of the MDefaultM pae style to the D61 /( landscape
format 8heiht H'.J cm) width "H cm9:
"i# "o' $s 3b:e'(
"i# S&ee( $s 3b:e'(
"i# S(.+e8#i+ies $s 3b:e'(
"i# "e)Mge $s 3b:e'(
"o' = T&is7o#ponen(
MgeS(.+es = S(.+e8#i+ies1ge(2.5#e(@MgeS(.+es@)
"e)Mge = MgeS(.+es1ge(2.5#e(@"e)u+(@)
"e)Mge16sLn-s'pe = True
"e)Mge1Ci-(& = 21DDD
"e)Mge1Beig&( = 148DD
3a1e Mar1in8 Border8 and hadow
The com.sun.star.style.PaeProperties ser&ice pro&ides the followin properties for adjustin pae
marins as well as borders and shadows:
Le!t"argin (long)
width of the left hand pae marin in hundredths of a millimeter
$ight"argin (long)
width of the riht hand pae marin in hundredths of a millimeter
)op"argin (long)
width of the top pae marin in hundredths of a millimeter
Bottom"argin (long)
width of the bottom pae marin in hundredths of a millimeter
Chapter $2 4orms $>,
Le!tBor%er (struct)
specifications for left@hand line of pae border
8com.sun.star.table.#orderLine structure9
$ightBor%er (struct)
specifications for riht@hand line of pae border
)opBor%er (struct)
specifications for top line of pae border 8com.sun.star.table.#orderLine
structure9
BottomBor%er (struct)
specifications for bottom line of pae border
Le!tBor%erDistance (long)
distance between left@hand pae border and pae content in
hundredths of a millimeter
$ightBor%erDistance (long)
distance between riht@hand pae border and pae content in
)opBor%erDistance (long)
distance between top pae border and pae content in hundredths of a
millimeter
BottomBor%erDistance (long)
distance between bottom pae border and pae content in hundredths
of a millimeter
Sha%o*-ormat (struct)
specifications for shadow of content area of pae
8com.sun.star.table.Shadow-ormat structure9
The followin e,ample sets the left and riht@hand borders of the MDefaultM pae style to H
centimeter.
"i# "o' $s 3b:e'(
"i# S&ee( $s 3b:e'(
"i# S(.+e8#i+ies $s 3b:e'(
"o' = T&is7o#ponen(
"e)Mge1Le)(Argin = 1DDD
"e)Mge1,ig&(Argin = 1DDD
;eaders and 2ooters
The headers and footers of a document form part of the pae properties and are defined usin the
com.sun.star.style.PaeProperties ser&ice. The properties for formattin headers are:
(ea%erIs.n (Boolean)
header is acti&ated
$$> LibreOffice 3 Basic %"i&e
(ea%erLe!t"argin (long)
distance between header and left@hand pae marin in hundredths of a
millimeter
(ea%er$ight"argin (long)
distance between header and riht@hand pae marin 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)
heiht of header in hundredths of a millimeter
(ea%erIsDnamic(eight (Boolean)
heiht of header is automatically adapted to content
(ea%erLe!tBor%er (struct)
details of the left@hand border of frame around header
(ea%er$ightBor%er (struct)
details of the riht@hand border of frame around header
(ea%er)opBor%er (struct)
details of the top line of the border around header
(ea%erBottomBor%er (struct)
details of the bottom line of the border around header
(ea%erLe!tBor%erDistance (long)
distance between left@hand border and content of header in hundredths
of a millimeter
(ea%er$ightBor%erDistance (long)
distance between riht@hand border and content of header in
(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 paes ha&e the same content 8refer to
Be-erTex( ) Be-erTex(Le)() and Be-erTex(,ig&( 9
(ea%erBac'Color (long)
backround color of header
(ea%erBac'+raphicU$L (String)
Chapter $2 4orms $$$
(ea%erBac'+raphic-ilter (String)
name of the filter for interpretin the backround raphics for the
header
(ea%erBac'+raphicLocation (0num)
position of the backround raphics for the header 8&alue accordin to
com.sun.star.style.$raphicLocation enumeration9
(ea%erBac')ransparent (Boolean)
shows the backround of the header as transparent
(ea%erSha%o*-ormat (struct)
details of shadow of header 8com.sun.star.table.Shadow-ormat
structure9
The properties for formattin footers are:
-ooterIs.n (Boolean)
footer is acti&ated
-ooterLe!t"argin (long)
distance between footer and left@hand pae marin in hundredths of a
millimeter
-ooter$ight"argin (long)
distance between footer and riht@hand pae marin in hundredths of a
millimeter
-ooterBo%Distance (long)
distance between footer and main body of document in hundredths of a
millimeter
-ooter(eight (long)
heiht of footer in hundredths of a millimeter
-ooterIsDnamic(eight (Boolean)
heiht of footer is adapted automatically to the content
-ooterLe!tBor%er (struct)
details of left@hand line of border around footer
-ooter$ightBor%er (struct)
details of riht@hand line of border around footer
-ooter)opBor%er (struct)
details of top line of border around footer
-ooterBottomBor%er (struct)
details of bottom line of border around footer
-ooterLe!tBor%erDistance (long)
distance between left@hand border and content of footer in hundredths
of a millimeter
-ooter$ightBor%erDistance (long)
distance between riht@hand border and content of footer in hundredths
of a millimeter
$$2 LibreOffice 3 Basic %"i&e
-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 paes ha&e the same content 8refer to
8oo(erTex() 8oo(erTex(Le)() and 8oo(erTex(,ig&( 9
-ooterBac'Color (long)
backround color of footer
-ooterBac'+raphicU$L (String)
-ooterBac'+raphic-ilter (String)
name of the filter for interpretin the backround raphics for the footer
-ooterBac'+raphicLocation (0num)
position of backround raphics for the footer 8&alue accordin to
com.sun.star.style.$raphicLocation enumeration9
-ooterBac')ransparent (Boolean)
shows the backround of the footer as transparent
-ooterSha%o*-ormat (struct)
details of shadow of footer 8com.sun.star.table.Shadow-ormat
structure9
!han1in1 the Text of ;eaders and 2ooters
The content of headers and footers in a spreadsheet is accessed throuh the followin properties:
Le!t2age(ea%erContent (.b6ect)
content of headers for e&en paes
8com.sun.star.sheet..eader-ooter7ontent ser&ice9
$ight2age(ea%erContent (.b6ect)
content of headers for odd paes
Le!t2age-ooterContent (.b6ect)
content of footers for e&en paes
$ight2age-ooterContent (.b6ect)
content of footers for odd paes
6f you do not need to distinuish between headers or footers for odd and e&en paes 8the
8oo(er6sS&re- property is 8+se9) then set the properties for headers and footers on odd
paes.
/ll the named objects return an object that supports the com.sun.star.sheet..eader-ooter7ontent
ser&ice. #y means of the 8non@enuine9 properties Le)(Tex() 7en(erTex() and ,ig&(Tex()
this ser&ice pro&ides three te,t elements for the headers and footers of LibreOffice 7alc.
The followin e,ample writes the M=ust a Test.M &alue in the left@hand te,t field of the header from
the MDefaultM template.
Chapter $2 4orms $$3
"i# "o' $s 3b:e'(
"i# S&ee( $s 3b:e'(
"i# S(.+e8#i+ies $s 3b:e'(
"i# BTex( $s 3b:e'(
"i# B7on(en( $s 3b:e'(
"o' = T&is7o#ponen(

"e)Mge1Be-er6s3n = True
B7on(en( = "e)Mge1,ig&(MgeBe-er7on(en(
BTex( = B7on(en(1Le)(Tex(
BTex(1S(ring = @Wus( Tes(1@
"e)Mge1,ig&(MgeBe-er7on(en( = B7on(en(
1ote the last line in the e,ample: Once the te,t is chaned) the Tex(7on(en( object must be
assined to the header aain so that the chane is effecti&e.
/nother mechanism for chanin the te,t of headers and footers is a&ailable for te,t documents
8LibreOffice %riter9 because these consist of a sinle block of te,t. The followin properties are
defined in the com.sun.star.style.PaeProperties ser&ice:
(ea%er)e1t (.b6ect)
te,t object with content of the header 8com.sun.star.te,t.YTe,t ser&ice9
(ea%er)e1tLe!t (.b6ect)
te,t object with content of headers on left@hand paes
8com.sun.star.te,t.YTe,t ser&ice9
(ea%er)e1t$ight (.b6ect)
te,t object with content of headers on riht@hand paes
-ooter)e1t (.b6ect)
te,t object with content of the footer 8com.sun.star.te,t.YTe,t ser&ice9
-ooter)e1tLe!t (.b6ect)
te,t object with content of footers on left@hand paes
-ooter)e1t$ight (.b6ect)
te,t object with content of footers on riht@hand paes
The followin e,ample creates a header in the MDefaultM pae style for te,t documents and adds
the te,t M=ust a TestM to the header.
"i# "o' $s 3b:e'(
"i# S&ee( $s 3b:e'(
"i# S(.+e8#i+ies $s 3b:e'(
"i# BTex( $s 3b:e'(
"o' = T&is7o#ponen(
"e)Mge1Be-er6s3n = True
BTex( = "e)Mge1Be-erTex(
$$2 LibreOffice 3 Basic %"i&e
BTex(1S(ring = @Wus( Tes(1@
6n this instance) access is pro&ided directly throuh the Be-erTex( property of the pae style
rather than the Be-er8oo(er7on(en( object.
!enterin1 <,readsheets Onl-=
The com.sun.star.sheet.TablePaeStyle ser&ice is only used in LibreOffice 7alc pae styles and
allows cell ranes that you want printed to be centered on the pae. This ser&ice pro&ides the
followin properties:
Center(ori4ontall (Boolean)
table content is centered hori<ontally
CenterVerticall (Boolean)
table content is centered &ertically
/efinition of Ele+ents to be 3rinted <,readsheets Onl-=
%hen you format sheets) you can define whether pae elements are &isible. -or this purpose) the
com.sun.star.sheet.TablePaeStyle ser&ice pro&ides the followin properties:
2rintAnnotations (Boolean)
prints cell comments
2rint+ri% (Boolean)
prints the cell ridlines
2rint(ea%ers (Boolean)
prints the row and column headins
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 e,tend across se&eral paes) they are first
printed in &ertically descendin order) and then down the riht@hand
side.
2rint-ormulas (Boolean)
prints the formulas instead of the calculated &alues
2rint9eroValues (Boolean)
prints the <ero &alues
+diting #preadsheet *ocu%ents
%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 ranes.
Chapter $2 4orms $$3
Cell 1anges
6n addition to an object for indi&idual cells 8com.sun.star.table.7ell ser&ice9) LibreOffice also
pro&ides objects that represent cell ranes. Such 7e++,nge objects are created usin 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 8:9 is used to specify a cell rane in a spreadsheet document. -or e,ample) /H:7H(
represents all the cells in rows H to H( in columns /) #) and 7.
6f the position of the cell rane is only known at runtime) use the followin 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 aruments of getCell7angeByPosition are the position of the upper left cell of the rane)
followed by the position of the bottom riht cell of the same rane.
The location of indi&idual cells in a cell rane can be determined usin the ge(7e++2.Mosi(ion
method) where the coordinates of the top left cell in the cell rane is 8G) G9. The followin e,ample
uses this method to create an object of cell 7!.
"i# "o' $s 3b:e'(
"i# S&ee( $s 3b:e'(
"i# 7e++,nge $s 3b:e'(
"i# 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)
2or+attin1 !ell .an1es
=ust like indi&idual cells) you can apply formattin to cell ranes usin the
com.sun.star.table.7ellProperties ser&ice. -or more information and e,amples of this ser&ice) see
4ormatting )prea&sheet Doc"ments.
!o+,utin1 With !ell .an1es
You can use the 'o#pu(e8un'(ion method to perform mathematical operations on cell ranes.
The 'o#pu(e8un'(ion e,pects 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.$eneral-unction enumeration. The followin &alues are a&ailable:
SU"
sum of all numerical &alues
C.UN)
total number of all &alues 8includin non@numerical &alues9
C.UN)NU"S
total number of all numerical &alues
$$# LibreOffice 3 Basic %"i&e
AV0$A+0
a&erae of all numerical &alues
"A8
larest 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 followin e,ample computes the a&erae &alue of the $1!73 rane and prints the result in a
messae bo,:
"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)
(arning
8un'(ions 4$,< 4$,M< ST"4E,M re(urn n in'orre'( *+ue 0&en pp+ie-
(o proper+. -e)ine- rnge1 See "ssue ))>)& 1
/eletin1 !ell !ontents
The '+er7on(en(s method simplifies the process of deletin cell contents and cell ranes in
that it deletes one specific type of content from a cell rane.
The followin e,ample remo&es all the strins and the direct formattin information from the
22!73 rane.
"i# "o' $s 3b:e'(
"i# S&ee( $s 3b:e'(
"i# 7e++,nge $s 3b:e'(
"i# 8+gs $s Long
"o' = T&is7o#ponen(
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,
Chapter $2 4orms $$'
7e++,nge1'+er7on(en(s(8+gs)
The flas specified in '+er7on(en(s come from the com.sun.star.sheet.7ell-las constants list.
This list pro&ides the followin 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+
strins
ANN.)A)I.N
comments that are linked to cells
-.$"ULA
formulas
(A$DA))$
direct formattin of cells
S)&L0S
indirect formattin
.B/0C)S
drawin objects that are connected to cells
0DI)A))$
character formattin that only applies to parts of the cells
You can also add the constants toether to delete different information usin a call from
'+er7on(en(s.
#earching and 1eplacing Cell Contents
Spreadsheet documents) like te,t documents) pro&ide a function for searchin and replacin.
The descriptor objects for searchin and replacin in spreadsheet documents are not created
directly throuh the document object) but rather throuh the S&ee(s list. The followin is an
e,ample of a search and replace process:
"i# "o' $s 3b:e'(
"i# S&ee( $s 3b:e'(
"i# ,ep+'e"es'rip(or $s 3b:e'(
"i# 6 $s 6n(eger
"o' = T&is7o#ponen(
,ep+'e"es'rip(or = S&ee(1're(e,ep+'e"es'rip(or()
,ep+'e"es'rip(or1Ser'&S(ring = @is@
,ep+'e"es'rip(or1,ep+'eS(ring = @0s@
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 e,ample uses the first pae of the document to create a ,ep+'e"es'rip(or and then
applies this to all paes in a loop.
$$+ LibreOffice 3 Basic %"i&e
#asic $uide
Chapter +
Drawings an& Presentations
*rawings and Presentations
$2> LibreOffice 3 Basic %"i&e
This chapter pro&ides an introduction to the macro@controlled creation and editin of drawins and
presentations.
The first section describes the structure of drawins) includin the basic elements that contain drawins. The
second section addresses more comple, editin functions) such as roupin) rotatin) and scalin objects.
The third section deals with presentations.
6nformation about creatin) openin) and sa&in drawins can be found in /or0ing /ith Doc"ments.
The #tructure of *rawings
Pages
Tip
/ Draw 8or 6mpress9 document is composed of paes) also called slides. %hat is written
here also applies to 6mpress documents.
LibreOffice does not limit the number of paes in a drawin document. You can desin each pae separately.
There is also no limit to the number of drawin elements that you can add to a pae.
The paes of a drawin document are a&ailable throuh the "r0Mges container. You can access
indi&idual paes either throuh their number or their name. 6f a document has one pae and this is called
Slide 1) then the followin e,amples are identical.
Example 1: access by means of the number (numbering begins with 0)
"i# "o' $s 3b:e'(
"i# Mge $s 3b:e'(
"o' = T&is7o#ponen(
Mge = "o'1"r0Mges(D)
Note
The e,pression "o'1"r0Mges(D) is a #asic simplification of the /P6 call :
"o'1ge("r0Mges1ge(2.6n-ex(D)
Example 2: access by means of the name
"i# "o' $s 3b:e'(
"i# Mge $s 3b:e'(
"o' = T&is7o#ponen(
Mge = "o'1"r0Mges1ge(2.5#e(@S+i-e 1@)
6n 4,ample H) the pae is accessed by its number 8countin beins at G9. 6n the second e,ample) the pae is
accessed by its name and the ge(2.5#e method.
3ro,erties of a ,a1e
The precedin call returns a pae object that supports the 'o#1sun1s(r1-r0ing1"r0Mge ser&ice.
The ser&ice reconi<es the followin properties:
Bor%erLe!t (Long)
left@hand border in hundredths of a millimeter
Bor%er$ight (Long)
riht@hand 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
Chapter $2 4orms $2$
Wi%th (Long)
pae width in hundredths of a millimeter
(eight (Long)
pae heiht in hundredths of a millimeter
Number (Short)
number of paes 8numberin beins at H9) read@only
.rientation (0num)
pae orientation 8in accordance with
'o#1sun1s(r1*ie01Mper3rien((ion enumeration9
6f these settins are chaned) then allof the paes in the document are affected.
The followin e,ample sets the pae si<e of a drawin document which has just been opened to "G , "G
centimeters with a pae marin of G.( centimeters:
"i# "o' $s 3b:e'(
"i# Mge $s 3b:e'(
"o' = T&is7o#ponen(
Mge12or-erLe)( = 5DD
Mge12or-er,ig&( = 5DD
Mge12or-erTop = 5DD
Mge12or-er2o((o# = 5DD
Mge1Ci-(& = 2DDDD
Mge1Beig&( = 2DDDD
.ena+in1 3a1es
(arning
6) ne0 pge is inser(e- in -r0ing -o'u#en( o) se*er+ pges<
++ subse?uen( pges 0&i'& &*e notbeen ren#e- 0i++ u(o#(i'++.
see (&eir -e)u+( n#e '&nge< e1g1 Slide 3 0i++ be '&nge- in(o Slide
4< e('1 T&is u(o#(i' ren#ing 0or/s +so in re*erse 0&en pge
is -e+e(e-1
T&e on+. 0. (o &*e )ixe- pge n#e is (o ren#e (&e pge< b.
(&e user in(er)'e or b. progr##ing1
/ pae pro&ides methods ge(5#e and se(5#e to read and modify its name. #asic can handle both
methods like a property 5#e. .ere we rename the first pae of the drawin document.
"i# "o' $s 3b:e'(
"i# Mge $s 3b:e'(

"o' = T&is7o#ponen(
Mge15#e = @8irs(@
!reatin1 and /eletin1 3a1es
The "r0Mges container of a -r0ing document is also used to create and delete indi&idual paes. The
followin e,ample uses the &s2.5#e method to check if a pae called MyPagee,ists. 6f it does) the
method determines a correspondin object reference by usin the ge(2.5#e method and then sa&es the
reference in a &ariable in Mge. 6f the correspondin pae does not e,ist) it is created and inserted in the
drawin document by the inser(5e02.6n-ex method. The arument of the method is the position)
counted from G) of the e8isting pae after which the new pae will be inserted. Then the new pae is
renamed.
"i# "o' $s 3b:e'(
"i# Mge $s 3b:e'(
"o' = T&is7o#ponen(
6) "o'1"r0pges1&s2.5#e(@A.Mge@) T&en
Mge = "o'1"r0pges1ge(2.5#e(@A.Mge@)
E+se
Mge = "o'1"r0pges1inser(5e02.6n-ex(2)
Mge15#e = @A.Mge@ % .ou s&ou+- +0.s ren#e ne0
pge
% A.Mge is (&e )our(& pge 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.Y1ame/ccess
interface.
The inser(5e02.6n-ex method is obtained from the com.sun.star.drawin.YDrawPaes interface. The
same interface pro&ides the method re#o*e to delete 8remo&e9 a pae:
"i# "o' $s 3b:e'(

"o' = T&is7o#ponen(
6) "o'1"r0pges1&s2.5#e(@A.Mge@) T&en
"o'1"r0pges1re#o*e(Mge)
En- 6)
/u,licatin1 a 3a1e
/ copy of a i&en pae is created) not from the DrawPaes container) but from the drawin document itself
with the method -up+i'(e. The copy is created at the ne,t position after the oriinal pae) with a default
name.
"i# "o' $s 3b:e'(
"i# Mge $s 3b:e'(< 7+one-Mge $s 3b:e'(

"o' = T&is7o#ponen(
7+one-Mge = "o'1-up+i'(e(Mge)
7+one-Mge15#e = @A.7op.@ % .ou s&ou+- +0.s ren#e
ne0 pge
Movin1 a 3a1e
The /P6 does not pro&ide a method to chane the position of a pae inside a drawin document.
+le%entary Properties of *rawing Ob5ects
Drawin objects include shapes 8rectanles) circles) and so on9) lines) and te,t objects. /ll of these share a
number of common features and support the 'o#1sun1s(r1-r0ing1S&pe ser&ice. This ser&ice
defines the SiXe and Mosi(ion properties of a drawin object.
LibreOffice #asic also offers se&eral other ser&ices throuh which you can modify such properties) as
formattin or apply fills. The formattin options that are a&ailable depend on the type of drawin object.
The followin e,ample creates and inserts a rectanle in a drawin document:
"i# "o' $s 3b:e'(
"i# Mge $s 3b:e'(
"i# Moin( $s 5e0 'o#1sun1s(r10(1Moin(
Chapter $2 4orms $23
"i# SiXe $s 5e0 'o#1sun1s(r10(1SiXe
"o' = T&is7o#ponen(
Moin(1x = 1DDD
Moin(1. = 1DDD
SiXe1Ci-(& = 1DDDD
SiXe1Beig&( = 1DDDD
,e'(ng+eS&pe =
"o'1're(e6ns(n'e(@'o#1sun1s(r1-r0ing1,e'(ng+eS&pe@)
,e'(ng+eS&pe1SiXe = SiXe
,e'(ng+eS&pe1Mosi(ion = Moin(
Mge1--(,e'(ng+eS&pe)
The Moin( and SiXe structures with the point of oriin 8left hand corner9 and the si<e of the drawin object
are then initiali<ed. The lenths are specified in hundredths of a millimeter.
The proram code then uses the "o'1're(e6ns(n'e call to create the rectanle drawin object as
specified by the com.sun.star.drawin.*ectanleShape ser&ice. /t the end) the drawin object is assined to
a pae usin a Mge1-- call.
2ill 3ro,erties
This section describes four ser&ices and in each instance the sample proram code uses a rectanle shape
element that combines se&eral types of formattin. -ill properties are combined in the
com.sun.star.drawin.-illProperties ser&ice.
LibreOffice reconi<es four main types of formattin for a fill area. The simplest &ariant is a sinle@color fill.
The options for definin color radients and hatches let you create other colors into play. The fourth &ariant is
the option of projectin e,istin raphics into the fill area.
The fill mode of a drawin object is defined usin the 8i++S(.+e property. The permissible &alues are
defined in com.sun.star.drawin.-illStyle.
in1le !olor 2ills
The main property for sinle@color 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 followin e,ample creates a rectanle shape and fills it with red 8*$# &alue "(() G) G9:
"i# "o' $s 3b:e'(
"i# Mge $s 3b:e'(
Moin(1x = 1DDD
Moin(1. = 1DDD
SiXe1Ci-(& = 1DDDD
SiXe1Beig&( = 1DDDD
"o' = T&is7o#ponen(
,e'(ng+eS&pe =
,e'(ng+eS&pe18i++S(.+e =
'o#1sun1s(r1-r0ing18i++S(.+e1S3L6"
,e'(ng+eS&pe18i++7o+or = ,G2(255<D<D)
!olor Gradient
6f you set the 8i++S(.+e property to G,$"6E5T) you can apply a color radient to any fill area of a
LibreOffice document.
6f you want to apply a predefined color radient) you can assin the associated name of the
8i++Trnspren'eGr-ien(5#e property. To define your own color radient) you need to complete a
com.sun.star.awt.$radient structure to assin the 8i++Gr-ien( property. This property pro&ides the
followin options:
Stle (0num)
type of radient) for e,ample) linear or radial 8default &alues in accordance with
com.sun.star.awt.$radientStyle9
StartColor (Long)
start color of color radient
0n%Color (Long)
end color of color radient
Angle (Short)
anle of color radient in tenths of a deree
8.!!set (Short)
Y@coordinate at which the color radient starts) specified in hundredths of a
millimeter
&.!!set (Short)
Y@coordinate at which the color radient beins) specified in hundredths of a
millimeter
StartIntensit (Short)
intensity of S(r(7o+or as a percentae 8in LibreOffice #asic) you can also
specify &alues hiher than HGG percent9
0n%Intensit (Short)
intensity of En-7o+or as a percentae 8in LibreOffice #asic) you can also
specify &alues hiher than HGG percent9
StepCount (Short)
number of color raduations which LibreOffice is to calculate for the radients
The followin e,ample demonstrates the use of color radients with the aid of the com.sun.star.awt.$radient
structure:
"i# "o' $s 3b:e'(
"i# Mge $s 3b:e'(
"i# Gr-ien( $s 5e0 'o#1sun1s(r10(1Gr-ien(
Moin(1x = 1DDD
Moin(1. = 1DDD
SiXe1Ci-(& = 1DDDD
SiXe1Beig&( = 1DDDD
"o' = T&is7o#ponen(
,e'(ng+eS&pe =
Gr-ien(1S(.+e = 'o#1sun1s(r10(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
'o#1sun1s(r1-r0ing18i++S(.+e1G,$"6E5T
,e'(ng+eS&pe18i++Gr-ien( = Gr-ien(
This e,ample creates a linear color radient 8S(.+e = L65E$,9. The radient starts with red
8S(r(7o+or9 in the top left corner) and e,tends at a '( deree anle 8$ng+e9 to reen 8En-7o+or9 in the
bottom riht corner. The color intensity of the start and end colors is H(G percent 8S(r(6n(ensi(. and
En-6n(ensi(.9 which results in the colors seemin brihter than the &alues specified in the S(r(7o+or
and En-7o+or properties. The color radient is depicted usin a hundred raduated indi&idual colors
8S(ep7oun(9.
;atches
To create a hatch fill) the 8i++S(.+e property must be set to B$T7B. The proram code for definin the
hatch is &ery similar to the code for color radients. /ain an au,iliary structure) in this case
com.sun.star.drawin..atch) is used to define the appearance of hatches. The structure for hatches has the
followin properties:
Stle (0num)
type of hatch: simple) s5uared) or s5uared with diaonals 8default &alues in
accordance with 'o#1sun1s(r10(1B('&S(.+e9
Color (Long)
color of lines
Distance (Long)
distance between lines in hundredths of a millimeter
Angle (Short)
anle of hatch in tenths of a deree
The followin e,ample demonstrates the use of a hatch structure:
"i# "o' $s 3b:e'(
"i# Mge $s 3b:e'(
"i# B('& $s 5e0 'o#1sun1s(r1-r0ing1B('&
$2# LibreOffice 3 Basic %"i&e
Moin(1x = 1DDD
Moin(1. = 1DDD
SiXe1Ci-(& = 1DDDD
SiXe1Beig&( = 1DDDD
"o' = T&is7o#ponen(
,e'(ng+eS&pe =
'o#1sun1s(r1-r0ing18i++S(.+e1B$T7B
B('&1S(.+e = 'o#1sun1s(r1-r0ing1B('&S(.+e1S65GLE
B('&17o+or = ,G2(64<64<64)
B('&1"is(n'e = 2D
B('&1$ng+e = 45D
,e'(ng+eS&pe18i++B('& = B('&
This code creates a simple hatch structure 8B('&S(.+e = S65GLE9 whose lines are rotated '( derees
8$ng+e9. The lines are dark ray 87o+or9 and are spaced is G." millimeters 8"is(n'e9 apart.
Bit+a,s
To use bitmap projection as a fill) you must set the 8i++S(.+e property to 26TA$M. 6f the bitmap is already
a&ailable in LibreOffice) you just need to specify its name in the 8i++2i(Ap5#e property and its display
style 8simple) tiled) or elonated9 in the 8i++2i(#pAo-e property 8default &alues in accordance with
com.sun.star.drawin.#itmap+ode9.
6f you want to use an e,ternal bitmap file) you can specify its 0*L in the 8i++2i(#pN,L property.
The followin e,ample creates a rectanle and tiles the Sky bitmap that is a&ailable in LibreOffice to fill the
area of the rectanle:
"i# "o' $s 3b:e'(
"i# Mge $s 3b:e'(
Moin(1x = 1DDD
Moin(1. = 1DDD
SiXe1Ci-(& = 1DDDD
SiXe1Beig&( = 1DDDD
"o' = T&is7o#ponen(
,e'(ng+eS&pe =
'o#1sun1s(r1-r0ing18i++S(.+e126TA$M
Chapter $2 4orms $2'
,e'(ng+eS&pe18i++2i(#p5#e = @S/.@
,e'(ng+eS&pe18i++2i(#pAo-e =
'o#1sun1s(r1-r0ing12i(#pAo-e1,EME$T
Trans,arenc-
You can adjust the transparency of any fill that you apply. The simplest way to chane the transparency of a
drawin element is to use the 8i++Trnspren'e property.
The followin e,ample creates a red rectanle with a transparency of (G percent.
"i# "o' $s 3b:e'(
"i# Mge $s 3b:e'(
Moin(1x = 1DDD
Moin(1. = 1DDD
SiXe1Ci-(& = 1DDDD
SiXe1Beig&( = 1DDDD
"o' = T&is7o#ponen(
,e'(ng+eS&pe =
,e'(ng+eS&pe18i++Trnspren'e = 5D
,e'(ng+eS&pe18i++7o+or = ,G2(255<D<D)

To make the fill transparent) set the 8i++Trnspren'e property to HGG.
6n addition to the 8i++Trnspren'e property) the com.sun.star.drawin.-illProperties ser&ice also
pro&ides the 8i++Trnspren'eGr-ien( property. This is used to define a radient that specifies the
transparency of a fill area.
Line 3ro,erties
/ll drawin objects that can ha&e a border line support the com.sun.star.drawin.LineStyle ser&ice. Some of
the properties that this ser&ice pro&ides are:
LineStle (0num)
line type 8default &alues in accordance with com.sun.star.drawin.LineStyle9
LineColor (Long)
line color
Line)ransparence (Short)
line transparency
LineWi%th (Long)
line thickness in hundredths of a millimeter
$2+ LibreOffice 3 Basic %"i&e
Line/oint (0num)
transitions to connection points 8default &alues in accordance with
com.sun.star.drawin.Line=oint9
The followin e,ample creates a rectanle with a solid border 8LineS(.+e = S3L6"9 that is ( millimeters
thick 8LineCi-(&9 and (G percent transparent. The riht and left@hand edes of the line e,tend to their
points of intersect with each other 8LineWoin( = A6TE,9 to form a riht@anle.
"i# "o' $s 3b:e'(
"i# Mge $s 3b:e'(
Moin(1x = 1DDD
Moin(1. = 1DDD
SiXe1Ci-(& = 1DDDD
SiXe1Beig&( = 1DDDD
"o' = T&is7o#ponen(
,e'(ng+eS&pe =
,e'(ng+eS&pe1Line7o+or = ,G2(128<128<128)
,e'(ng+eS&pe1LineTrnspren'e = 5D
,e'(ng+eS&pe1LineCi-(& = 5DD
,e'(ng+eS&pe1LineWoin( =
'o#1sun1s(r1-r0ing1LineWoin(1A6TE,
,e'(ng+eS&pe1LineS(.+e =
'o#1sun1s(r1-r0ing1LineS(.+e1S3L6"
6n addition to the listed properties) the com.sun.star.drawin.LineStyle ser&ice pro&ides options for drawin
dotted and dashed lines. -or more information) see the LibreOffice /P6 reference.
Text 3ro,erties </rawin1 Ob?ects=
The com.sun.star.style.7haracterProperties and com.sun.star.style.PararaphProperties
ser&ices can format te,t in drawin objects. These ser&ices relate to indi&idual characters and pararaphs
and are described in detail in -e8t Doc"ments.
The followin e,ample inserts te,t in a rectanle and formats the font com.sun.star.style.7haracterProperties
ser&ice.
"i# "o' $s 3b:e'(
"i# Mge $s 3b:e'(
Moin(1x = 1DDD
Moin(1. = 1DDD
SiXe1Ci-(& = 1DDDD
SiXe1Beig&( = 1DDDD
"o' = T&is7o#ponen(
Chapter $2 4orms $2,
,e'(ng+eS&pe =
,e'(ng+eS&pe1S(ring = @T&is is (es(@
,e'(ng+eS&pe17&rCeig&( =
,e'(ng+eS&pe17&r8on(5#e = @$ri+@
This code uses the S(ring@property of the rectanle to insert the te,t and the 7&rCeig&( and
7&r8on(5#e properties from the com.sun.star.style.7haracterProperties ser&ice to format the te,t font.
The te,t can only be inserted after the drawin object has been added to the drawin pae. You can also use
the com.sun.star.drawin.Te,t ser&ice to position and format te,t in drawin object. The followin are some
of the important properties of this ser&ice:
)e1tAuto+ro*(eight (Boolean)
adapts the heiht of the drawin element to the te,t it contains
)e1tAuto+ro*Wi%th (Boolean)
adapts the width of the drawin element to the te,t it contains
)e1t(ori4ontalA%6ust (0num)
hori<ontal position of te,t within the drawin element 8default &alues in
accordance with com.sun.star.drawin.Te,t.ori<ontal/djust9
)e1tVerticalA%6ust (0num)
&ertical position of te,t within the drawin element 8default &alues in accordance
with com.sun.star.drawin.Te,t;ertical/djust9
)e1tLe!tDistance (Long)
left@hand distance between drawin element and te,t in hundredths of a
millimeter
)e1t$ightDistance (Long)
riht@hand distance between drawin element and te,t in hundredths of a
millimeter
)e1tUpperDistance (Long)
upper distance between drawin element and te,t in hundredths of a millimeter
)e1tLo*erDistance (Long)
lower distance between drawin element and te,t in hundredths of a millimeter
The followin e,ample demonstrates use of the named properties.
"i# "o' $s 3b:e'(
"i# Mge $s 3b:e'(
Moin(1x = 1DDD
Moin(1. = 1DDD
SiXe1Ci-(& = 1DDDD
SiXe1Beig&( = 1DDDD
"o' = T&is7o#ponen(
,e'(ng+eS&pe =
,e'(ng+eS&pe1S(ring = @T&is is (es(@ % A. on+. (/e
p+'e )(er Mge1--I
,e'(ng+eS&pe1Tex(4er(i'+$-:us( =
'o#1sun1s(r1-r0ing1Tex(4er(i'+$-:us(1T3M
,e'(ng+eS&pe1Tex(BoriXon(+$-:us( =
'o#1sun1s(r1-r0ing1Tex(BoriXon(+$-:us(1LE8T
,e'(ng+eS&pe1Tex(Le)("is(n'e = 3DD
,e'(ng+eS&pe1Tex(,ig&("is(n'e = 3DD
,e'(ng+eS&pe1Tex(Npper"is(n'e = 3DD
,e'(ng+eS&pe1Tex(Lo0er"is(n'e = 3DD
This code inserts a drawin element in a pae and then adds te,t to the top left corner of the drawin object
usin the Tex(4er(i'+$-:us( and Tex(BoriXon(+$-:us( properties. The minimum distance
between the te,t ede of the drawin object is set to three millimeters.
hadow 3ro,erties
You can add a shadow to most drawin objects with the com.sun.star.drawin.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 drawin object in hundredths of a
millimeter
Sha%o*&Distance (Long)
hori<ontal distance of the shadow from the drawin object in hundredths of a
millimeter
The followin e,ample creates a rectanle with a shadow that is &ertically and hori<ontally offset from the
rectanle by " millimeters. The shadow is rendered in dark ray with (G percent transparency.
"i# "o' $s 3b:e'(
"i# Mge $s 3b:e'(
Moin(1x = 1DDD
Moin(1. = 1DDD
SiXe1Ci-(& = 1DDDD
SiXe1Beig&( = 1DDDD
"o' = T&is7o#ponen(
,e'(ng+eS&pe =
,e'(ng+eS&pe1S&-o0 = True
,e'(ng+eS&pe1S&-o07o+or = ,G2(1L2<1L2<1L2)
,e'(ng+eS&pe1S&-o0Trnspren'e = 5D
,e'(ng+eS&pe1S&-o0R"is(n'e = 2DD
,e'(ng+eS&pe1S&-o0Z"is(n'e = 2DD
"n Overview of )arious *rawing Ob5ects
.ectan1le ha,es
*ectanle shape objects 8com.sun.star.drawin.*ectanleShape9 support the followin ser&ices for
formattin objects:
-ill properties
com.sun.star.drawin.-illProperties
Line properties
com.sun.star.drawin.LineProperties
)e1t properties
com.sun.star.drawin.Te,t 8with com.sun.star.style.7haracterProperties and
com.sun.star.style.PararaphProperties9
Sha%o* properties
com.sun.star.drawin.ShadowProperties
Corner$a%ius (Long)
radius for roundin corners in hundredths of a millimeter
!ircles and Elli,ses
The Ser&ice com.sun.star.drawin.4llipseShape ser&ice is responsible for circles and ellipses and supports
the followin ser&ices:
-ill properties
Line properties
)e1t properties
Sha%o* properties
6n addition to these ser&ices) circles and ellipses also pro&ide these properties:
Circle5in% (0num)
type of circle or ellipse 8default &alues in accordance with
com.sun.star.drawin.7ircleOind9
CircleStartAngle (Long)
start anle in tenths of a deree 8only for circle or ellipse sements9
Circle0n%Angle (Long)
end anle in tenths of a deree 8only for circle or ellipse sements9
The 7ir'+eVin- property determines if an object is a complete circle) a circular slice) or a section of a
circle. The followin &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 8partial circle whose interfaces are linked directly to one another9
com.sun.star.%ra*ing.Circle5in%.S0C)I.N
circle slice
com.sun.star.%ra*ing.Circle5in%.A$C
anle 8not includin circle line9
The followin e,ample creates a circular slice with a IG deree anle 8produced from difference between
start anle of "G derees and end anle of KG derees9
"i# "o' $s 3b:e'(
"i# Mge $s 3b:e'(
"i# E++ipseS&pe $s 3b:e'(
Moin(1x = 1DDD
Moin(1. = 1DDD
SiXe1Ci-(& = 1DDDD
SiXe1Beig&( = 1DDDD
"o' = T&is7o#ponen(
E++ipseS&pe =
"o'1're(e6ns(n'e(@'o#1sun1s(r1-r0ing1E++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-r0ing17ir'+eVin-1SE7T635
Mge1--(E++ipseS&pe)
Lines
LibreOffice pro&ides the com.sun.star.drawin.LineShape ser&ice for line objects. Line objects support all of
the eneral formattin ser&ices with the e,ception of areas. The followin are all of the properties that are
associated with the LineS&pe ser&ice:
Line properties
)e1t properties
Sha%o* properties
The followin e,ample creates and formats a line with the help of the named properties. The oriin 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# "o' $s 3b:e'(
"i# Mge $s 3b:e'(
"i# LineS&pe $s 3b:e'(
Moin(1x = 1DDD
Moin(1. = 1DDD
SiXe1Ci-(& = 1DDDD
SiXe1Beig&( = 1DDDD
"o' = T&is7o#ponen(

LineS&pe =
"o'1're(e6ns(n'e(@'o#1sun1s(r1-r0ing1LineS&pe@)
LineS&pe1SiXe = SiXe
LineS&pe1Mosi(ion = Moin(
Mge1--(LineS&pe)
3ol-,ol-1on ha,es
LibreOffice also supports comple, polyonal shapes throuh the com.sun.star.drawin.PolyPolyonShape
ser&ice. Strictly speakin) a PolyPolyon is not a simple polyon but a multiple polyon. Se&eral independent
lists containin corner points can therefore be specified and combined to form a complete object.
/s with rectanle shapes) all the formattin properties of drawin objects are also pro&ided for polypolyons:
-ill properties
Line properties
)e1t properties
Sha%o* properties
The Mo+.Mo+.gonS&pe ser&ice also has a property that lets you define the coordinates of a polyon:
Mo+.Mo+.gon ($rr.) ? field containin the coordinates of the polyon 8double array with points of the
com.sun.star.awt.Point type9
The followin e,ample shows how you can define a trianle with the Mo+.Mo+.gonS&pe ser&ice.
"i# "o' $s 3b:e'(
"i# Mge $s 3b:e'(
"i# Mo+.Mo+.gonS&pe $s 3b:e'(
"i# Mo+.Mo+.gon $s 4rin(
"i# 7oor-in(es(2) $s 5e0 'o#1sun1s(r10(1Moin(
"o' = T&is7o#ponen(
Mo+.Mo+.gonS&pe =
"o'1're(e6ns(n'e(@'o#1sun1s(r1-r0ing1Mo+.Mo+.gonS&pe@
)
Mge1--(Mo+.Mo+.gonS&pe) % Mge1-- #us( (/e p+'e
be)ore (&e 'oor-in(es re se(
7oor-in(es(D)1x = 1DDD
7oor-in(es(1)1x = 75DD
7oor-in(es(2)1x = 1DDDD
7oor-in(es(D)1. = 1DDD
7oor-in(es(1)1. = 75DD
7oor-in(es(2)1. = 5DDD
Mo+.Mo+.gonS&pe1Mo+.Mo+.gon = $rr.(7oor-in(es())
Since the points of a polyon are defined as absolute &alues) you do not need to specify the si<e or the start
position of a polyon. 6nstead) you need to create an array of the points) packae this array in a second array
8usin the $rr.(7oor-in(es()) call9) and then assin this array to the polyon. #efore the
correspondin call can be made) the polyon must be inserted into the document.
The double array in the definition allows you to create comple, shapes by merin se&eral polyons. -or
e,ample) you can create a rectanle and then insert another rectanle inside it to create a hole in the oriinal
rectanle:
"i# "o' $s 3b:e'(
"i# Mge $s 3b:e'(
"i# Mo+.Mo+.gonS&pe $s 3b:e'(
"i# Mo+.Mo+.gon $s 4rin(
"i# S?ure1(3) $s 5e0 'o#1sun1s(r10(1Moin(
"o' = T&is7o#ponen(
Mo+.Mo+.gonS&pe =
"o'1're(e6ns(n'e(@'o#1sun1s(r1-r0ing1Mo+.Mo+.gonS&pe@
)
Mge1--(Mo+.Mo+.gonS&pe) % Mge1-- #us( (/e p+'e
be)ore (&e 'oor-in(es re se(
S?ure1(D)1x = 5DDD
S?ure1(1)1x = 1DDDD
S?ure1(2)1x = 1DDDD
S?ure1(3)1x = 5DDD
S?ure1(D)1. = 5DDD
S?ure1(1)1. = 5DDD
S?ure1(2)1. = 1DDDD
S?ure1(3)1. = 1DDDD
S?ure2(D)1x = 65DD
S?ure2(1)1x = 85DD
S?ure2(2)1x = 85DD
S?ure2(3)1x = 65DD
S?ure2(D)1. = 65DD
S?ure2(1)1. = 65DD
S?ure2(2)1. = 85DD
S?ure2(3)1. = 85DD
S?ure3(D)1x = 65DD
S?ure3(1)1x = 85DD
S?ure3(2)1x = 85DD
S?ure3(3)1x = 65DD
S?ure3(D)1. = LDDD
S?ure3(1)1. = LDDD
S?ure3(2)1. = L5DD
S?ure3(3)1. = L5DD
Mo+.Mo+.gonS&pe1Mo+.Mo+.gon = $rr.(S?ure1()< S?ure2()<
S?ure3())
%ith respect as to which areas are filled and which areas are holes) LibreOffice applies a simple rule: the
ede of the outer shape is always the outer border of the polypolyon. The ne,t line inwards is the inner
border of the shape and marks the transition to the first hole. 6f there is another line inwards) it marks the
transition to a filled area.
Gra,hics
The last of the drawin elements presented here are raphic objects that are based on the
com.sun.star.drawin.$raphicObjectShape ser&ice. These can be used with any raphic within LibreOffice
whose appearance can be adapted usin a whole rane of properties.
$raphic objects support two of the eneral formattin properties:
)e1t properties
Sha%o* properties
/dditional properties that are supported by raphic objects are:
+raphicU$L (String)
0*L of the raphic
A%6ustLuminance (Short)
luminance of the colors) as a percentae 8neati&e &alues are also permitted9
A%6ustContrast (Short)
contrast as a percentae 8neati&e &alues are also permitted9
A%6ust$e% (Short)
red &alue as a percentae 8neati&e &alues are also permitted9
A%6ust+reen (Short)
reen &alue as a percentae 8neati&e &alues are also permitted9
A%6ustBlue (Short)
blue &alue as a percentae 8neati&e &alues are also permitted9
+amma (Short)
amma &alue of a raphic
)ransparenc (Short)
transparency of a raphic as a percentae
+raphicColor"o%e (enum)
color mode) for e,ample) standard) ray staes) black and white 8default &alue in
accordance with com.sun.star.drawin.7olor+ode9
The followin e,ample shows how to insert a pae into a raphics object.
"i# "o' $s 3b:e'(
"i# Mge $s 3b:e'(
"i# Grp&i'3b:e'(S&pe $s 3b:e'(
Moin(1x = 1DDD % spe'i)i'(ions< insigni)i'n(
be'use +((er
'oor-in(es re bin-ing
Moin(1. = 1DDD
SiXe1Ci-(& = 1DDDD
SiXe1Beig&( = 1DDDD
"o' = T&is7o#ponen(
Grp&i'3b:e'(S&pe =
"o'1're(e6ns(n'e(@'o#1sun1s(r1-r0ing1Grp&i'3b:e'(S&p
e@)
Grp&i'3b:e'(S&pe1SiXe = SiXe
Grp&i'3b:e'(S&pe1Mosi(ion = Moin(

Grp&i'3b:e'(S&pe1Grp&i'N,L = @)i+e!OOO'!O(es(1:pg@
Grp&i'3b:e'(S&pe1$-:us(2+ue = H5D
Grp&i'3b:e'(S&pe1$-:us(Green = 5
Grp&i'3b:e'(S&pe1$-:us(2+ue = 1D
Grp&i'3b:e'(S&pe1$-:us(7on(rs( = 2D
Grp&i'3b:e'(S&pe1$-:us(Lu#inn'e = 5D
Grp&i'3b:e'(S&pe1Trnspren'. = 4D
Grp&i'3b:e'(S&pe1Grp&i'7o+orAo-e =
'o#1sun1s(r1-r0ing17o+orAo-e1ST$5"$,"
Mge1--(Grp&i'3b:e'(S&pe)
This code inserts the (es(1:pg raphic and adapts its appearance usin the $-:us( properties. 6n this
e,ample) the raphics are depicted as 'G percent transparent with no other color con&ersions do not take
place 8Grp&i'7o+orAo-e = ST$5"$,"9.
+diting *rawing Ob5ects
&rouping Ob5ects
6n many situations) it is useful to roup se&eral indi&idual drawin objects toether so that they beha&e as a
sinle lare object.
The followin e,ample combines two drawin objects:
"i# "o' $s 3b:e'(
"i# Mge $s 3b:e'(
"i# S?ure $s 3b:e'(
"i# 7ir'+e $s 3b:e'(
"i# S&pes $s 3b:e'(
"i# Group $s 3b:e'(
"i# 5e0Mos $s 5e0 'o#1sun1s(r10(1Moin(
"i# Beig&( $s Long
"i# Ci-(& $s Long

"o' = T&is7o#ponen(
Moin(1x = 3DDD
Moin(1. = 3DDD
SiXe1Ci-(& = 3DDD
SiXe1Beig&( = 3DDD
% 're(e s?ure -r0ing e+e#en(
S?ure =
S?ure1SiXe = SiXe
S?ure1Mosi(ion = Moin(
S?ure18i++7o+or = ,G2(255<128<128)
Mge1--(S?ure)
% 're(e 'ir'+e -r0ing e+e#en(
7ir'+e =
"o'1're(e6ns(n'e(@'o#1sun1s(r1-r0ing1E++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)
Mge1--(7ir'+e)
% 'o#bine s?ure n- 'ir'+e -r0ing e+e#en(s
S&pes =
're(eNnoSer*i'e(@'o#1sun1s(r1-r0ing1S&pe7o++e'(ion@)
S&pes1--(S?ure)
S&pes1--(7ir'+e)
Group = Mge1group(S&pes)
% 'en(re 'o#bine- -r0ing e+e#en(s
Beig&( = Mge1Beig&(
Ci-(& = Mge1Ci-(&
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 rectanle and a circle and inserts them into a pae. 6t then creates an object that
supports the com.sun.star.drawin.Shape7ollection ser&ice and uses the $-- method to add the rectanle
and the circle to this object. The S&pe7o++e'(ion is added to the pae usin the Group method and
returns the actual Group object that can be edited like an indi&idual S&pe.
6f you want to format the indi&idual objects of a roup) apply the formattin before you add them to the roup.
You cannot modify the objects once they are in the roup.
1otating and #hearing *rawing Ob5ects
/ll of the drawin objects that are described in the pre&ious sections can also be rotated and sheared usin
the com.sun.star.drawin.*otationDescriptor ser&ice.
The ser&ice pro&ides the followin properties:
$otateAngle (Long)
rotary anle in hundredths of a deree
ShearAngle (Long)
shear anle in hundredths of a deree
The followin e,ample creates a rectanle and rotates it by !G derees usin the ,o((e$ng+e property:
"i# "o' $s 3b:e'(
"i# Mge $s 3b:e'(
Moin(1x = 1DDD
Moin(1. = 1DDD
SiXe1Ci-(& = 1DDDD
SiXe1Beig&( = 1DDDD
"o' = T&is7o#ponen(
,e'(ng+eS&pe =
,e'(ng+eS&pe1,o((e$ng+e = 3DDD
The ne,t e,ample creates the same rectanle as in the pre&ious e,ample) but instead shears it throuh !G
derees usin the S&er$ng+e property.
"i# "o' $s 3b:e'(
"i# Mge $s 3b:e'(
Moin(1x = 1DDD
Moin(1. = 1DDD
SiXe1Ci-(& = 1DDDD
SiXe1Beig&( = 1DDDD
"o' = T&is7o#ponen(
,e'(ng+eS&pe =
,e'(ng+eS&pe1S&er$ng+e = 3DDD
#earching and 1eplacing
/s in te,t documents) drawin documents pro&ide a function for searchin and replace. This function is
similar to the one that is used in te,t documents as described in -e8t Doc"ments. .owe&er) in drawin
documents the descriptor objects for searchin and replacin are not created directly throuh the document
object) but rather throuh the associated character le&el. The followin e,ample outlines the replacement
process within a drawin:
"i# "o' $s 3b:e'(
"i# Mge $s 3b:e'(
"i# ,ep+'e"es'rip(or $s 3b:e'(
"i# 6 $s 6n(eger
"o' = T&is7o#ponen(
,ep+'e"es'rip(or = Mge1're(e,ep+'e"es'rip(or()
,ep+'e"es'rip(or1Ser'&S(ring = @is@
,ep+'e"es'rip(or1,ep+'eS(ring = @0s@
8or 6 = D (o "o'1"r0Mges17oun( H 1
Mge = "o'1"r0Mges(6)
Mge1,ep+'e$++(,ep+'e"es'rip(or)
5ex( 6
This code uses the first pae of the document to create a ,ep+'e"es'rip(or and then applies this
descriptor in a loop to all of the paes in the drawin document.
Presentations
LibreOffice presentations are based on drawin documents. 4ach pae in the presentation is a slide. You
can access slides in the same way as a standard drawin is accessed throuh the "r0Mges 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.drawin.DrawinDocument ser&ice.
(orking (ith Presentations
6n addition to the drawin 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. -or e,ample) 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 e,ample 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
e,ample and run the screen presentation.
The followin methods are pro&ided as presentation objects:
start
starts the presentation
en%
ends the presentation
rehearse)imings
starts the presentation from the beinnin and establishes its runtime
The followin 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*as.n)op (Boolean)
always displays the presentation window as the first window on the screen
IsAutomatic (Boolean)
automatically runs throuh the presentation
Is0n%less (Boolean)
restarts the presentation from the beinnin once it ends
Is-ullScreen (Boolean)
automatically starts the presentation in full screen mode
Is"ouseVisible (Boolean)
displays the mouse durin the presentation
2ause (long)
the amount of time that a blank screen is displayed at the end of the presentation
StartWithNa3igator (Boolean)
displays the na&iator window when the presentation starts
Use2n (Boolean)
displays the pointer durin the presentation
#asic $uide
Chapter ,
Charts :Diagrams;
Charts 6*iagra%s7
LibreOffice can display data as a chart) which creates raphical representations of numerical data in the form
of bars) pie charts) lines or other elements. Data can either be displayed as "D or !D raphics) and the
appearance of the chart elements can be indi&idually adapted in a way similar to the process used for
drawin elements.
7harts are not treated as independent documents in LibreOffice) but as objects that are embedded in an
e,istin document.
/ chart may contain its own data or may display data from the container document. -or e,ample charts in
spreadsheets can display data obtained from the cell ranes and charts in te,t documents can display data
obtained from writer tables.
'sing Charts in #preadsheets
7harts within spreadsheets can display the data from an assined cell rane within the spreadsheet. /ny
modifications made to the data within the spreadsheet will also be reflected in the assined chart. The
followin e,ample shows how to create a chart assined to some cell ranes within a spreadsheet
document:
"i# "o' $s 3b:e'(
"i# 7&r(s $s 3b:e'(
"i# 7&r( s 3b:e'(
"i# ,e'( $s 5e0 'o#1sun1s(r10(1,e'(ng+e
"i# ,nge$--ress(D) $s 5e0
"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)
/lthouh the code used in the e,ample may appear to be comple,) the central processes are limited to three
lines. The first central line creates the "o' document &ariable) which references the current spreadsheet
document 8"o' line N S(r"es/(op17urren(7o#ponen(9. The code used in the e,ample then creates a
list containin all charts of the first spreadsheet 87&r(s line N "o'1S&ee(s(D)17&r(s9. -inally) in the
last line) a new chart is added to this list usin the --5e02.5#e method. This new chart is then &isible to
the user. The &ariable ,nge$--ress determines the assined cell rane whose data will be displayed
within the chart. The &ariable ,e'( determines the position and si<e of the chart within the first sheet in the
spreadsheet document.
The pre&ious e,ample creates a bar chart. 6f a different chart type is needed) then the bar chart must be
e,plicitly replaced:
7&r( = 7&r(s1ge(2.5#e(@A.7&r(@)1e#be--e-3b:e'(
7&r(1"igr# =
7&r(1're(e6ns(n'e(@'o#1sun1s(r1'&r(1Line"igr#@)
The first line defines the correspondin chart object. The second line replaces the current chart with a new
one : in this e,ample) a line chart.
Note
6n +icrosoft 4,cel) a distinction is made between charts which ha&e been inserted as a
separate pae in a +icrosoft 4,cel document and charts which are embedded in a table
pae. 7orrespondinly) two different access methods are defined there for charts. This
distinction is not made in LibreOffice #asic) because charts in LibreOffice 7alc are always
created as embedded objects of a table pae. The charts are always accessed usin the
7harts list of the associated Sheet object.
The #tructure of Charts
The structure of a chart) and therefore the list of ser&ices and interfaces supported by it) depends on the
chart type. -or e,ample) the methods and properties of the Z@a,is) are a&ailable in !D charts) but not in "D
charts) and in pie charts) there are no interfaces for workin with a,es.
Title/ #ubtitle and egend
Title) subtitle and leend are basic elements pro&ided for e&ery chart. The 7&r( object pro&ides the
followin properties for administratin these elements:
(as"ain)itle (Boolean)
acti&ates the title
)itle (.b6ect)
object with detailed information about the chart title 8supports the
com.sun.star.chart.7hartTitle ser&ice9
(asSub)itle(Boolean)
acti&ates the subtitle
Subtitle (.b6ect)
object with detailed information about the chart subtitle 8supports the
(asLegen% (Boolean)
acti&ates the leend
Legen% (.b6ect)
object with detailed information about the leend 8supports the
com.sun.star.chart.7hartLeend ser&ice9
#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-r0ing1S&pe. This allows to determine the position and si<e of the
elements usin the Mosi(ion and SiXe properties. /s the si<e of the leend and the titles is calculated
automatically based on the current content and the character heiht for e,ample) the si<e property pro&ides
read access only.
-ill and line properties 8com.sun.star.drawin.-illProperties and com.sun.star.drawin.LineProperties
ser&ices9 as well as the character properties 8com.sun.star.style.7haracterProperties ser&ice9 are pro&ided
for further formattin of the elements.
com.sun.star.chart.7hartTitlecontains not only the listed formattin properties) but also two other properties:
String (String)
te,t which to be displayed as the title or subtitle
)e1t$otation (Long)
anle of rotation of te,t in HGGths of a deree
The leend 8com.sun.star.chart.7hartLeend9 contains the followin additional property:
Alignment (0num)
position at which the leend appears 8&alue of type
com.sun.star.chart.7hartLeendPosition9
The followin e,ample creates a chart with a title M+ain Title StrinM) a subtitle MSubtitle StrinM and a leend.
The leend has a ray backround color) is placed at the bottom of the chart) and has a character si<e of I
points.
"i# "o' $s 3b:e'(
"i# 7&r(s $s 3b:e'(
"i# 7&r( s 3b:e'(
"i# ,e'( $s 5e0 'o#1sun1s(r10(1,e'(ng+e
,e'(1R = 8DDD
,e'(1Z = 1DDD
,e'(1Ci-(& = 1DDDD
,e'(1Beig&( = 7DDD
"o' = T&is7o#ponen(
7&r(s = "o'1S&ee(s(D)17&r(s
True)
7&r( = 7&r(s1ge(2.5#e(@A.7&r(@)1E#be--e-3b:e'(
7&r(1BsAinTi(+e = True
7&r(1Ti(+e1S(ring = @Ain Ti(+e S(ring@
7&r(1BsSubTi(+e = True
7&r(1Sub(i(+e1S(ring = @Sub(i(+e S(ring@
7&r(1BsLegen- = True
7&r(1Legen-1$+ign#en( =
'o#1sun1s(r1'&r(17&r(Legen-Mosi(ion123TT3A
7&r(1Legen-18i++S(.+e =
7&r(1Legen-18i++7o+or = ,G2(21D< 21D< 21D)
7&r(1Legen-17&rBeig&( = 7
!ackground
4&ery chart has a backround area. The 7&r( object pro&ides the property $re to format the backround:
Area (.b6ect)
backround area of the chart 8supports com.sun.star.chart.7hart/rea ser&ice9
The backround of a chart co&ers its complete area) includin the area under the title) subtitle and leend.
The associated com.sun.star.chart.7hart/rea ser&ice supports line and fill properties.
*iagra%
The 7&r( object pro&ides the property "igr# which forms the coordinate system with a,es and rids)
where the data finally is displayed:
Diagram (.b6ect)
object formin the coordinate system where the data is plotted. 6t supports
com.sun.star.chart.Diaram ser&ice and:
com.sun.star.chart.StackableDiaram
com.sun.star.chart.7hart/,isYSupplier
com.sun.star.chart.7hart/,isYSupplier
com.sun.star.chart.7hart/,isZSupplier
com.sun.star.chart.7hartTwo/,isYSupplier
com.sun.star.chart.7hartTwo/,isYSupplier
Different ser&ices are supported dependin on the chart type 8see Chart -ypes9.
(all and Floor
The chart wall is the backround of the coordinate system where the data is plotted. Two chart walls usually
e,ist for !D charts: one behind the plotted data and one as the left@hand or riht@hand demarcation. This
depends on the rotation of the chart. !D charts usually also ha&e a floor.
The "igr# object pro&ides the properties %all and -loor:
Wall (.b6ect)
backround wall of the coordinate system 8supports
com.sun.star.chart.7hart/rea ser&ice9
-loor (.b6ect)
floor panel of coordinate system 8only for !D charts) supports
com.sun.star.chart.7hart/rea ser&ice9
The specified objects support the 'o#1sun1s(r1'&r(17&r($re ser&ice) which pro&ides the usual fill
and line properties 8com.sun.star.drawin.-illProperties and com.sun.star.drawin.LineProperties ser&ices)
refer to Drawings an& Presentations9.
The followin e,ample shows how raphics 8named Sky9 already contained in LibreOffice can be used as a
backround for a chart. The wall is set to be blue.
"i# "o' $s 3b:e'(
"i# 7&r(s $s 3b:e'(
"i# 7&r( s 3b:e'(
"i# ,e'( $s 5e0 'o#1sun1s(r10(1,e'(ng+e
,e'(1R = 8DDD
,e'(1Z = 1DDD
,e'(1Ci-(& = 1DDDD
,e'(1Beig&( = 7DDD
"o' = T&is7o#ponen(
7&r(s = "o'1S&ee(s(D)17&r(s
True)
7&r( = 7&r(s1ge(2.5#e(@A.7&r(@)1E#be--e-3b:e'(
7&r(1$re18i++S(.+e =
'o#1sun1s(r1-r0ing18i++S(.+e126TA$M
7&r(1$re18i++2i(#p5#e = @S/.@
7&r(1$re18i++2i(#pAo-e =
'o#1sun1s(r1-r0ing12i(#pAo-e1,EME$T
7&r(1"igr#1C++18i++S(.+e =
7&r(1"igr#1C++18i++7o+or = ,G2(DD<132<2DL)
",es
LibreOffice reconi<es fi&e different a,es that can be used in a chart. 6n the simplest scenario) these are the
Y and Y@a,es. %hen workin with !D charts) a Z@a,is is also sometimes pro&ided. -or charts in which the
&alues of the &arious rows of data de&iate sinificantly from one another) LibreOffice pro&ides a second Y
and Y@a,is for second scalin operations.
The "igr# object pro&ides the followin properties to access the a,es:
(as8A1is (Boolean)
acti&ates the Y@a,is
8A1is (.b6ect)
object with detailed information about the Y@a,is 8supports
com.sun.star.chart.7hart/,is ser&ice9
(as8A1isDescription (Boolean)
acti&ates the labels for the inter&al marks for the Y@a,is
(as&A1is (Boolean)
acti&ates the Y@a,is
&A1is (.b6ect)
object with detailed information about the Y@a,is 8supports
(as&A1isDescription (Boolean)
acti&ates the labels for the inter&al marks for the Y@a,is
(as9A1is (Boolean)
acti&ates the Z@a,is
9A1is (.b6ect)
object with detailed information about the Z@a,is 8supports
(as9A1isDescription (Boolean)
acti&ates the labels for the inter&al marks for the Z@a,is
(asSecon%ar8A1is (Boolean)
acti&ates the secondary Y@a,is
Secon%ar8A1is (.b6ect)
object with detailed information about the secondary Y@a,is 8supports
(asSecon%ar8A1isDescription (Boolean)
acti&ates the labels for the inter&al marks for the secondary Y@a,is
(asSecon%ar&A1is (Boolean)
acti&ates the secondary Y@a,is
Secon%ar&A1is (.b6ect)
object with detailed information about the secondary Y@a,is 8supports
(asSecon%ar&A1isDescription (Boolean)
acti&ates the labels for the inter&al marks for the secondary Y@a,is
Properties of ",es
The a,is objects of a LibreOffice chart support the com.sun.star.chart.7hart/,is ser&ice. 6n addition to the
properties for characters 8com.sun.star.style.7haracterProperties ser&ice) refer to -e8t Doc"ments9 and lines
8com.sun.star.drawin.LineStyle ser&ice) refer to Drawings an& Presentations9) it pro&ides the followin
properties:
calin1 ,ro,erties7
"a1 (Double)
ma,imum &alue for a,is
"in (Double)
minimum &alue for a,is
.rigin (Double)
point of intersect for crossin a,es
Step"ain (Double)
distance between the major inter&al marks
Step(elp (Double)
distance between the minor inter&al marks 8deprecated since LibreOffice !.GF
0se property Step.elp7ount instead9
Step(elpCount (Long)
7ontains the number of minor inter&als within a major inter&al. 4.. a
Step.elp7ount of ( di&ides the major inter&al into ( pieces and thus produces '
minor tick marks. 8a&ailable since LibreOffice !.G9
Auto"a1 (Boolean)
the ma,imum &alue for the a,is is calculated automatically when set to true
Auto"in (Boolean)
the minimum &alue for the a,is is calculated automatically when set to true
Auto.rigin (Boolean)
the oriin is determined automatically when set to true
AutoStep"ain (Boolean)
Step+ain is determined automatically when set to true
AutoStep(elp (Boolean)
Step.elp7ount is determined automatically when set to true
Logarithmic (Boolean)
scales the a,es in loarithmic manner 8rather than linear9
$e3erseDirection (Boolean)
determines if the a,is orientation is mathematical or re&ersed. 8a&ailable since
LibreOffice ".'9
Label ,ro,erties7
DisplaLabels (Boolean)
acti&ates the te,t label at the inter&al marks
)e1t$otation (Long)
anle of rotation of te,t label in HGGths of a deree
Arrange.r%er (enum)
the label may be staered) thus they are positioned alternately o&er two lines
8&alues accordin to com.sun.star.chart.7hart/,is/rraneOrderType9
)e1tBrea' (Boolean)
permits line breaks within the a,es labels
)e1tCan.3erlap (Boolean)
permits an o&erlap of the a,es labels
Number-ormat (Long)
number format to be used with the a,es labels
Lin'Number-ormat)oSource (Boolean)
determines whether to use the number format i&en by the container document)
or from the property 5u#ber8or#(. 8since LibreOffice ".!9
"nterval +ar9 ,ro,erties7
"ar's (Const)
determines the position of the major inter&al marks 8&alues in accordance with
com.sun.star.chart.7hart/,is+arks9
(elp"ar's (Const)
determines the position of the minor inter&al marks 8&alues in accordance with
com.sun.star.chart.7hart/,is+arks9
Onl- for bar charts7
.3erlap (Long)
percentae which specifies the e,tent to which the bars of different sets of data
may o&erlap 8at HGG]) the bars are shown as completely o&erlappin) at @HGG])
there is a distance of the width of one bar between them9
+apWi%th (long)
percentae which specifies the distance there may be between the different
roups of bars of a chart 8at HGG]) there is a distance correspondin to the width
of one bar9
&rids
-or the primary a,es rids and sub rids can be displayed) matchin to the major and minor inter&als. The
"igr# object pro&ides the followin properties to access the rids:
(as8A1is+ri% (Boolean)
acti&ates major rid for Y@a,is
8"ain+ri% (.b6ect)
object with detailed information about the major rid for Y@a,is 8supports
com.sun.star.chart.7hart$rid ser&ice9
(as8A1is(elp+ri% (Boolean)
acti&ates minor rid for Y@a,is
8(elp+ri% (.b6ect)
object with detailed information about the minor rid for Y@a,is 8supports
the same for y and <:
(as&A1is+ri% (Boolean)
acti&ates major rid for Y@a,is
&"ain+ri% (.b6ect)
object with detailed information about the major rid for Y@a,is 8supports
(as&A1is(elp+ri% (Boolean)
acti&ates minor rid for Y@a,is
&(elp+ri% (.b6ect)
object with detailed information about the minor rid for Y@a,is 8supports
(as9A1is+ri% (Boolean)
acti&ates major rid for Z@a,is
9"ain+ri% (.b6ect)
object with detailed information about the major rid for Z@a,is 8supports
(as9A1is(elp+ri% (Boolean)
acti&ates minor rid for Z@a,is
9(elp+ri% (.b6ect)
object with detailed information about the minor rid for Z@a,is 8supports
The rid object is based on the com.sun.star.chart.7hart$rid ser&ice) which in turn supports the line
properties of the com.sun.star.drawin.LineStyle support ser&ice 8refer to Drawings an& Presentations9.
",es Title
-or all a,es an additional title can be displayed. The "igr# object pro&ides the followin properties to
access the a,es title:
(as8A1is)itle (Boolean)
acti&ates title of Y@a,is
8A1is)itle (.b6ect)
object with detailed information about title of the Y@a,is 8supports
same y and <:
(as&A1is)itle (Boolean)
acti&ates title of Y@a,is
&A1is)itle (.b6ect)
object with detailed information about title of the Y@a,is 8supports
(as9A1is)itle (Boolean)
acti&ates title of Z@a,is
9A1is)itle (.b6ect)
object with detailed information about title of the Z@a,is 8supports
and for the secondary a,es 8a&ailable since LibreOffice !.G9:
(asSecon%ar8A1is)itle (Boolean)
acti&ates title of the secondary Y@a,is.
Secon%8A1is)itle (.b6ect)
object with detailed information about title of the secondary Y@a,is 8supports
(asSecon%ar&A1is)itle (Boolean)
acti&ates title of the secondary Y@a,is.
Secon%&A1is)itle (.b6ect)
object with detailed information about title of the secondary Y@a,is 8supports
The objects for formattin the a,es title are based on the com.sun.star.chart.7hartTitle ser&ice) which is also
used for chart titles.
Exa+,le
The followin e,ample creates a line chart. The color for the rear wall of the chart is set to white. #oth the Y
and Y@a,es ha&e a ray rid for &isual orientation. The minimum &alue of the Y@a,is is fi,ed to G and the
ma,imum &alue is fi,ed to HGG so that the resolution of the chart is retained e&en if the &alues are chaned.
The Y@a,is points in re&erse direction from riht to left. /nd a title for the Y@a,is was added.
"i# "o' $s 3b:e'(
"i# 7&r(s $s 3b:e'(
"i# 7&r( s 3b:e'(
"i# ,e'( $s 5e0 'o#1sun1s(r10(1,e'(ng+e
"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
True)
7&r( = 7&r(s1ge(2.5#e(@A.7&r(@)1e#be--e-3b:e'(
7&r(1"igr# =
7&r(1're(e6ns(n'e(@'o#1sun1s(r1'&r(1Line"igr#@)
7&r(1"igr#1C++18i++7o+or = ,G2(255< 255< 255)
7&r(1"igr#1BsR$xisGri- = True
7&r(1"igr#1RAinGri-1Line7o+or = ,G2(1L2< 1L2< 1L2)
7&r(1"igr#1BsZ$xisGri- = True
7&r(1"igr#1ZAinGri-1Line7o+or = ,G2(1L2< 1L2< 1L2)
7&r(1"igr#1Z$xis1Ain = D
7&r(1"igr#1Z$xis1Ax = 1DD
7&r(1"igr#1R$xis1,e*erse"ire'(ion = (rue %nee-s
Libre3))i'e 214 or ne0er
7&r(1"igr#1BsR$xisTi(+e = (rue
7&r(1"igr#1R$xisTi(+e1S(ring = @,e*erse- R $xis
Ex#p+e@
9* Charts
+ost charts in LibreOffice can also be displayed with !D raphics. The followin properties are pro&ided for
!D charts at the "igr# object:
Dim:D (Boolean)
acti&ates !D display
Deep (Boolean)
the series will be arraned behind each other in <@direction
$ightAngle%A1es (Boolean)
acti&ates a !D display mode where Y@ and Y@a,es form a riht anle within the
projection. 8a&ailable since LibreOffice ".!9
D:DScene2erspecti3e (0num)
defines whether the !D objects are to be drawn in perspecti&e or parallel
projection.8&alues accordin to com.sun.star.drawin.Projection+ode9
2erspecti3e (Long)
Perspecti&e of !D charts 8 ^G)HGG_ 9 8a&ailable since LibreOffice ".'.H9
$otation(ori4ontal (Long)
.ori<ontal rotation of !D charts in derees 8 ^@HJG)HJG_ 9 8a&ailable since
LibreOffice ".'.H9
$otationVertical (Long)
;ertical rotation of !D charts in derees 8 ^@HJG)HJG_ 9 8a&ailable since LibreOffice
".'.H9
The followin e,ample creates a !D area chart.
"i# "o' $s 3b:e'(
"i# 7&r(s $s 3b:e'(
"i# 7&r( s 3b:e'(
"i# ,e'( $s 5e0 'o#1sun1s(r10(1,e'(ng+e
"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
True)
7&r( = 7&r(s1ge(2.5#e(@A.7&r(@)1e#be--e-3b:e'(
7&r(1"igr# =
7&r(1're(e6ns(n'e(@'o#1sun1s(r1'&r(1$re"igr#@)
7&r(1"igr#1"i#3" = (rue
7&r(1"igr#1"eep = (rue
7&r(1"igr#1,ig&($ng+e-$xes = (rue %nee-s Libre3))i'e
213 or ne0er
7&r(1"igr#1"3"S'eneMerspe'(i*e =
'o#1sun1s(r1-r0ing1Mro:e'(ionAo-e1ME,SME7T64E
7&r(1"igr#1Merspe'(i*e = 1DD %nee-s Libre3))i'e 21411
or ne0er
7&r(1"igr#1,o((ionBoriXon(+ = 6D %nee-s Libre3))i'e
21411 or ne0er
7&r(1"igr#1,o((ion4er(i'+ = 3D %nee-s Libre3))i'e
21411 or ne0er
#tacked Charts
Stacked charts are charts that are arraned 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.
6n LibreOffice) &arious types of charts can be displayed in a stacked form. /ll of these charts support the
com.sun.star.chart.StackableDiaram ser&ice) which in turn pro&ides the followin properties:
Stac'e% (Boolean)
acti&ates the stacked &iewin mode
2ercent (Boolean)
rather than absolute &alues) displays their percentae distribution
Chart Types
ine Charts
Line charts 8com.sun.star.chart.LineDiaram9 support two Y@a,es) two Y@a,es and one Z@a,is. They can be
displayed as "D or !D raphics 8com.sun.star.chart.Dim!Ddiaramser&ice9. The lines can be stacked
8com.sun.star.chart.StackableDiaram9.
Line charts pro&ide the followin properties:
Smbol)pe (const)
symbol for displayin the data points 8constant in accordance with
com.sun.star.chart.7hartSymbolType9
SmbolSi4e (Long)
si<e of symbol for displayin the data points in HGGths of a millimeter
SmbolBitmapU$L (String)
file name of raphics for displayin the data points
Lines (Boolean)
links the data points by means of lines
Spline)pe (Long)
spline function for smoothin the lines 8G: no spline function) H: cubic splines) ": #
splines9
Spline.r%er (Long)
polynomial weiht for splines 8only for # splines9
Spline$esolution (Long)
number of support points for spline calculation
"rea Charts
/rea charts 8com.sun.star.chart./reaDiaram ser&ice9 support two Y@a,es) two Y@a,es and one Z@a,is. They
can be displayed as "D or !D raphics 8com.sun.star.chart.Dim!Ddiaram ser&ice9. The areas can be
stacked 8com.sun.star.chart.StackableDiaram9.
!ar Charts
#ar charts 8com.sun.star.chart.#arDiaram9 support two Y@a,es) two Y@a,es and one Z@a,is. They can be
displayed as "D or !D raphics 8com.sun.star.chart.Dim!Ddiaram ser&ice9. The bars can be stacked
8com.sun.star.chart.StackableDiaram9.
They pro&ide the followin properties:
Vertical (Boolean)
displays the bars &ertically) otherwise they are depicted hori<ontally
Deep (Boolean)
in !D &iewin mode) positions the bars behind one another rather than ne,t to
one another
Stac'e%BarsConnecte% (Boolean)
links the associated bars in a stacked chart by means of lines 8only a&ailable with
hori<ontal charts9
Number.!Lines (Long)
number of lines to be displayed in a stacked chart as lines rather than bars
+roupBars2erA1is (Boolean)
displays bars attached to different a,es behind or ne,t to each other 8a&ailable
since LibreOffice ".'9
Pie Charts
Pie charts 8com.sun.star.chart.PieDiaram9 do not contain any a,es and cannot be stacked. They can be
displayed as "D or !D raphics 8com.sun.star.chart.Dim!DDiaram ser&ice9.
The followin properties are pro&ided for pie and donut charts with the "igr# object:
StartingAngle (Long)
anle of the first piece of a pie in derees 8a&ailable since LibreOffice !.G9
#asic $uide
Chapter $>
Databases
*atabases
LibreOffice has an interated database interface 8independent of any systems9 called Star Database
7onnecti&ity 8SD#79. The objecti&e of de&elopin this interface was to pro&ide access to as many different
data sources as possible.
To make this possible) data sources are accessed by dri&ers. The sources from which the dri&ers take their
data is irrele&ant to a SD#7 user. Some dri&ers access file@based databases and take the data directly from
them. Others use standard interfaces such as =D#7 or OD#7. There are) howe&er) also special dri&ers
which access the +/P6 address book) LD/P directories or LibreOffice spreadsheets as data sources.
Since the dri&ers are based on 01O components) other dri&ers can be de&eloped and therefore open up
new data sources. You will find details about this in the LibreOffice De&eloper>s $uide.
Note
6n terms of its concept) SD#7 is comparable with the /DO and D/O libraries a&ailable in
;#/. 6t permits hih le&el access to databases) reardless of the underlyin database
b'/en-s1
#20 a 2uery anguage
The SUL lanuae is pro&ided as a 5uery lanuae for users of SD#7. To compare the differences between
different SUL dialects) the SD#7 components from LibreOffice ha&e their own SUL parser. This uses the
5uery window to check the SUL commands typed and corrects simple synta, errors) such as those
associated with uppercase and lowercase characters.
6f a dri&er permits access to a data source that does not support SUL) then it must independently con&ert the
transferred SUL commands to the nati&e access needed.
Types of *atabase "ccess
The database interface from LibreOffice is a&ailable in the LibreOffice %riter and LibreOffice 7alc
applications) as well as in the database forms.
6n LibreOffice %riter) standard letters can be created with the assistance of SD#7 data sources and these
can then be printed out. You can also mo&e data from the database window into te,t documents usin the
dra@and@drop function.
6f you mo&e a database table into a spreadsheet) LibreOffice creates a table area which can be updated at
the click of the mouse if the oriinal data has been modified. 7on&ersely) spreadsheet data can be mo&ed to
a database table and a database import performed.
-inally) LibreOffice pro&ides a mechanism for forms based on databases. To do this) you first create a
standard LibreOffice %riter or LibreOffice 7alc form and then link the fields to a database.
/ll the options specified here are based on the user interface from LibreOffice. 1o prorammin knowlede
is needed to use the correspondin functions.
This section) howe&er) pro&ides little information about the functions specified) but instead concentrates on
the prorammin interface from SD#7) which allows for automated database 5ueryin and therefore permits
a much reater rane of applications to be used.
#asic knowlede of the way in which databases function and the SUL 5uery lanuae is howe&er needed to
fully understand the followin sections.
*ata #ources
/ database is incorporated into LibreOffice by creatin what is commonly referred to as a data source. The
user interface pro&ides a correspondin option for creatin data sources in the 4,tras menu. You can also
create data sources and work with them usin LibreOffice #asic.
/ database conte,t object that is created usin the 're(eNnoSer*i'e function ser&es as the startin
point for accessin a data source. This based on the com.sun.star.sdb.Database7onte,t ser&ice and is the
root object for all database operations.
The followin e,ample shows how a database conte,t can be created and then used to determine the names
of all data sources a&ailable. 6t displays the names in a messae bo,.
"i# "(bse7on(ex( $s 3b:e'(
"i# 5#es
"i# 6 $s 6n(eger
"(bse7on(ex( =
're(eNnoSer*i'e(@'o#1sun1s(r1s-b1"(bse7on(ex(@)
5#es = "(bse7on(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 conte,t usin the ge(2.5#e method:
"i# "(Sour'e $s 3b:e'(
"(bse7on(ex( =
"(Sour'e = "(bse7on(ex(1ge(2.5#e(@7us(o#ers@)
The e,ample creates a "(Sour'e object for a data source called Customers.
Data sources pro&ide a rane of properties) which in turn pro&ide eneral information about the oriin of the
data and information about access methods. The properties are:
Name (String)
name of data source
U$L (String)
0*L of data source in the form of jdbc: subprotocol : subnameor sdbc: subprotocol :
subname
Settings (Arra)
array containin Mroper(.4+ue@pairs with connection parameters 8usually at
least user name and password9
User (String)
user name
2ass*or% (String)
user password 8is not sa&ed9
Is2ass*or%$e7uire% (Boolean)
the password is needed and is interacti&ely re5uested from user.
Is$ea%.nl (Boolean)
permits read@only access to the database
Number-ormatsSupplier (.b6ect)
object containin the number formats a&ailable for the database 8supports the
com.sun.star.util.Y1umber-ormatsSupplier interface9
)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 LibreOffice are not H:H comparable with the data sources in OD#7.
%hereas an OD#7 data source only co&ers information about the oriin of the data) a data
source in LibreOffice also includes a rane of information about how the data is displayed
within the database windows of LibreOffice.
2ueries
Predefined 5ueries can be assined to a data source. LibreOffice notes the SUL commands of 5ueries so
that they are a&ailable at all times. Uueries are used to simplify workin with databases because they can be
opened with a simple mouse click and also pro&ide users without any knowlede of SUL with the option of
issuin SUL commands.
/n object which supports the com.sun.star.sdb.UueryDefinition ser&ice is concealed behind a 5uery. The
5ueries are accessed by means of the Suer."e)ini(ions method of the data source.
The followin e,ample lists the names of data source 5ueries can be established in a messae bo,.
"i# Suer."e)ini(ions $s 3b:e'(
"i# Suer."e)ini(ion $s 3b:e'(
"i# 6 $s 6n(eger
"(bse7on(ex( =
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
6n addition to the 1ame property used in the e,ample) the com.sun.star.sdb.UueryDefinition pro&ides a
whole rane of other properties. These are:
Name (String)
5uery name
Comman% (String)
SUL command 8typically a SELE7T command9
The followin e,ample shows how a 5uery object can be created in a proram@controlled manner and can be
assined to a data source.
"i# Suer."e)ini(ions $s 3b:e'(
"i# Suer."e)ini(ion $s 3b:e'(
"i# 6 $s 6n(eger
"(bse7on(ex( =
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)
$#> LibreOffice 3 Basic %"i&e
The 5uery object is first created usin the 're(eNnoSer*i'e call) then initiali<ed) and then inserted into
the Suer."e)ini(ions object by means of inser(2.5#e.
*atabase "ccess
/ database connection is needed for access to a database. This is a transfer channel which permits direct
communication with the database. 0nlike the data sources presented in the pre&ious section) the database
connection must therefore be re@established e&ery time the proram is restarted.
LibreOffice pro&ides &arious ways of establishin database connections. This e,ample shows how to
connect to an e,istin data source.
"i# 7onne'(ion $s 3b:e'(
"i# 6n(er'(ionBn-+er s 3b:e'(
"(bse7on(ex( =
6) 5o( "(Sour'e16sMss0or-,e?uire- T&en
7onne'(ion = "(Sour'e1Ge(7onne'(ion(@@<@@)
E+se
6n(er'(ionBn-+er =
're(eNnoSer*i'e(@'o#1sun1s(r1s-b16n(er'(ionBn-+er@)
7onne'(ion =
"(Sour'e17onne'(Ci(&7o#p+e(ion(6n(er'(ionBn-+er)
En- 6)
The code used in the e,ample first checks whether the database is password protected. 6f not) it creates the
database connection re5uired usin the Ge(7onne'(ion call. The two empty strins in the command line
stand for the user name and password.
6f the database is password protected) the e,ample creates an 6n(er'(ionBn-+er and opens the
database connection usin the 7onne'(Ci(&7o#p+e(ion method. The 6nteraction.andler ensures that
LibreOffice asks the user for the re5uired loin data.
$teration of Tables
/ table is usually accessed in LibreOffice throuh the ,esu+(Se( object. / ,esu+(Se( is a type of marker
that indicates a current set of data within a &olume of results obtained usin the SELE7T command.
This e,ample shows how a ,esu+(Se( can be used to 5uery &alues from a database table.
"i# 7onne'(ion $s 3b:e'(
"i# 6n(er'(ionBn-+er s 3b:e'(
"i# S((e#en( $s 3b:e'(
"i# ,esu+(Se( $s 3b:e'(
"(bse7on(ex( =
6) 5o( "(Sour'e16sMss0or-,e?uire- T&en
7onne'(ion = "(Sour'e1Ge(7onne'(ion(@@<@@)
E+se
6n(er'(ionBn-+er =
're(eNnoSer*i'e(@'o#1sun1s(r1s-b16n(er'(ionBn-+er@)
7onne'(ion =
Chapter $2 4orms $#$
"(Sour'e17onne'(Ci(&7o#p+e(ion(6n(er'(ionBn-+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)
Cen-
En- 6)
Once the database connection has been established) the code used in the e,ample 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 proram now checks whether the ,esu+(Se(
actually e,ists and tra&erses the data records usin a loop. The &alues re5uired 8in the e,ample) those from
the 7us(o#er5u#ber field9 returns the ,esu+(Se( usin the ge(S(ring method) whereby the parameter
H determines that the call relates to the &alues of the first column.
Note
The ,esu+(Se( object from SD#7 is comparable with the ,e'or-se( object from
"$3 and $"3) since this also pro&ides iterati&e access to a database.
Note
The database is actually accessed in LibreOffice throuh a ,esu+(Se( object. This
reflects the content of a table or the result of a SUL@S4L47T command. 6n the past) the
,esu+(Se( object pro&ided the resident methods in the /pplication object for na&iation
within the data) for e,ample) "(5ex(,e'or- )1
Type.#pecific Methods for 1etrieving )alues
/s can be seen in the e,ample from the pre&ious section) LibreOffice pro&ides a ge(S(ring method for
accessin table contents. The method pro&ides the result in the form of a strin. The followin ge( methods
are a&ailable:
getBte()
supports the SUL data types for numbers) characters and strins
getShort()
getInt()
getLong()
get-loat()
getDouble()
getBoolean()
getString()
supports all SUL data types
$#2 LibreOffice 3 Basic %"i&e
getBtes()
supports the SUL data types for binary &alues
getDate()
supports the SUL data types for numbers) strins) date and time stamp
get)ime()
get)imestamp()
getCharacterStream()
supports the SUL data types for numbers) strins and binary &alues
getUnico%eStream()
supports the SUL data types for numbers) strins and binary &alues
getBinarStream()
binary &alues
get.b6ect()
supports all SUL data types
6n all instances) the number of columns should be listed as a parameter whose &alues should be 5ueried.
The 1esult#et )ariants
/ccessin databases is often a matter of critical speed. LibreOffice pro&ides se&eral ways of optimi<in
,esu+(Se(s and thereby controllin the speed of access. The more functions a ,esu+(Se( pro&ides) the
more comple, its implementation usually is and therefore the slower the functions are.
/ simple ,esu+(Se(< pro&ides the minimum scope of functions a&ailable. 6t only allows iteration to be
applied forward) and for &alues to be interroated. +ore e,tensi&e na&iation options) such as the possibility
of modifyin &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 8specifications in
accordance with com.sun.star.sdbc.*esultSet7oncurrency9.
$esultSet)pe (const)
specifications reardin type of ,esu+(Se(s 8 specifications in accordance with
com.sun.star.sdbc.*esultSetType9.
The &alues defined in com.sun.star.sdbc.*esultSet7oncurrency are:
U2DA)ABL0
,esu+(Se( permits &alues to be modified
$0AD,.NL&
,esu+(Se( does not permit modifications
The com.sun.star.sdbc.*esultSet7oncurrency roup of constants pro&ides the followin specifications:
-.$WA$D,.NL&
,esu+(Se( only permits forward na&iation
Chapter $2 4orms $#3
SC$.LL,INS0NSI)IV0
,esu+(Se( permits any type of na&iation) chanes to the oriinal data are)
howe&er) not noted
SC$.LL,S0NSI)IV0
,esu+(Se( permits any type of na&iation) chanes to the oriinal data impact
on the ,esu+(Se(
Note
$ ,esu+(Se( 'on(ining (&e ,E$"_35LZ n- S7,3LL_65SE5S6T64E
proper(ies 'orrespon-s (o re'or- se( o) (&e Snps&o( (.pe in $"3
n- "$31
%hen usin the ,esu+(Se(%s NM"$TE$2LE and S7,3LL_SE5S6T64E properties) the scope of function of
a ,esu+(Se( is comparable with a ".nse( type ,e'or-se( from /DO and D/O.
Methods for Navigation in 1esult#ets
6f a ,esu+(Se( is a S7,3LL_65SE5S6T64E or S7,3LL_SE5S6T64E type) it supports a whole rane of
methods for na&iation in the stock of data. The central methods are:
ne1t()
na&iation to the ne,t data record
pre3ious()
na&iation to the pre&ious data record
!irst()
na&iation to the first data record
last()
na&iation to the last data record
be!ore-irst()
na&iation to before the first data record
a!terLast()
na&iation to after the last data record
/ll methods return a #oolean parameter which specifies whether the na&iation was successful.
To determine the current cursor position) the followin 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
isLast()
,esu+(Se( is the last data record
Modifying *ata 1ecords
6f a ,esu+(Se( has been created with the ,esu+(Se(7on'urren'. N NM"$TE$2LE &alue) then its
content can be edited. This only applies for as lon as the SUL command allows the data to be re@written to
$#2 LibreOffice 3 Basic %"i&e
the database 8depends on principle9. This is not) for e,ample) possible with comple, SUL commands with
linked columns or accumulated &alues.
The ,esu+(Se( object pro&ides Np-(e methods for modifyin &alues) which are structured in the same
way as the ge( methods for retrie&in &alues. The up-(eS(ring method) for e,ample) allows a strin to
be written.
/fter modification) the &alues must be transferred into the database usin the up-(e,o0()method. The
call must take place before the ne,t na&iation command) otherwise the &alues will be lost.
6f an error is made durin the modifications) this can be undone usin the 'n'e+,o0Np-(es()method.
This call is only a&ailable pro&ided that the data has not be re@written into the database usin up-(e,o0().
Chapter $2 4orms $#3
#asic $uide
Chapter $$
Dialogs
*ialogs
Chapter $2 4orms $#'
You can add custom dialo windows and forms to LibreOffice documents. These in turn can be linked to
LibreOffice #asic macros to considerably e,tend the usae rane of LibreOffice #asic. Dialos can) for
e,ample) display database information or uide users throuh a step@by@step process of creatin a new
document in the form of a %i<ard.
Tip
You will find another description of dialos in the De&eloper>s $uide:
chapter LibreOffice@Basic@"/E describes more fully the 6D4
chapter 3ro1ra++in1 /ialo1s and /ialo1 !ontrols shows more e,amples in #asic.
(orking (ith *ialogs
LibreOffice #asic dialos consist of a dialo window that can contain te,t fields) list bo,es) radio buttons) and
other control elements.
Creating *ialogs
You can create and structure dialos usin the LibreOffice dialo editor:
4ig"re 3: Create an& str"ct"re &ialogs in the &ialog e&itor
You can dra the control elements from the desin pallet 8riht9 into the dialo area) and define their position
and si<e.
The e,ample shows a dialo that contains a label and a list bo,.
4ig"re 2: ( &ialog containing a label an& a list bo8
You can open a dialo with the followin code:
"i# "+g $s 3b:e'(
"i+ogLibrries1Lo-Librr.(@S(n-r-@)
"+g = 7re(eNno"i+og("i+ogLibrries1S(n-r-1"+g"e))
"+g1Exe'u(e()
"+g1-ispose()
7re(eNno"i+og creates an object called "+g that references the associated dialo. #efore you can
create the dialo) you must ensure that the library it uses 8in this e,ample) the S(n-r- library9 is loaded.
The Lo-Librr. method performs this task.
Once the "+g dialo object has been initiali<ed) you can use the Exe'u(e method to display the dialo.
Dialos such as this one are described as modal because they do not permit any other proram action until
they are closed. %hile this dialo is open) the proram remains in the Exe'u(e call.
The -ispose method at the end of the code releases the resources used by the dialo once the proram
ends.
Closing *ialogs
!losin1 With OA or !ancel
6f a dialo contains an OKor a Cancelbutton) the dialo is automatically closed when you click one of these
buttons. +ore information about workin with these buttons is discussed in Dialog Control 5lements in Detail.
6f you close a dialo by clickin the OKbutton) the Exe'u(e method returns a return &alue of H) otherwise a
&alue of G is returned.
"i# "+g $s 3b:e'(
"i+ogLibrries1Lo-Librr.(@S(n-r-@)
"+g = 7re(eNno"i+og("i+ogLibrries1S(n-r-1A."i+og)
Se+e'( 7se "+g1Exe'u(e()
7se 1
Asg2ox @3/ presse-@
$#+ LibreOffice 3 Basic %"i&e
7se D
Asg2ox @7n'e+ presse-@
En- Se+e'(
!losin1 With the !lose Button in the Title Bar
You can close a dialo by clickin the close button on the title bar of the dialo window. The Exe'u(e
method of the dialo returns the &alue G) which is the same as when you click 7ancel.
!losin1 With an Ex,licit 3ro1ra+ !all
You can also close an open dialo window with the en-Exe'u(e method:
"+g1en-Exe'u(e()
The 4,ecute method of the dialo returns the &alue G) which is the same as when you click 7ancel.
"ccess to $ndividual Control +le%ents
/ dialo can contain any number of control elements. You can access these elements throuh 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(+1Lbe+ = @5e0 Lbe+@
This code determines the object for the A.2u((on control element and then initiali<es the 7(+ object
&ariable with a reference to the element. -inally the code sets the Lbe+ property of the control element to
the 5e0 Lbe+ &alue.
Note
Nn+i/e Libre3))i'e 2si' i-en(i)iers< (&e n#es o) 'on(ro+ e+e#en(s
re 'se sensi(i*e1
(orking (ith the Model of *ialogs and Control +le%ents
The di&ision between &isible proram elements 8View9 and the data or documents behind them 8Model9
occurs at many places in LibreOffice /P6. 6n addition to the methods and properties of control elements) both
dialo and control element objects ha&e a subordinate Ao-e+ object. This object allows you to directly
access the content of a dialo or control element.
6n dialos) the distinction between data and depiction is not always as clear as in other /P6 areas of
LibreOffice. 4lements of the /P6 are a&ailable throuh both the ;iew and the +odel.
The Ao-e+ property pro&ides proram@controlled access to the model of dialo and control element objects.
"i# '#-5ex( $s 3b:e'(
'#-5ex( = "+g1ge(7on(ro+(@'#-5ex(@)
'#-5ex(1Ao-e+1Enb+e- = 8+se
This e,ample deacti&ates the '#-5ex( button in the "+g dialo with the aid of the model object from
'#-5ex(.
Properties
Na%e and Title
4&ery control element has its own name that can be 5ueried usin the followin model property:
"o%el.Name (String)
control element name
Chapter $2 4orms $#,
You can specify the title that appears in the title bar of a dialo with the followin model property:
"o%el.)itle (String)
dialo title 8only applies to dialos9
Position and #i:e
You can 5uery the si<e and position of a control element usin the followin properties of the model object:
"o%el.(eight (long)
heiht of control element 8in ma units9
"o%el.Wi%th (long)
width of control element 8in ma units9
"o%el.2osition8 (long)
Y@position of control element) measured from the left inner ede of the dialo 8in
ma units9
"o%el.2osition& (long)
Y@position of control element) measured from top inner ede of the dialo 8in ma
units9
To ensure platform independence for the appearance of dialos) LibreOffice uses the Map AppFont (ma)
internal unit to specify the position and si<e within dialos. /n ma unit is defined as bein one eihth of the
a&erae heiht of a character from the system font defined in the operatin system and one 5uarter of its
width. #y usin ma units) LibreOffice ensures that a dialo looks the same on different systems under
different system settins.
6f you want to chane the si<e or position of control elements for runtime) determine the total si<e of the
dialo and adjust the &alues for the control elements to the correspondin part ratios.
Note
The +ap $pp8on( 8ma9 replaces the Twips unit to achie&e better platform independence.
Focus and Tabulator #e;uence
You can na&iate throuh the control elements in any dialo by pressin the Tab key. The followin
properties are a&ailable in this conte,t 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 throuh the Tab key
"o%el.)abIn%e1 (Long)
position of control element in the order of acti&ation
-inally) the control element pro&ides a ge(8o'us method that ensures that the underlyin control element
recei&es the focus:
get-ocus
control element recei&es the focus 8only for dialos9
Multi.Page *ialogs
/ dialo in LibreOffice can ha&e more than one tab pae. The S(ep property of a dialo defines the current
tab pae of the dialo whereas the S(ep property for a control element specifies the tab pae where the
control element is to be displayed.
$'> LibreOffice 3 Basic %"i&e
The S(ep@&alue of G is a special case. 6f you set this &alue to <ero in a dialo) all of the control elements are
&isible reardless of their S(ep &alue. Similarly) if you set this &alue to <ero for a control element) the
element is displayed on all of the tab paes in a dialo.
4ig"re 3: Designing Page $ of the &ialog
6n the precedin e,ample) you can also assin the S(ep &alue of G to the di&idin line as well as the
7n'e+) Mre*) 5ex() and "one buttons to display these elements on all paes. You can also assin the
elements to an indi&idual tab pae 8for e,ample pae H9.
The followin proram code shows how the S(ep &alue in e&ent handlers of the 5ex( and Mre* buttons can
be increased or reduced and chanes 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+1Enb+e- = 5o( '#-Mre*1Ao-e+1Enb+e-
'#-5ex(1Ao-e+1Enb+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+1Enb+e- = 8+se
'#-5ex(1Ao-e+1Enb+e- = True
"+g1Ao-e+1S(ep = "+g1Ao-e+1S(ep H 1
En- Sub
/ lobal "+g &ariable that references an open dialo must be included to make this e,ample possible. The
dialo then chanes its appearance as follows:
4ig"re #: Page $
4ig"re ': Page 2
Tip You can find an other OOoBasic exa+,le here.
Chapter $2 4orms $'$
*ialogs supporting several languages
The strins of a Dialo can be locali<ed) see the De&eloper>s $uide chapter Dialog LocaliAation.
+vents
LibreOffice dialos and forms are based on an e&ent@oriented prorammin model where you can assin
event handlersto 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 handlin as well as access other
control elements.
LibreOffice control elements reconi<e different types of e&ents that can be triered in different situations.
These e&ent types can be di&ided into four roups:
Mouse control: 4&ents that correspond to mouse actions 8for e,ample) simple mouse mo&ements or a click
on a particular screen location9.
Keyboard control: 4&ents that are triered by keyboard strokes.
Focus modification: 4&ents that LibreOffice performs when control elements are acti&ated or deacti&ated.
Control element-specific events: 4&ents that only occur in relation to certain control elements.
%hen you work with e&ents) make sure that you create the associated dialo in the LibreOffice de&elopment
en&ironment and that it contains the re5uired control elements or documents 8if you apply the e&ents to a
form9.
4ig"re +: -he LibreOffice Basic &e.elopment en.ironment
The fiure abo&e shows the LibreOffice #asic de&elopment en&ironment with a dialo window that contains
two list bo,es. You can mo&e the data from one list to the other usin the buttons between the two list bo,es.
6f you want to display the layout on screen) then you should create the associated LibreOffice #asic
procedures so that they can be called up by the e&ent handlers. 4&en thouh you can use these procedures
in any module) it is best to limit their use to two modules. To make your code easier to read) you should
assin meaninful names to these procedures. =umpin directly to a eneral proram procedure from a
macro can result in unclear code. 6nstead) to simplify code maintenance and troubleshootin) you should
create another procedure to ser&e as an entry point for e&ent handlin @ e&en if it only e,ecutes a sinle call
to the taret procedure.
The code in the followin e,ample mo&es an entry from the left to the riht list bo, of a dialo.
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
6f this procedure was created in LibreOffice #asic) you can assin it to an e&ent re5uired usin the
property window of the dialo editor.
4ig"re ,: -he assign (ction &ialog
The /ssin /ction dialo lists all of the a&ailable 4&ents. To assin a macro to an e&ent:
Select the e&ent
$'2 LibreOffice 3 Basic %"i&e
7lick Macro...
#rowse to and select the macro you want to assin
7lick OO
Para%eters
The occurrence of a particular e&ent is not always enouh for an appropriate response. /dditional
information may be re5uired. -or e,ample) to process a mouse click) you may need the screen position
where the mouse button was pressed.
6n LibreOffice #asic) you can use object parameters to pro&ide more information about an e&ent to a
procedure) for e,ample:
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 triers the procedure
call.
*eardless 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 usin E*en(1Sour'e and its model usin E*en(1Sour'e1Ao-e+.
You can use these properties to trier an e&ent within an e&ent handler.
Mouse +vents
LibreOffice #asic reconi<es the followin mouse e&ents:
"ouse mo3e%
user mo&es mouse
"ouse mo3e% *hile 'e presse%
user dras mouse while holdin down a key
"ouse button presse%
user presses a mouse button
Note
This e&ent is also used for notifyin re5uests for a popup conte,t menu on the control. 6n
this case) the member MopupTrigger of the e&ent passed to your macro function will be
T*04. 6n particular) if such a re5uest is made by pressin the riht mouse button on the
control) the e&ent will be fired twice: once for the popup menu re5uest) and once for the real
mouse e&ent. 6f you are interested in only the mouse click) your macro should inore all
calls where MopupTrigger is T,NE1
"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.+ouse4&ent structure which
pro&ides the followin information:
Buttons (short)
button pressed 8one or more constants in accordance with
com.sun.star.awt.+ouse#utton9
8 (long)
Y@coordinate of mouse) measured in pi,els from the top left corner of the control
element
Chapter $2 4orms $'3
& (long)
Y@coordinate of mouse) measured in pi,els from the top left corner of the control
element
Clic'Count (long)
number of clicks associated with the mouse e&ent 8if LibreOffice can respond fast
enouh) 7+i'/7oun( is also H for a double@click because only an indi&idual
e&ent is initiated9
The constants defined in com.sun.star.awt.+ouse#utton for the mouse buttons are:
L0-)
left mouse button
$I+()
riht mouse button
"IDDL0
middle mouse button
The followin e,ample 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(r10(1Aouse2u((on1LE8T
T&en
Asg = Asg G @LE8T @
En- 6)
6) E*en(12u((ons $5" 'o#1sun1s(r10(1Aouse2u((on1,6GBT
T&en
Asg = Asg G @,6GBT @
En- 6)
6) E*en(12u((ons $5"
'o#1sun1s(r10(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
Note
The ;#/ 7lick and Doubleclick e&ents are not a&ailable in LibreOffice #asic. 6nstead use
the LibreOffice #asic +ouse0p e&ent for the click e&ent and imitate the Doubleclick e&ent
by chanin the application loic.
<eyboard +vents
The followin keyboard e&ents are a&ailable in LibreOffice #asic:
5e presse%
user presses a key.
5e release%
user releases a key
$'2 LibreOffice 3 Basic %"i&e
#oth e&ents relate to loical key actions and not to physical actions. 6f the user presses se&eral keys to
output a sinle character 8for e,ample) to add an accent to a character9) then LibreOffice #asic only
creates one e&ent.
/ sinle key action on a modification key) such as the Shift key or the /lt key does not create an
independent e&ent.
6nformation about a pressed key is pro&ided by the e&ent object that LibreOffice #asic supplies to the
procedure for e&ent handlin. 6t contains the followin properties:
5eCo%e (short)
code of the pressed key 8default &alues in accordance with
com.sun.star.awt.Oey9
5eChar (String)
character that is entered 8takin the modification keys into consideration9
The followin e,ample uses the Ve.7o-e property to establish if the 4nter key) the Tab key) or one of the
other control keys has been pressed. 6f one of these keys has been pressed) the name of the key 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'( 7se E*en(1Ve.7o-e
7se 'o#1sun1s(r10(1Ve.1,ETN,5
Asg = @,e(urn presse-@
7se 'o#1sun1s(r10(1Ve.1T$2
Asg = @Tb presse-@
7se 'o#1sun1s(r10(1Ve.1"ELETE
Asg = @"e+e(e presse-@
7se 'o#1sun1s(r10(1Ve.1ES7$ME
Asg = @Es'pe presse-@
7se 'o#1sun1s(r10(1Ve.1"3C5
Asg = @"o0n presse-@
7se 'o#1sun1s(r10(1Ve.1NM
Asg = @Np presse-@
7se 'o#1sun1s(r10(1Ve.1LE8T
Asg = @Le)( presse-@
7se 'o#1sun1s(r10(1Ve.1,6GBT
Asg = @,ig&( presse-@
7se E+se
Asg = @7&r'(er @ G E*en(1Ve.7&r G @ en(ere-@
En- Se+e'(
Asg2ox Asg
En- Sub
6nformation about other keyboard constants can be found in the /P6 *eference under the
com.sun.star.awt.Oey roup of constants.
Focus +vents
-ocus e&ents indicate if a control element recei&es or loses focus. You can use these e&ents to) for e,ample)
determine if a user has finished processin a control element so that you can update other elements of a
dialo. The followin focus e&ents are a&ailable:
When recei3ing !ocus
element recei&es focus
When losing !ocus
element loses focus
Chapter $2 4orms $'3
The E*en( objects for the focus e&ents are structured as follows:
-ocus-lags (short)
cause of focus chane 8default &alue in accordance with
com.sun.star.awt.-ocus7hane*eason9
Ne1t-ocus (.b6ect)
object that recei&es focus 8only for the C&en +osing )o'us e&ent9
)emporar (Boolean)
the focus is temporarily lost
Control +le%ent.#pecific +vents
6n addition to the precedin e&ents) which are supported by all control elements) there are also some control
element@specific 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 chanes
Item Status Change%
the status of a control element chanes
)e1t mo%i!ie%
the te,t of a control element chanes
When initiating
an action that can be performed when the control element is triered 8for
e,ample) a button is pressed9
%hen you work with e&ents) note that some e&ents) such as the C&en ini(i(ing e&ent) can be initiated
each time you click the mouse on some control elements 8for e,ample) on radio buttons9. 1o action is
performed to check if the status of the control element has actually chaned. To a&oid such Vblind e&entsW)
sa&e the old control element &alue in a lobal &ariable) and then check to see if the &alue has chaned when
an e&ent is e,ecutin.
The C&en ini(i(ing e&ent is also noteworthy for the followin reasons:
This e&ent is initiated by either a key@press or a mouse button. Thus) it pro&ides a consistent interface for
users who na&iate by mouse or by keyboard.
%hen the ,epe( property of a command button is set to True) this e&ent is the one which is repeatedly
sent) as lon as the trierin action 8key down or mouse@button down9 remains in effect.
The properties for the 6(e# S((us 7&nge- e&ent are:
Selecte% (long)
currently selected entry
(ighlighte% (long)
currently hihlihted entry
ItemI% (long)
6D of entry
*ialog Control +le%ents
LibreOffice #asic reconi<es a rane of control elements which can be di&ided into the followin roups:
$'# LibreOffice 3 Basic %"i&e
+ntry fields !uttons #election lists Other
Te,t fields Standard buttons List bo,es Scrollbars 8hori<ontal and &ertical9
Date fields 7heckbo,es 7ombo@bo,es -ields of roups
Time fields *adio #uttons Tree 7ontrol Proress bars
1umerical fields Di&idin lines 8hori<ontal and
&ertical9
7urrency fields $raphics
-ields adoptin any format -ile selection fields
!uttons
/ button performs an action when you click it.
The simplest scenario is for the button to trier a C&en 6ni(i(ing e&ent when it is clicked by a user.
You can also link another action to the button to close a dialo usin the Mus&2u((onT.pe property. %hen
you click a button that has this property set to the &alue of G) the dialo remains unaffected. 6f you click a
button that has this property set to the &alue of H) the dialo is closed) and the Exe'u(e method of the dialo
returns the &alue H 8dialo se5uence has been ended correctly9. 6f the Mus&2u((onT.pe has the &alue of ")
the dialo is closed and the Exe'u(e method of the dialo returns the &alue G 8dialo closed9. 6n the Dialo
4ditor) the property &alues are shown symbolically) as "e)u+( 8G9) 3/. 8H9) and 7n'e+ 8"9.
The followin are some of the properties that are a&ailable throuh the button model:
"o%el.Bac'groun%Color (long)
color of backround
"o%el.De!aultButton (Boolean)
The button is used as the default &alue and responds to the 4nter key if it has no
focus
"o%el.-ontDescriptor (struct)
structure that specifies the details of the font to be used 8in accordance with
com.sun.star.awt.-ontDescriptor structure9
"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)
te,t color of the control element
"o%el.(elp)e1t (String)
help te,t that is displayed when you mo&e the mouse cursor o&er the control
element
"o%el.(elpU$L (String)
0*L of the online help for the correspondin control element
2ushButton)pe (short)
action that is linked to the button 8G: no action) H: OO) ": 7ancel9
Option !uttons
These buttons are enerally used in roups and allow you to select from one of se&eral options. %hen you
select an option) all of the other options in the roup are deacti&ated. This ensures that at any one time) only
one option button is set.
Chapter $2 4orms $''
/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 followin properties from the model of the option buttons:
structure with details of the font to be used 8in accordance with
com.sun.star.awt.-ontDescriptor9
label that is displayed on the control element
control element can be printed
"o%el.State (Short)
if this property is e5ual to H) the option is acti&ated) otherwise it is deacti&ated
te,t color of control element
help te,t that is displayed when the mouse cursor rests o&er the control element
0*L of online help for the correspondin control element
To combine se&eral option buttons in a roup) you must position them one after another in the acti&ation
se5uence without any aps 8Ao-e+1Tb6n-ex property,described as Order in the dialo editor9. 6f the
acti&ation se5uence is interrupted by another control element) then LibreOffice automatically starts with a
new control element roup that can be acti&ated reardless of the first roup of control elements.
Note
0nlike ;#/) you cannot insert option buttons in a roup of control elements in LibreOffice
#asic. The roupin of control elements in LibreOffice #asic is only used to ensure a &isual
di&ision by drawin a frame around the control elements.
Checkbo,es
7heckbo,es are used to record a Yes or 1o &alue and dependin on the mode) they can adopt two or three
states. 6n addition to the Yes and 1o states) a check bo, can ha&e an in@between state if the correspondin
Yes or 1o status has more than one meanin or is unclear.
7heckbo,es pro&ide the followin properties:
State (Short)
state of the checkbo, 8G: no) H: yes) ": in@between state9
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 in@
between state
The model object of a checkbo, pro&ides the followin properties:
$'+ LibreOffice 3 Basic %"i&e
structure with details of the font used 8in accordance with
label for the control element
"o%el.State (Short)
state of the checkbo, 8G: no) H: yes) ": in@between state9
the control element can be reached with the Tab key
help te,t that is displayed when you rest the mouse cursor o&er the control
element
Te,t Fields
Te,t fields allow users to type numbers and te,t. The com.sun.star.awt.0no7ontrol4dit. ser&ice forms the
basis for te,t fields.
/ te,t field can contain one or more lines and can be edited or blocked for user entries. Te,t fields can also
be used as special currency and numerical fields as well as screen fields for special tasks. /s these control
elements are based on the Nno7on(ro+E-i( 0no ser&ice) their proram@controlled handlin is similar.
Te,t fields pro&ide the followin properties:
)e1t (String)
current te,t
Selecte%)e1t (String)
currently hihlihted te,t
Selection (Struct)
read@only hihlihtin of details 8structure in accordance with
com.sun.star.awt.Selection) with the Ain and Ax properties to specify the start
and end of the current hihlihtin9
"a1)e1tLen (short)
ma,imum number of characters that you can type in the field
0%itable (Boolean)
True acti&ates the option for enterin te,t) 8+se blocks the entry option 8the
property cannot be called up directly but only throuh 6sE-i(b+e9
Is0%itable (Boolean)
the content of the control element can be chaned) read@only
The followin properties are pro&ided throuh the associated model object:
Chapter $2 4orms $',
"o%el.Align (short)
orientation of te,t 8G: left@alined) H: centered) ": riht@alined9
color of the backround of the control element
"o%el.Bor%er (short)
type of border 8G: no border) H: !D border) ": simple border9
"o%el.0choChar (String)
echo character for password fields
structure with details of font used 8in accordance with
"o%el.(ar%LineBrea's (Boolean)
automatic line breaks are permanently inserted in the control element te,t
"o%el.(Scroll (Boolean)
the te,t has a hori<ontal scrollbar
"o%el."a1)e1tLen (Short)
ma,imum lenth of te,t) where G corresponds to no lenth limit
"o%el."ultiLine (Boolean)
permits entry to spans se&eral lines
"o%el.$ea%.nl (Boolean)
the content of the control element is read@only
"o%el.)e1t (String)
te,t associate with the control element
"o%el.VScroll (Boolean)
the te,t has a &ertical scrollbar
help te,t that is displayed when the mouse cursor rests o&er the control element
ist !o,es
List bo,es 8com.sun.star.awt.0no7ontrolList#o, ser&ice9 support the followin properties:
$+> LibreOffice 3 Basic %"i&e
ItemCount (Short)
number of elements) read@only
Selecte%Item (String)
te,t of hihlihted entry) read@only
Selecte%Items (Arra .! Strings)
data field with hihlihted entries) read@only
Selecte%Item2os (Short)
number of the entry hihlihted at present) read@only
Selecte%Items2os (Arra o! Short)
data field with the number of hihlihted entries 8for lists which support multiple
selection9) read@only
"ultiple"o%e (Boolean)
True acti&ates the option for multiple selection of entries) 8+se blocks multiple
selections 8the property cannot be called up directly but only throuh
6sAu+(ip+eAo-e9
Is"ultiple"o%e (Boolean)
permits multiple selection within lists) read@only
List bo,es pro&ide the followin methods:
a%%Item (Item# 2os)
enters the strin specified in the 6(e# into the list at the Mos position
a%%Items (ItemArra# 2os)
enters the entries listed in the strin>s 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 hihlihtin for the element specified in the strin 6(e#
dependin on the Se+e'(Ao-e #oolean &ariable
ma'eVisible (2os)
scrolls throuh the list field so that the entry specified with Mos is &isible
The model object of the list bo,es pro&ides the followin properties:
backround color of control element
"o%el.Bor%er (short)
structure with details of font used 8in accordance with
"o%el.LineCount (Short)
number of lines in control element
Chapter $2 4orms $+$
"o%el."ultiSelection (Boolean)
permits multiple selection of entries
"o%el.Selecte%Items (Arra o! Strings)
list of hihlihted entries
"o%el.StringItemList (Arra o! Strings)
list of all entries
"o%el.$ea%.nl (Boolean)
automatically displayed help te,t which is displayed if the mouse cursor is abo&e
the control element
Note
The ;#/ option for issuin list entries with a numerical additional &alue (6(e#"() does
not e,ist in LibreOffice #asic. 6f you want to administer a numerical &alue 8for e,ample a
database 6D9 in addition to the natural lanuae te,t) you must create an au,iliary data field
that administers in parallel to the list bo,.
$+2 LibreOffice 3 Basic %"i&e
#asic $uide
Chapter $2
4orms
For%s
$+2 LibreOffice 3 Basic %"i&e
6n many respects) the structure of LibreOffice forms corresponds to the Dialos. There are) howe&er) a few
key differences:
Dialos appear in the form of one sinle dialo window) which is displayed o&er the document and does not
permit any actions other than dialo processin until the dialo is ended. -orms) on the other hand) are
displayed directly in the document) just like drawin elements.
/ dialo editor is pro&ided for creatin dialos) and this can be found in the LibreOffice #asic de&elopment
en&ironment. -orms are created usin the -orm 7ontrols and the -orm Desin Toolbar directly within the
document.
%hereas the dialo functions are a&ailable in all LibreOffice documents) the full scope of the form functions
are only a&ailable in te,t and spreadsheets.
The control elements of a form can be linked with an e,ternal database table. This function is not a&ailable
in dialos.
The control elements of dialos and forms differ in se&eral aspects.
0sers who want to pro&ide their forms with their own methods for e&ent handlin) should refer to the 7hapter
HH Dialos The mechanisms e,plained there are identical to those for forms.
(orking (ith For%s
LibreOffice forms may contain te,t fields) list bo,es) radio buttons) and a rane of other control elements)
which are inserted directly in a te,t or spreadsheet. The -orm -unctions Toolbar is used for editin forms.
/ LibreOffice form may adopt one of two modes: the draft mode and the display mode. 6n draft mode) the
position of control elements can be chaned and their properties can be edited usin a properties window.
The -orm -unctions Toolbar is also used to switch between modes.
/eter+inin1 Ob?ect 2or+s
LibreOffice positions the control elements of a form at drawin object le&el. The actual object form can be
accessed throuh the -orms list at the drawin le&el. The objects are accessed as follows in te,t documents:
"i# "o' $s 3b:e'(
"i# "r0Mge $s 3b:e'(
"i# 8or# $s 3b:e'(
"o' = T&is7o#ponen(
"r0Mge = "o'1"r0Mge
8or# = "r0Mge18or#s1Ge(2.6n-ex(D)
The Ge(2.6n-ex method returns the form with the inde, number G.
%hen workin with spreadsheets) an intermediate stae is needed for the Sheets list because the drawin
le&els are not located directly in the document but in the indi&idual sheets:
"i# "o' $s 3b:e'(
"i# S&ee( $s 3b:e'(
"i# "r0Mge $s 3b:e'(
"i# 8or# $s 3b:e'(
"o' = T&is7o#ponen(
S&ee( = "o'1S&ee(s1Ge(2.6n-ex(D)
"r0Mge = S&ee(1"r0Mge
8or# = "r0Mge18or#s1Ge(2.6n-ex(D)
/s is already suested by the Ge(2.6n-ex method name) a document may contain se&eral forms. This is
useful) for e,ample) if the contents of different databases are displayed within one document) or if a H:n
database relationship is displayed within a form. The option of creatin sub@forms is also pro&ided for this
purpose.
The Three As,ects of a !ontrol Ele+ent 2or+
/ control element of a form has three aspects:
Chapter $2 4orms $+3
The Modelof the control element is the key object for the LibreOffice #asic@prorammer when workin with
control element forms.
The counterpart to this is the Viewof the control element) which administers the display information.
Since control element forms within the documents are administered like a special drawin element) there is
also a Shape objectwhich reflects the drawin element@specific properties of the control element 8in particular
its position and si<e9.
Accessin1 the Model of !ontrol Ele+ent 2or+s
The models of the control elements of a form are a&ailable throuh the Ge(2.5#e method of the Object
form:
"i# "o' $s 3b:e'(
"i# 8or# $s 3b:e'(
"i# 7(+ $s 3b:e'(
"o' = T&is7o#ponen(
8or# = "o'1"r0Mge18or#s1Ge(2.6n-ex(D)
7(+ = 8or#1ge(2.5#e(@A.Lis(2ox@)
The e,ample determines the model of the A.Lis(2ox control element) which is located in the first form of
the te,t document currently open.
6f you are not sure of the form of a control element) you can use the option for searchin throuh all forms for
the control element re5uired:
"i# "o' $s 3b:e'(
"i# 8or#s $s 3b:e'(
"i# 8or# $s 3b:e'(
"i# 7(+ $s 3b:e'(
"i# 6 s 6n(eger
"o' = T&is7o#ponen(
8or#s = "o'1"r0pge18or#s
8or 6 = D To 8or#s17oun( H 1
8or# = 8or#s1Ge(b.6n-ex(6)
6) 8or#1Bs2.5#e(@A.Lis(2ox@) T&en
7(+ = 8or#1Ge(b.5#e(@A.Lis(2ox@)
Exi( 8un'(ion
En- 6)
5ex( 6
The e,ample uses the Bs2.5#e method to check all forms of a te,t document to determine whether they
contain a control element model called A.Lis(2ox. 6f a correspondin model is found) then a reference to
this is sa&ed in the 7(+ &ariable and the search is terminated.
Accessin1 the Biew of !ontrol Ele+ent 2or+s
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 usin the document controller.
"i# "o' $s 3b:e'(
"i# "o'7r+ $s 3b:e'(
"i# 8or#s $s 3b:e'(
"i# 8or# $s 3b:e'(
"i# 7(+ $s 3b:e'(
"i# 7(+4ie0 $s 3b:e'(
"i# 6 s 6n(eger
"o' = T&is7o#ponen(
"o'7r+ = "o'1ge(7urren(7on(ro++er()
$+# LibreOffice 3 Basic %"i&e
6) 8or#1Bs2.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 e,ample is &ery similar to the code listed in the pre&ious e,ample for determinin a
control element model. 6t uses not only the "o' document object but also the "o'7r+ document controller
object which makes 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 87(+4ie0
&ariable9 of the control element form.
Accessin1 the ha,e Ob?ect of !ontrol Ele+ent 2or+s
The method for accessin the shape objects of a control element also uses the correspondin drawin le&el
of the document. To determine a special control element) all drawin elements of the drawin le&el must be
searched throuh.
"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"r0Mge17oun( H 1
S&pe = "o'1"r0Mge(i)
6) BsNno6n(er)'es(S&pe<
@'o#1sun1s(r1-r0ing1R7on(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 e,ample checks all drawin elements to determine whether they support the
com.sun.star.drawin.Y7ontrolShape interface needed for control element forms. 6f this is the case) the
7on(ro+15#e property then checks whether the name of the control element is A.Lis(2ox. 6f this is true)
the function ends the search.
*eter%ining the #i:e and Position of Control +le%ents
/s already mentioned) the si<e and position of control elements can be determined usin the associated
s&pe object. The control element shape) like all other s&pe objects) pro&ides the SiXe and Mosi(ion
properties for this purpose:
Si4e (struct)
si<e of control element 8com.sun.star.awt.Si<e data structure9
2osition (struct)
position of control element 8com.sun.star.awt.Point data structure9
The followin e,ample shows how the position and si<e of a control element can be set usin the associated
shape object:
"i# S&pe $s 3b:e'(
% 111 6ni(i+iXe S&pe ob:e'(< s pre*ious+. s&o0n 111
Chapter $2 4orms $+'
Moin(1x = 1DDD
Moin(1. = 1DDD
SiXe1Ci-(& = 1DDDD
SiXe1Beig&( = 1DDDD
S&pe1SiXe = SiXe
S&pe1Mosi(ion = Moin(
The s&pe object of the control element must already be known if the code is to function. 6f this is not the
case) it must be determined usin the precedin code.
Control +le%ent For%s
The control elements a&ailable in forms are similar to those of dialos. The selection ranes from simple te,t
fields throuh list and combo bo,es 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.
6n 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 4orms chapter.
Buttons
The model object of a form button pro&ides the followin properties:
Bac'groun%Color (long)
backround color
De!aultButton (Boolean)
the button ser&es as a default &alue. 6n 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 throuh the tabulator button
)abIn%e1 (Long)
position of control element in acti&ation se5uence
-ontName (String)
name of font type
-ont(eight (Single)
heiht of character in points 8pt9
)ag (String)
strin containin additional information) which can be sa&ed in the button for
proram@controlled access
)argetU$L (String)
taret 0*L for buttons of the 0*L type
)arget-rame (String)
name of window 8or frame9 in which Trge(N,L is to be opened when acti&atin
the button 8for buttons of the N,L type9
$++ LibreOffice 3 Basic %"i&e
Label (String)
button label
)e1tColor (Long)
(elp)e1t (String)
automatically displayed help te,t which is displayed if the mouse cursor is abo&e
the control element
(elpU$L (String)
Button)pe (0num)
action that is linked with the button 8default &alue from
com.sun.star.form.-orm#uttonType9
State (Short)
in tole button) H N pushed) G N normal
Throuh 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.-orm#uttonType roup of
constants pro&ides the followin &alues:
2US(
standard button
SUB"I)
end of form entry 8particularly rele&ant for .T+L forms9
$0S0)
resets all &alues within the form to their oriinal &alues
U$L
call of the 0*L defined in Trge(N,L 8is opened within the window which was
specified throuh Trge(8r#e9
The OKand Cancelbutton types pro&ided in dialos are not supported in forms.
O,tion Buttons
The followin properties of an option button are a&ailable throuh its model object:
0nable% (Boolean)
)abstop (Boolean)
the control element can be reached throuh the tab key
)abIn%e1 (Long)
position of control element in the acti&ation se5uence
-ontName (String)
name of font type
-ont(eight (Single)
Chapter $2 4orms $+,
)ag (String)
Label (String)
inscription of button
2rintable (Boolean)
State (Short)
if H) the option is acti&ated) otherwise it is deacti&ated
$e!Value (String)
strin for sa&in additional information 8for e,ample) for administerin data record
6Ds9
)e1tColor (Long)
(elp)e1t (String)
automatically displayed help te,t) which is displayed if the mouse cursor is abo&e
the control element
(elpU$L (String)
The mechanism for roupin option buttons distinuishes between the control elements for dialos and
forms. %hereas control elements appearin one after another in dialos are automatically combined to form
a roup) roupin in forms is performed on the basis of names. To do this) all option buttons of a roup must
contain the same name. LibreOffice combines the rouped control elements into an array so that the
indi&idual buttons of a LibreOffice #asic proram can be reached in the same way.
The followin e,ample shows how the model of a control element roup can be determined.
"i# "o' $s 3b:e'(
"i# 8or#s $s 3b:e'(
"i# 8or# $s 3b:e'(
"i# 7(+ $s 3b:e'(
"i# 6 s 6n(eger
"o' = T&is7o#ponen(
6) 8or#1Bs2.5#e(@A.3p(ions@) T&en
7(+ = 8or#1 Ge(Groupb.5#e(@A.3p(ions@)
Exi( 8un'(ion
En- 6)
5ex( 6
The code corresponds to the pre&ious e,ample for determinin a simple control element model. 6t searches
throuh all forms in the current te,t document in a loop and uses the Bs2.5#e method to check whether
the correspondin form contains an element with the A.3p(ions name it is searchin for. 6f this is the case)
then the model array is accessed usin the Ge(Group2.5#e method 8rather than the Ge(2.5#e method
to determine simple models9.
!hec9boxes
The model object of a checkbo, form pro&ides the followin properties:
$,> LibreOffice 3 Basic %"i&e
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 H) the option is acti&ated) otherwise it is deacti&ated
$e!Value (String)
strin for sa&in additional information 8for e,ample) for administratin data
record 6Ds9
)e1tColor (Long)
(elp)e1t (String)
the control element
(elpU$L (String)
Text 2ields
The model objects of te,t field forms offer the followin properties:
Align (short)
orientation of te,t 8G: left@alined) H: centered) ": riht@alined9
Bor%er (short)
0choChar (String)
echo character for password field
Chapter $2 4orms $,$
-ontName (String)
name of font type
-ont(eight (Single)
(ar%LineBrea's (Boolean)
the automatic line breaks are permanently inserted in the te,t of the control
element
(Scroll (Boolean)
the te,t has a hori<ontal scrollbar
"a1)e1tLen (Short)
ma,imum lenth of te,tF if G is specified) there are no limits
"ultiLine (Boolean)
permits multi@line entries
2rintable (Boolean)
$ea%.nl (Boolean)
0nable% (Boolean)
)abstop (Boolean)
)abIn%e1 (Long)
position of the control element in the acti&ation se5uence
-ontName (String)
name of font type
-ont(eight (Single)
)e1t (String)
te,t of control element
)e1tColor (Long)
VScroll (Boolean)
the te,t has a &ertical scrollbar
(elp)e1t (String)
the control element
(elpU$L (String)
$,2 LibreOffice 3 Basic %"i&e
List Boxes
The model object of the list bo, forms pro&ides the followin properties:
Bor%er (short)
type of border 8G: no border) H: !D frame) ": simple frame9
-ontDescriptor (struct)
structure with details of font to be used 8in accordance with
LineCount (Short)
number of lines of control element
"ultiSelection (Boolean)
permits multiple selection of entries
Selecte%Items (Arra o! Strings)
list of hihlihted entries
StringItemList (Arra o! Strings)
list of all entries
ValueItemList (Arra o! Variant)
list containin additional information for each entry 8for e,ample) for
administratin data record 6Ds9
2rintable (Boolean)
$ea%.nl (Boolean)
0nable% (Boolean)
)abstop (Boolean)
)abIn%e1 (Long)
-ontName (String)
name of font type
-ont(eight (Single)
)ag (String)
strin containin additional information which can be sa&ed in the button for
)e1tColor (Long)
Chapter $2 4orms $,3
(elp)e1t (String)
the control element
(elpU$L (String)
Note
Throuh their 4+ue6(e#Lis( property) list bo, forms pro&ide a counterpart to the ;#/
property) 6(e#"(< throuh which you can administer additional information for
indi&idual list entries.
-urthermore) the followin methods are pro&ided thouh the &iew object of the list bo,:
a%%Item (Item# 2os)
inserts the strin specified in the 6(e# at the Mos position in the list
a%%Items (ItemArra# 2os)
inserts the entries listed in the strin>s 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 hihlihtin for the element specified in the strin
6(e# dependin on the Se+e'(Ao-e &ariable
ma'eVisible (2os)
scrolls throuh the list field so that the entry specified by Mos is &isible
*atabase For%s
LibreOffice forms can be directly linked to a database. The forms created in this way pro&ide all the functions
of a full database front end without re5uirin independent prorammin work.
You can pae throuh and search in the selected tables and 5ueries) as well as chane data records and
insert new data records. LibreOffice automatically ensures that the rele&ant data is retrie&ed from the
database) and that any chanes made are written back to the database.
/ database form corresponds to a standard LibreOffice form. 6n addition to the standard properties) the
followin database@specific properties must also be set in the form:
DataSourceName (String)
name of data source 8refer to Database (ccessF the data source must be lobally
created in LibreOffice9
Comman% (String)
name of table) 5uery) or the SUL select command to which a link is to be made
Comman%)pe (Const)
specifies whether the 7ommand is a table) a 5uery or a SUL command 8&alue
from com.sun.star.sdb.7ommandType enumeration9
The com.sun.star.sdb.7ommandType enumeration co&ers the followin &alues:
)ABL0
Table
;U0$&
Uuery
$,2 LibreOffice 3 Basic %"i&e
C.""AND
SUL command
The database fields are assined to the indi&idual control elements throuh this property:
Data-iel% (String)
name of linked database field
Tables
/nother control element is pro&ided for work with databases) the table control element. This represents the
content of a complete database table or 5uery. 6n the simplest scenario) a table control element is linked to a
database usin the autopilot form) which links all columns with the rele&ant database fields in accordance
with the user specifications.
Chapter $2 4orms $,3
6nde,
"
/rrays
empty arrays "H
simple arrays HK
!
branchin
if...then...else "(
select...case "L
C
charts 8diarams9
!d charts H(G
area charts H("
a,es H'(
a,es title H'K
backround H''
bar charts H("
diaram H''
rids H'J
line charts H("
stacked charts H(H
title) subtitle and leend H'!
wall and floor H'(
comments H"
creatin new documents LI
*
databases
iteration of tables H(K
5ueries H(J
resultset &ariants HLH
debuin tools (J
dialos
access to indi&idual control elements HLL
buttons HI(
checkbo,es HIL
closin dialos HL(
control element@specific e&ents HI'
creatin dialos HL'
dialo control elements HI(
e&ents HLK
focus and tabulator se5uence HLI
keyboard e&ents HI!
list bo,es HIK
mouse e&ents HIH
multi@pae dialos HLJ
name and title HLI
option buttons HIL
parameters HIH
position and si<e HLI
te,t fields HII
drawins
bitmaps H"I
circles and elipses H!"
color radient H"(
duplicatin a pae H"'
fill properties H"(
raphics H!(
roupin objects H!L
hatches H"I
line properties H"J
lines H!!
paes H""
plypolyon shapes H!'
properties of a pae H""
rectanle shapes H!H
renamin paes H"!
rotation and shearin drawin objects H!I
sarchin and replacin H!J
shadow properties H!H
sinle color fills H"(
te,t properties 8drawin objects9 H"K
transparency H"J
+
error handlin
on error instruction !"
resume command !"
F
focus e&ents HI!
forms
checkbo,es HJI
control element forms HJ(
database forms HKH
list bo,es HJK
tables HKH
te,t fields HJJ
workin with forms HJ"
&
lobal &ariables "!

local &ariables ""
Chapter $2 4orms $,'
loops
do...loop "I
for each "I
for...ne,t "I
while...wend "J
M
markers H!
N
numbers
boolean &alues HJ
currency &ariables HI
decimal numnbers HI
double &ariables HL
e,ponential writin style HJ
floats HI
he,adecimal &alues HJ
inteer &ariables HL
lon inteer &ariables HL
octal &alues HJ
sinle &ariables HL
O
operators
comparison operators "(
loical operators "'
mathematical operators "'
other instructions
type...end type !'
with...end with !'
P
pie charts H(!
predefined constants "'
pri&ate &ariables "!
procedures and functions
functions "K
optional parameters !H
procedures "K
recursion !H
proram lines H"
properties of a,es H'L
public domains &arialbes ""
1
runtime library
beep ("
con&ersion functions !J
date and time '!
debu properties (J
displayn messaes (G
en&iron (!
files and directories '(
methods (I
properties (I
readin te,t files 'K
shell ("
Strins 'H
wait and waituntil ("
writin and readin te,t files 'J
$,+ LibreOffice 3 Basic %"i&e
#
spreadsheets documents
backround color and shadows HGI
cell properties HGI
cell ranes HHI
cells and ranes HG!
centerin 8spreadsheets only9 HHL
formattin spreadsheet documents HGI
headers and footers HH"
justification HGJ
pae backround HHG
pae format HHG
pae properties HHG
rows and columns HG"
spreadsheets HGG
Strins JK
ansi character set H(
ascii caharacter set H(
code paes H(
Strins &ariables H(
unicode H(
T
te,t documents
annotations KL
cells KH
chapter name Q number KI
character properties IK
columns KH
current pae KL
date Q time KI
editin tables KG
formattin IJ
insertin control codes J(
more than just te,t JK
number of paes) words and characters K(
pararaph portions II
pararaph properties IK
pararaphs II
pararaphs and pararaph portions IL
replacin te,t portions JI
rows KG
searchin for te,t portions JL
te,t fields K'
te,t frames K"
te,tcursor J"
the dialo editor J
the lanuae of libreoffice basica J
the libreoffice api J
the runtime library J
(
workin with documents
automatic update I"
compression of files L(
document and template types I"
pritin documents LK
sa&in and e,portin documents LJ
star desktop L'
storeasurl method options LJ
style types IH
Chapter $2 4orms $,,
thiscomponent L(
,ml file format L(
workin with &ariables
e,plicit &ariable declaration H'
implicit &airable declaration H!
2>> LibreOffice 3 Basic %"i&e

LibreOffice 3 Basic Guide PDF

Hochgeladen von

Dokumentinformationen

Originaltitel

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

LibreOffice 3 Basic Guide PDF

Hochgeladen von

Copyright:

Verfügbare Formate

LibreOffice 3

Das könnte Ihnen auch gefallen