gs4013-gettingstartedwithmacros

8/11/2019 GS4013-GettingStartedWithMacros

1/22

Getting Started Guide

Chapter 13

Getting Started with MacrosUsing the Macro Recorder and Beyond


2/22


3/22

Contents

Copyright"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" #

Contributors................................................................................................................................. 2

eedbac,..................................................................................................................................... 2

+c,nowledgments........................................................................................................................ 2$ublication date and so!tware *ersion......................................................................................... 2

Note for Mac users"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""#

$ntroduction"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" %

&our first macros""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""%

+dding a macro............................................................................................................................ 7

-ecording a macro...................................................................................................................... 9

-unning a macro......................................................................................................................... :

;iewing and editing macros......................................................................................................... :

-e!ining subroutines with S#5................................................................................................ =>e!ining *ariables using >im................................................................................................... ?ispatch !ramewor,................................................................................................................... 13

ow the macro recorder uses the dispatch !ramewor,.............................................................. 17

6ther options............................................................................................................................. 17

Macro organi*ation"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" '%

4here are macros storedA........................................................................................................ 1B

mporting macros....................................................................................................................... 19

>ownloading macros to import...................................................................................................1:

+ow to run a macro""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""',

Toolbars) menu items and ,eyboard shortcuts........................................................................... 1=


4/22

$ntroduction

+ macro is a sa*ed se@uence o! commands or ,eystro,es that are stored !or later use. +n eampleo! a simple macro is one that DtypesE your address. The %ibre6!!ice macro language is *ery!leible) allowing automation o! both simple and comple tas,s. acros are *ery use!ul when youha*e to repeat the same tas, in the same way o*er and o*er again.

%ibre6!!ice macros are usually written in a language called %ibre6!!ice 5asic) sometimesabbre*iated to 5asic. +lthough you can learn 5asic and write macros) there is a steep learningcur*e to writing macros !rom scratch. The usual methods !or a beginner are to use macros thatsomeone else has written or use the builtFin macro recorder) which records ,eystro,es and sa*esthem !or use.

ost tas,s in %ibre6!!ice are accomplished by Ddispatching a commandE &sending a command()which is intercepted and used. The macro recorder wor,s by recording the commands that aredispatched &see D>ispatch !ramewor,E on page 13(.

&our first macros

Adding a macro

The !irst step in learning macro programming is to !ind and use eisting macros. This sectionassumes that you ha*e a macro that you want to use) which may be in an email) on a web page) ore*en in a boo,. or this eample) the macro in%isting 1 is used. You must create a library andmodule to contain your macro see Dacro organiHationE on page 17!or more in!ormation.

*isting 1 Si$ple $acro that says hello

SubHelloMacro

Print"Hello"

EndSub

%ig)re 1 *i+reOffice Basic Macros dialog

/ Getting Started with Macros


5/22

%ig)re 0 *i+reOffice Basic Macro Organier dialog

%ig)re 3 2ntegrated (e+)gging n,iron$ent dialog

#se the !ollowing steps to create a library to contain your macro'

1( #se Tools > Macros > rgani*e Macros > !ibreffice 0asicto open the %ibre6!!ice5asic acro dialog &igure 1(.

2( Clic, rgani*erto open the 5asic acro 6rganiHer dialog &igure 2( and select the*i+rariestab.

3( Set the *ocationto My Macros 4 (ialogs) which is the de!ault location.

7( Clic, Newto open the "ew %ibrary dialog.

B(


6/22

=( Select odule1) or the new module that you created) and clic, -ditto open the ntegrated>ebugging < is a tet editor included with %ibre6!!icethat allows you to create and edit macros.

?( 4hen a new module is created) it contains a comment and an empty macro named ain)which does nothing.

10( +dd the new macro either be!ore Sub ain or a!ter Macros > rgani*e Macros > !ibreffice 0asic"

1B( Select a macro and then clic, 2un.

*isting 0 Mod)le1 after adding the new $acro.REM ***** BASIC *****

SubHelloMacro

Print"Hello"

EndSub

SubMain

EndSub

2ecording a macro

! you ha*e to repeatedly enter the same in!ormation) you can copy this in!ormation a!ter it hasbeen entered into your document !or the !irst time) then paste the in!ormation into your documenteach time you want to use it. owe*er) i! something else is copied to the clipboard) the contents onthe clipboard are changed. This means that you ha*e reFcopy your repeated in!ormation. Too*ercome this problem) you can create a macro that enters your repeated in!ormation.

Noteor some types o! in!ormation that you want to repeatedly enter into a document) itmaybe more con*enient to create an +utoTet !ile. See the 6riter G)ide Chapter 36oring with 'e7t!or more in!ormation.

1( a,e sure macro recording is enabled by going to Tools > ptions > !ibreffice >Advancedon the main menu bar and selecting the option -nable macro recording. 5yde!ault) this !eature is turned o!! when %ibre6!!ice was installed on your computer.

2( Go to Tools > Macros > 2ecord Macroon the main menu bar to start recording a macro.+ small dialog is displayed indicating that %ibre6!!ice is recording a macro.

3( Type the desired in!ormation or per!orm an appropriate series o! operations. +s aneample) type your name.

7( Clic, 3top 2ecordingon the small -ecording dialog to stop recording and the %ibre6!!ice5asic acros dialog opens &igure 1on page 7(.

B( 6pen the library container My Macros.

9( ind the library named Standardin y acros. "ote that e*ery library container has a

library named Standard.

8 Getting Started with Macros


7/22

:( Select the Standard library and clic, New Moduleto create a new module to contain themacro. This opens the "ew odule dialog &igure 7(.

%ig)re / 9ew Mod)le dialog

=( Type a descripti*e name !or the new module) !or eample Recordedand clic, 1to createthe module. The %ibre6!!ice 5asic acros dialog now displays the name o! the new modulein the Standard library.

?( n the Macro nametet bo) type a name !or the macro you ha*e Iust recorded) !oreample nterMy9a$e.

10( Clic, 3aveto sa*e the macro and close the %ibre6!!ice 5asic acros dialog.

11( ! you !ollowed all o! the abo*e steps) the Standard library now contains a module named

-ecorded and this module contains the Macros > rgani*e Macros > !ibreffice 0asicon the mainmenu bar to open the %ibre6!!ice 5asic acros dialog) select your macro and clic, 2un.

%ig)re & Macro Selector dialog

4iewing and editing macros

To *iew andor edit the macro that you created'

1( Go to Tools > Macros > rgani*e Macros > !ibreffice 0asicto open the %ibre6!!ice5asic acros dialog.

5o)r first $acros :


8/22

2( Select your new macro


9/22

+nother ,ind o! subroutine is called a !unction which is a subroutine that returns a *alue.unctions are de!ined by the ,eyword #"CT6" at the beginning. owe*er) recordedmacros in %ibre6!!ice do not accept !unctions.

Defining variables using Dim

You can write in!ormation on a piece o! paper so that you can loo, at it later. + *ariable) li,e a piece

o! paper) contains in!ormation that can be changed and read. >im originally in 5+SC stood !or>imension and was used to de!ine the dimensions o! an array. The dim statement used in theect. 6ther common *ariable types include string) integer) and date. + third *ariable) namedargs1?is an array o! property *alues. + *ariable o! type arrayallows a single *ariable to containmultiple *alues) similar to storing multiple pages in a single boo,. ;alues in an array are usuallynumbered starting !rom Hero. The number in the parentheses indicates the highest usable numberto access a storage location. n this eample) there is only one *alue) and it is numbered Hero.

Exlaining macro codeThe !ollowing is an eplanation o! the coding used in the


10/22

This is where the magic happens. The dispatch helper sends a dispatch to the document !rame&stored in the *ariable named document( with the command .uno'nsertTet. The net twoarguments) !rame name and search !lags) are beyond the scope o! this document. The lastargument is the array o! property *alues to be used while eecuting the command nsertTet.

end sub

The last line o! the code ends o! the subroutine.

Creating a macro

4hen creating a macro) it is important to as, two @uestions be!ore recording'

1( Can the tas, be written as a simple set o! commandsA

2( Can the steps be arranged so that the last command lea*es the cursor ready !or the netcommand or entering tet or data into the documentA

A more complicated e.ample of a macro

+ common tas, is to copy rows and columns o! data !rom a web site and !ormat them as a table in

a tet document as !ollows'

1( Copy the data !rom the web site to the clipboard.

2( To a*oid strange !ormatting and !onts) paste the tet into a 4riter document as un!ormattedtet.

3( -e!ormat the tet with tabs between columns so that it can be con*erted into a table usingTable > Convert > Te.t to Tableon the main menu bar.

>6"TL"64 The !ont weight is not speci!ied,nown.

T" speci!ies a B0M !ont weight.

#%T-+%GT speci!ies a 90M !ont weight.

%GT speci!ies a :BM !ont weight.

S


11/22

The data can be cleaned up in se*eral ways) all o! them easy to accomplish. The eample gi*enbelow uses ,eystro,es that assume the cursor is at the start o! the line with the tet T".

1( a,e sure macro recording is enabled by going to Tools > ptions > !ibreffice >Advancedon the main menu bar and selecting the option -nable macro recording. 5yde!ault) this !eature is turned o!! when %ibre6!!ice was installed on your computer.

2( Go to Tools > Macros > 2ecord Macroon the main menu bar to start recording.

3( $ress Ctrl!Right rrowto mo*e the cursor to the start o! Dspeci!iesE.

7( $ress Bacspacetwice to remo*e the tab and the space.

B( $ress 'a+to add the tab without the space a!ter the constant name.

9( $ress (eleteto delete the lower case s and then press Shift!Sto add an upper case S.

:( $ress Ctrl!Right rrowtwice to mo*e the cursor to the start o! the number.

=( $ress Ctrl!Shift!Right rrowto select and mo*e the cursor be!ore the M sign.

?( $ress Ctrl!Cto copy the selected tet to the clipboard.

10( $ress ndto mo*e the cursor to the end o! the line.

11( $ress Bacspacetwice to remo*e the two trailing spaces.

12( $ress o$eto mo*e the cursor to the start o! the line.13( $ress Ctrl!Dto paste the selected number to the start o! the line.

17( $asting the *alue also pasted an etra space) so press Bacspaceto remo*e the etraspace.

1B( $ress 'a+to insert a tab between the number and the name.

19( $ress o$eto mo*e to the start o! the line.

1:( $ress down arrowto mo*e to the net line.

1=( Stop recording the macro and sa*e the macro) see D-ecording a macroE on page 9.

t ta,es much longer to read and write the steps than to record the macro. 4or, slowly and thin,about the steps as you do them. 4ith practice this becomes second nature.

The generated macro code in%isting 7has been modi!ied to contain the step number in thecomments to match the code to the step abo*e.

*isting / Copying n)$eric ,al)e to start of the col)$n.

subCopyNum#oCol,rem -------------------------------------------------------------rem define variables

dimdocument asobjectdimdispatcerasobjectrem -------------------------------------------------------------rem !et access to te document

document "#isComponent$CurrentController$%ramedispatcer"create&noService'(com$sun$star$frame$)ispatcelper( +

rem '5+ /ress Ctrl+Right Arrowto move te cursor to te start of 6specifies7$

dispatcer$e1ecute)ispatc'document3($uno48o#oNe1t9ord(3((33Array'++

rem ':+ /ress Backspacet.ice to remove te tab and te space$

dispatcer$e1ecute)ispatc'document3($uno4S.Bac;space(3((33Array'++

rem -------------------------------------------------------------


rem '


12/22

dimar!s:'+asne.com$sun$star$beans$/roperty0aluear!s:'+$Name"(#e1t(ar!s:'+$0alue"CR='>+

dispatcer$e1ecute)ispatc'document3($uno4Insert#e1t(3((33ar!s:'++

rem '?+ /ress Deleteto delete te lo.er case s $$$$

dispatcer$e1ecute)ispatc'document3($uno4)elete(3((33Array'++

rem '?+ $$$ and ten press Shift+Sto add an upper case S$

dimar!s?'+asne.com$sun$star$beans$/roperty0aluear!s?'+$Name"(#e1t(ar!s?'+$0alue"(S(

dispatcer$e1ecute)ispatc'document3($uno4Insert#e1t(3((33ar!s?'++

rem '@+ /ress Ctrl+Right Arrowt.ice to move te cursor to te number$

dispatcer$e1ecute)ispatc'document3($uno48o#oNe1t9ord(3((33Array'++

rem -------------------------------------------------------------dispatcer$e1ecute)ispatc'document3($uno48o#oNe1t9ord(3((33Array'++

rem '+ /ress Ctrl+Shift+Right Arrowto select te number$

dispatcer$e1ecute)ispatc'document3($uno49ordRi!tSel(3((33Array'++

rem '>+ /ress Ctrl+C to copy te selected te1t to te clipboard$

dispatcer$e1ecute)ispatc'document3($uno4Copy(3((33Array'++

rem ',+ /ress Endto move te cursor to te end of te line$

dispatcer$e1ecute)ispatc'document3($uno48o#oEndfine(3((33Array'++

rem ',,+ /ress Backspacet.ice to remove te t.o trailin! spaces$


rem -------------------------------------------------------------


rem ',D+ /ress Hometo move te cursor to te start of te line$

dispatcer$e1ecute)ispatc'document3($uno48o#oStartfine(3((33Array'++

rem ',5+ /ress Ctrl+Vto paste te selected number to te start of te line$

dispatcer$e1ecute)ispatc'document3($uno4/aste(3((33Array'++

rem ',:+ /ress Backspaceto remove te e1tra space$dispatcer$e1ecute)ispatc'document3($uno4S.Bac;space(3((33Array'++

rem ',


13/22

dimar!s,>',+asne.com$sun$star$beans$/roperty0aluear!s,>'+$Name"(Count(ar!s,>'+$0alue",ar!s,>',+$Name"(Select(ar!s,>',+$0alue"false

dispatcer$e1ecute)ispatc'document3($uno48o)o.n(3((33ar!s,>'++

endsub

Cursor mo*ements are used !or all operations &as opposed to searching(. ! run on the>6"TL"64 line) the word weightis mo*ed to the !ront o! the line) and the !irst DTheE is changedto DSheE. This is not per!ect) but you should not run the macro on the lines that did not ha*e theproper !ormat. You need to do these manually.

2unning a macro 5uickly

t is tedious to repeatedly run the macro using Tools > Macros > 2un Macroon the main menubar when the macro can be run !rom the >< &igure 3on page B(.

1( Go to Tools > Macros > rgani*e Macros > !ibreffice 0asicon the main menu bar to

open the 5asic acro dialog &igure 1on page 7(.2( Select your macro and clic, -ditto open the macro in the >


14/22

+ow the macro recorder uses the dispatch framework

The macro recorder records the generated dispatches. The recorder is relati*ely simple tool to useand the same commands that are issued are recorded !or later use. The problem is that not alldispatched commands are complete. or eample) inserting an obIect generates the !ollowingcode'

dispatcer$e1ecute)ispatc'document3($uno4Insertbject(3 ((33Array'++

t is not possible to speci!y what ,ind o! obIect to create or insert. ! an obIect is inserted !rom a !ile)you cannot speci!y which !ile to insert.

-ecording a macro and using Tools > ptionson the main menu bar to open and modi!ycon!iguration items) the generated macro does not record any con!iguration changes. n !act) thegenerated code is commented so it will not e*en be run.

rem dispatcer$e1ecute)ispatc'document3

($uno4ptions#ree)ialo!(3 ((3 3 Array'++

! a dialog is opened) a command to open the dialog is li,ely to be generated. +ny wor, done insidethe dialog is not usually recorded. !ile. You ne*er ,now !or certainwhat will wor, unless you try it. or eample) the actions !rom the search dialog are properlycaptured.

ther options

4hen the macro recorder is not able to sol*e a speci!ic problem) the usual solution is to write codeusing the %ibre6!!ice obIects. #n!ortunately) there is a steep learning cur*e !or these %ibre6!!iceobIects. t is usually best to start with simple eamples and then increase the scope o! macros asyou learn more. %earning to read generated macros is a good place to start.

! you record Calc macros) and the recorder cancorrectly generate a macro) there is an addFina*ailable which con*erts Calc macros when they are recorded. The !inal code manipulates%ibre6!!ice obIects rather than generating dispatches. This can be *ery use!ul !or learning theobIect model and can be downloaded directly !rom the web site'

http'www.paoloFmanto*ani.orgdownloads>ispatchTo+pi-ecorder

Macro organi*ation

n %ibre6!!ice) macros are grouped in modules) modules are grouped in libraries) and libraries aregrouped in library containers. + library is usually used as a maIor grouping !or either an entire

category o! macros) or !or an entire application. odules usually split !unctionality) such as userinteraction and calculations. ndi*idual macros are subroutines and !unctions.igure :shows aneample o! the hierarchical structure o! macro libraries in %ibre6!!ice.

Go to Tools > Macros > rgani*e Macros > !ibreffice 0asicon the main menu bar to open the%ibre6!!ice 5asic acros dialog &igure 1 on page 7(. +ll a*ailable library containers are shown inthe Macro fro$list.


15/22

#nless your macros are applicable to a single document) and only to a single document) yourmacros will probably be stored in the y acros container. The y acros container is stored inyour user area or home directory.

%ig)re : Macro *i+rary hierarchy

! a macro is contained in a document) then a recorded macro will attempt to wor, on thatdocument because it primarily uses DThisComponentE !or its actions.


16/22

stored in ibreffice:userbasic. Macros > rgani*e 6ialogson the main menu bar to open the %ibre6!!ice acro

6rganiHer dialog &igure 2on page B(. +lternati*ely) go to Tools > Macros > rgani*e Macros >!ibreffice 0asicon the main menu bar to open the %ibre6!!ice acros dialog &igure 1on page7( and then clic, the rgani*erbutton.

$mporting macros

The %ibre6!!ice acro 6rganiHer dialog allows you to import macro libraries into your document aswell as creating) deleting) and renaming libraries) modules) and dialogs.

1( Select the library container to use and then clic, $mportto import macro libraries &igure 2on page B(.

2( "a*igate to the directory containing the library to import &igure =(. There are usually two

!iles !rom which to choose) dialog.lb and script.lb. t does not matter which o! these two!iles you select both will be imported. acros can be stored in libraries inside %ibre6!!icedocuments. Select a document rather than a directory on dis, to import libraries containedin a document.

Note You cannot import the library named Standard.

%ig)re = 9a,igating to a $acro li+rary

Tip

6n a computer operating %inu) the %ibre6!!ice speci!ic !iles are stored in the homedirectory o! a user in a directory whose name begins with a period. >irectories and!iles with names beginning with a period are normally hidden and not shown in anormal selection dialog. To open hidden !olders and !iles) press Ctrl-to show

hidden !olders and !iles not normally shown and na*igate as usual.

18 Getting Started with Macros


17/22

3( Select a !ile and clic, pento continue and open the mport %ibraries dialog &igure ?(.

%ig)re @ Choose li+rary i$port options

7( Select the !ollowing options !or importing libraries'

a( ! no options are selected) the library is copied to your user macro directory. owe*er) i!the library you are importing has the same name and you are importing into the samelocation) it will not be copied.

b( Select 2eplace e.isting librariesi! the library you want to import has the same nameand you want to replace the eisting library.

c( Select $nsert as referencei! you want to use the library as re!erence) but not import thelibrary into your document. 4hen a library is used as a re!erence) it remains in itscurrent location and is read only.

B( Clic, 1to import the macro library you selected.

6ownloading macros to import

acros are a*ailable !or download. Some macros are contained in documents) some as regular!iles that you must select and import) and some as macro tet that should be copied and pastedinto the 5asic >


18/22

+ow to run a macro

+lthough you can use Tools > Macros > 2un Macroto run all macros) this is not e!!icient !or!re@uently run macros. See D-unning a macroE on page :!or more in!ormation.

+ more common techni@ue !or !re@uently used macros is to assign the macro a toolbar icon) menuitem) ,eyboard shortcut) or a button embedded in a document. 4hile choosing a method) it is also

good to as, @uestions such as' Should the macro be a*ailable !or only one document) or globally !or all documentsA

s the macro !or a speci!ic document type) such as a Calc documentA

ow !re@uently will the macro be usedA

The answers will determine where to store the macro and how to ma,e it a*ailable. or eample)you will probably not add a rarely used macro to a toolbar. To help determine your choices) seeTable 2.

'a+le 0. Methods for starting a $acro

!"e Libre#ffice Document !"e Document

Toolbar "o Yes Yes

enu "o Yes Yes

Shortcut Yes Yes "o


19/22

%ig)re 1A Men)s page in C)sto$ie dialog

-vents

n %ibre6!!ice) when something happens it is that has an e*ent occurred. or eample) opening adocument) pressing a ,ey) or mo*ing the mouse cursor. %ibre6!!ice allows e*ents to cause amacro to be called the macro is then called an e*ent handler. ull co*erage o! e*ent handlers iswell beyond the scope o! this document) but a little ,nowledge can accomplish much.

Caution 5e care!ul when you con!igure an e*ent handler. or eample) assume that youwrite an e*ent handler that is called e*ery time that a ,ey is pressed) but you ma,e amista,e so the e*ent is not properly handled. 6ne possible result is that your e*ent

handler will consume all ,ey presses) !orcing you to !orcibly terminate %ibre6!!ice.

1( Go to Tools > Customi*eon the main menu bar to open the CustomiHe dialog and selectthe ocument e*ent to call a speci!ic macro. The macrothen per!orms certain setup tas,s !or the document. Select the desired e*ent and clic,Macroto open the acro Selector dialog &igure Bon page :(.

7( Select the desired macro and clic, 1to assign the macro to the e*ent. The


20/22

%ig)re 11 ,ents page in C)sto$ie dialog

any obIects in a document can be set to call macros when e*ents occur. The most common useis to add a control) such as a button) into a document.


21/22

/riting macros without the recorder

The eamples co*ered in this chapter are created using the macro recorder and the dispatcher.You can also write macros that directly access the obIects that comprise %ibre6!!ice i! you arecon!ident in writing computer code. n other words) you can create a macro that directlymanipulates a document.

>irectly manipulating %ibre6!!ice internal obIects is an ad*anced topic that is beyond the scope o!this chapter. + simple eample) howe*er) demonstrates how this wor,s.

*isting 8 ppend the te7t ;ello< to the c)rrent doc)$ent.

SubAppendello )imo)oc )ims#e1tService= )imoCursREM #isComponent refers to te currently active document$

o)oc "#isComponent

REM 0erify tat tis is a te1t document s#e1tService "(com$sun$star$te1t$#e1t)ocument( IfN#o)oc$supportsService's#e1tService+#en Ms!Bo1 (#is macro only .or;s .it a te1t document( E1itSub EndIfREM 8et te vie. cursor from te current controller$

oCurs "o)oc$currentController$!et0ie.Cursor'+REM Move te cursor to te end of te document

oCurs$!otoEnd'%alse+REM Insert te1t (ello( at te end of te document

oCurs$#e1t$insertStrin!'oCurs3(ello(3%alse+EndSub

Finding more information

"umerous resources are a*ailable that pro*ide help with writing macros. #se +elp > !ibreffice+elpto open the %ibre6!!ice help pages. The upper le!t corner o! the %ibre6!!ice help systemcontains a dropFdown list that determines which help set is displayed. To *iew the help !or 5asic)choose *i+reOffice Basic!rom this list.

$ncluded material

any ecellent macros are included with %ibre6!!ice. #se Tools > Macros > rgani*e Macros >!ibreffice 0asicto open the acro dialog. ebug moduleOsome good eamples include 4ritedbgn!o&document( andprintdbgn!o&sheet(.

nline resources

The !ollowing lin,s and re!erences contain in!ormation regarding macro programming'

http'as,.libreo!!ice.org&a P Q + site where *olunteers answer @uestions related to %ibre6!!ice(

%inding $ore infor$ation 01
http://ask.libreoffice.org/http://ask.libreoffice.org/http://ask.libreoffice.org/


22/22

gs4013-gettingstartedwithmacros

Documents