OpenOffice.org Macros Explained.pdf - Andrew Pitonyak

672 Pages·2016·7.38 MB·English

by  Andrew Pitonyak

OpenOffice.org Macros Explained
OOME Third Edition
Last Modified
Saturday, April 30, 2016 at 09:05:51 AM
Document Revision: 567
General Information
The contents of this document is Copyright 2011 - 2014 by Andrew D. Pitonyak. I will make
a final license decision when I am finished.
I created a second edition that was never released, which is why I refer to this book as the
third edition.
I have been repeatedly asked about the cover page so.... I am neither an artist nor a designer,
the cover was created by Amanda Barham (see http://www.amandabarham.com). She did an
awesome job.
Many people contributed to this document in one form or another. Feedback from community
members helps greatly. For reasons I don't understand, my wife allows me to take time away
from my family to work on this document, so, I suppose that the person to really thank is her
(send her enough money that she can get a fully body massage and she may force me to work
on this document).
While taking this document to the latest version, many errors, corrections, and suggestions
were provided by Volker Lenhardt who is providing a full translation into German. This
document has been greatly improved based on his work.
Thank you Volker Lenhardt (https://www.uni-due.de/~abi070/ooo.html).
Table of Contents
General Information...................................................................................................................1
Table of Contents........................................................................................................................i
 1. Introduction and housekeeping...........................................................................................13
 1.1. Comments from the author..........................................................................................13
 1.2. Environment and comments........................................................................................13
 2. Getting Started....................................................................................................................14
 2.1. Macro storage..............................................................................................................14
 2.1.1. Library container.................................................................................................14
 2.1.2. Libraries...............................................................................................................15
 2.1.3. Modules and dialogs............................................................................................16
 2.1.4. Key points............................................................................................................16
 2.2. Creating new modules and libraries............................................................................16
 2.3. Macro language...........................................................................................................18
 2.4. Create a module in a document...................................................................................18
 2.5. Integrated Debugging Environment............................................................................21
 2.6. Enter the macro...........................................................................................................24
 2.7. Run a macro................................................................................................................25
 2.8. Macro security.............................................................................................................25
 2.9. Using breakpoints........................................................................................................28
 2.10. How libraries are stored............................................................................................28
 2.11. How documents are stored........................................................................................29
 2.12. Conclusion.................................................................................................................30
 3. Language Constructs...........................................................................................................31
 3.1. Compatibility with Visual Basic.................................................................................32
 3.2. Compiler options and directives..................................................................................33
 3.3. Variables.....................................................................................................................33
 3.3.1. Constant, subroutine, function, label, and variable names..................................33
 3.3.2. Declaring variables..............................................................................................34
 3.3.3. Assigning values to variables..............................................................................36
 3.3.4. Boolean variables are True or False....................................................................36
 3.3.5. Numeric variables................................................................................................37
Integer variables.........................................................................................................38
Long Integer variables...............................................................................................39
Currency variables.....................................................................................................39
Single variables..........................................................................................................40
Double variables........................................................................................................40
 3.3.6. String variables contain text................................................................................40
 3.3.7. Date variables......................................................................................................41
 3.3.8. Create your own data types.................................................................................42
 3.3.9. Declare variables with special types....................................................................43
 3.3.10. Object variables.................................................................................................44
i
3.3.11. Variant variables................................................................................................44
 3.3.12. Constants...........................................................................................................45
 3.4. The With statement.....................................................................................................46
 3.5. Arrays..........................................................................................................................47
 3.5.1. Changing the dimension of an array....................................................................49
 3.5.2. The unexpected behavior of arrays......................................................................51
 3.6. Subroutines and functions...........................................................................................53
 3.6.1. Arguments...........................................................................................................54
Pass by reference or by value....................................................................................54
Optional arguments....................................................................................................57
Default argument values............................................................................................58
 3.6.2. Recursive routines...............................................................................................58
 3.7. Scope of variables, subroutines, and functions...........................................................59
 3.7.1. Local variables defined in a subroutine or function............................................60
 3.7.2. Variables defined in a module.............................................................................60
Global........................................................................................................................61
Public.........................................................................................................................61
Private or Dim............................................................................................................62
 3.8. Operators.....................................................................................................................62
 3.8.1. Mathematical and string operators......................................................................63
Unary plus (+) and minus (­).....................................................................................64
Exponentiation (^).....................................................................................................64
Multiplication (*) and Division (/)............................................................................65
Remainder after division (MOD)...............................................................................65
Integer division (\).....................................................................................................66
Addition (+), subtraction (­), and string concatenation (& and +).............................67
 3.8.2. Logical and bit­wise operators............................................................................67
AND...........................................................................................................................70
OR..............................................................................................................................70
XOR...........................................................................................................................71
EQV...........................................................................................................................71
IMP............................................................................................................................72
NOT...........................................................................................................................73
 3.8.3. Comparison operators..........................................................................................73
 3.9. Flow control................................................................................................................74
 3.9.1. Define a label as a jump target............................................................................74
 3.9.2. GoSub..................................................................................................................74
 3.9.3. GoTo....................................................................................................................75
 3.9.4. On GoTo and On GoSub.....................................................................................75
 3.9.5. If Then Else.........................................................................................................76
 3.9.6. IIf.........................................................................................................................77
ii
3.9.7. Choose.................................................................................................................77
 3.9.8. Select Case...........................................................................................................78
Case expressions........................................................................................................78
If Case statements are easy, why are they frequently incorrect?...............................79
Writing correct Case expressions..............................................................................80
 3.9.9. While ... Wend.....................................................................................................82
 3.9.10. Do ... Loop.........................................................................................................82
Exit the Do Loop.......................................................................................................83
Which Do Loop should I use?...................................................................................83
 3.9.11. For ... Next.........................................................................................................84
 3.9.12. Exit Sub and Exit Function................................................................................85
 3.10. Error handling using On Error..................................................................................86
 3.10.1. CVErr................................................................................................................87
 3.10.2. Ignore errors with On Error Resume Next........................................................88
 3.10.3. Clear an error handler with On Error GoTo 0...................................................88
 3.10.4. Specify your own error handler with On Error GoTo Label.............................89
 3.10.5. Error handlers — why use them?......................................................................91
 3.11. Conclusion.................................................................................................................93
 4. Numerical Routines............................................................................................................94
 4.1. Trigonometric functions..............................................................................................95
 4.2. Rounding errors and precision....................................................................................97
 4.3. Mathematical functions.............................................................................................100
 4.4. Numeric conversions.................................................................................................101
 4.5. Number to string conversions...................................................................................107
 4.6. Simple formatting......................................................................................................107
 4.7. Other number bases, hexadecimal, octal, and binary................................................108
 4.8. Random numbers......................................................................................................111
 4.9. Conclusion.................................................................................................................112
 5. Array Routines..................................................................................................................113
 5.1. Array() quickly builds a one­dimensional array with data........................................114
 5.2. DimArray creates empty multi­dimensional arrays..................................................116
 5.3. Change the dimension of an array.............................................................................117
 5.4. Array to String and back again..................................................................................118
 5.5. Array inspection functions........................................................................................119
 5.6. Conclusion.................................................................................................................122
 6. Date Routines....................................................................................................................123
 6.1. Compatibility issues..................................................................................................124
 6.2. Retrieve the current date and time............................................................................124
 6.3. Dates, numbers, and strings......................................................................................124
 6.4. Locale formatted dates..............................................................................................126
 6.5. ISO 8601 dates..........................................................................................................126
iii
6.6. Problems with dates..................................................................................................127
 6.7. Extract each part of a date.........................................................................................131
 6.8. Date arithmetic..........................................................................................................135
 6.9. Assembling dates from components.........................................................................136
 6.10. Measuring elapsed time over short intervals...........................................................137
 6.11. How fast does this run? A real­world example!......................................................139
 6.12. Long time intervals and special dates.....................................................................142
 6.13. Conclusion...............................................................................................................143
 7. String Routines..................................................................................................................144
 7.1. ASCII and Unicode values........................................................................................146
 7.2. Standard string functions...........................................................................................149
 7.3. Locale and strings.....................................................................................................153
 7.4. Substrings..................................................................................................................153
 7.5. Replace......................................................................................................................154
 7.6. Aligning strings with LSet and RSet.........................................................................155
 7.7. Fancy formatting with Format..................................................................................157
 7.8. Converting data to a string........................................................................................162
 7.9. Advanced searching..................................................................................................163
 7.10. Conclusion...............................................................................................................164
 8. File Routines.....................................................................................................................166
 8.1. Using URL notation to specify a file........................................................................167
 8.2. Directory manipulation functions.............................................................................168
 8.3. File manipulation functions.......................................................................................169
 8.4. File attributes, bitmasks, and binary numbers...........................................................172
 8.5. Obtaining a directory listing......................................................................................174
 8.6. Open a file.................................................................................................................175
 8.7. Information about open files.....................................................................................177
 8.8. Reading and writing data..........................................................................................180
 8.9. File and directory related services.............................................................................186
 8.9.1. Path Settings......................................................................................................186
 8.9.2. Path Substitution................................................................................................190
 8.9.3. Simple File Access............................................................................................192
 8.9.4. Streams..............................................................................................................192
 8.9.5. Pipes..................................................................................................................196
 8.10. Conclusion...............................................................................................................197
 9. Miscellaneous Routines....................................................................................................198
 9.1. Display and color......................................................................................................198
 9.1.1. Determine the GUI type....................................................................................198
 9.1.2. Determine pixel size (in twips)..........................................................................199
 9.1.3. Use color functions............................................................................................200
 9.2. Flow control..............................................................................................................202
iv
9.2.1. Return an argument...........................................................................................203
 9.2.2. Pause or end the macro......................................................................................204
 9.2.3. Dynamic Link Libraries....................................................................................205
 9.2.4. Calling external applications.............................................................................206
 9.2.5. Dynamic Data Exchange...................................................................................207
 9.3. User input and output................................................................................................208
 9.3.1. Simple output.....................................................................................................209
 9.3.2. Multi­line output................................................................................................210
 9.3.3. Prompting for input...........................................................................................212
 9.4. Error­related routines................................................................................................214
 9.5. Miscellaneous routines..............................................................................................215
 9.6. Partition.....................................................................................................................218
 9.7. Inspection and identification of variables.................................................................220
 9.8. Routines you should not use and other curiosities....................................................225
 9.9. Routines I do not understand.....................................................................................226
 9.10. Conclusion...............................................................................................................227
 10. Universal Network Objects.............................................................................................228
 10.1. Base types and structures........................................................................................229
 10.2. UNO interface.........................................................................................................231
 10.3. UNO service............................................................................................................232
 10.3.1. Setting a Read­Only Value..............................................................................236
 10.4. Context....................................................................................................................237
 10.5. Inspecting Universal Network Objects...................................................................237
 10.6. Using the type description manager........................................................................242
 10.7. Use Object or Variant..............................................................................................245
 10.8. Comparing UNO variables......................................................................................246
 10.9. Built­in global UNO variables................................................................................247
 10.10. Creating UNO values for OOo internals...............................................................250
 10.11. Finding objects and properties..............................................................................251
 10.12. UNO listeners........................................................................................................252
 10.12.1. Your first listener...........................................................................................253
 10.12.2. A complete listener: selection change listener..............................................254
 10.13. Creating a UNO dialog..........................................................................................256
 10.14. Conclusion.............................................................................................................260
 11. The Dispatcher................................................................................................................261
 11.1. The environment.....................................................................................................261
 11.1.1. Two different methods to control OOo...........................................................261
 11.1.2. Finding dispatch commands............................................................................263
Use the WIKI...........................................................................................................263
Probe the interface...................................................................................................263
Read source code.....................................................................................................266
v
11.2. Writing a macro using the dispatcher......................................................................266
 11.3. Dispatch failure – an advanced clipboard example.................................................266
 11.4. Conclusion...............................................................................................................267
 12. StarDesktop.....................................................................................................................268
 12.1. The Frame service...................................................................................................268
 12.1.1. The XIndexAccess interface............................................................................269
 12.1.2. Find frames with FrameSearchFlag constants.................................................269
 12.2. The XEventBroadcaster interface...........................................................................271
 12.3. The XDesktop interface..........................................................................................271
 12.3.1. Closing the desktop and contained components..............................................271
 12.3.2. Enumerating components using XEnumerationAccess...................................272
 12.3.3. Current component..........................................................................................273
 12.3.4. Current component (again)..............................................................................274
 12.3.5. Current frame...................................................................................................274
 12.4. Load a document.....................................................................................................275
 12.4.1. Named arguments............................................................................................279
 12.4.2. Loading a template..........................................................................................281
 12.4.3. Enabling macros while loading a document....................................................282
 12.4.4. Importing and exporting..................................................................................283
 12.4.5. Filter names.....................................................................................................283
 12.4.6. Loading and saving documents.......................................................................289
 12.4.7. Error handling while loading a document.......................................................291
 12.5. Conclusion...............................................................................................................291
 13. Generic Document Methods...........................................................................................292
 13.1. Service Manager......................................................................................................292
 13.2. Services and interfaces............................................................................................293
 13.3. Getting and setting properties.................................................................................294
 13.4. Document properties...............................................................................................296
 13.4.1. Document properties from a closed document................................................298
 13.4.2. Custom properties............................................................................................298
 13.4.3. Deprecated document information object.......................................................299
 13.5. List events...............................................................................................................300
 13.5.1. Registering your own listener..........................................................................301
 13.5.2. Intercepting dispatch commands.....................................................................302
 13.6. Link targets..............................................................................................................304
 13.7. Accessing view data: XViewDataSupplier.............................................................306
 13.8. Close a document: XCloseable...............................................................................307
 13.9. Draw Pages: XDrawPagesSupplier.........................................................................308
 13.9.1. Draw and Impress............................................................................................308
 13.9.2. Draw lines with arrows in Calc.......................................................................311
 13.9.3. Writer...............................................................................................................312
vi
13.10. The model..............................................................................................................313
 13.10.1. Document arguments.....................................................................................314
 13.11. Saving a document................................................................................................316
 13.12. Manipulating styles...............................................................................................319
 13.12.1. Style utilities..................................................................................................324
 13.13. Dealing with locale...............................................................................................329
 13.14. Enumerating printers.............................................................................................337
 13.15. Printing documents................................................................................................337
 13.15.1. Printing Writer documents............................................................................341
 13.15.2. Printing Calc documents................................................................................343
 13.15.3. A Calc example with a Print listener.............................................................344
 13.15.4. Print examples by Vincent Van Houtte.........................................................346
 13.16. Creating services...................................................................................................356
 13.17. Document settings.................................................................................................357
 13.18. The coolest trick I know........................................................................................359
 13.19. Converting to a URL in other languages...............................................................359
 13.20. Conclusion.............................................................................................................359
 14. Writer Documents...........................................................................................................360
 14.1. Basic building blocks..............................................................................................361
 14.1.1. Primary text content: the XText interface.......................................................361
 14.1.2. Text ranges: the XTextRange interface...........................................................362
 14.1.3. Inserting simple text........................................................................................364
 14.1.4. Text content: the TextContent service.............................................................364
 14.2. Enumerating paragraphs..........................................................................................366
 14.2.1. Paragraph properties........................................................................................366
Insert a page break...................................................................................................370
Set the paragraph style.............................................................................................371
 14.2.2. Character properties.........................................................................................371
 14.2.3. Enumerating text sections (paragraph portions)..............................................376
 14.3. Graphics..................................................................................................................378
 14.4. Paste HTML then embed linked graphics...............................................................381
 14.5. Cursors....................................................................................................................383
 14.5.1. View cursors....................................................................................................383
 14.5.2. Text (non­view) cursors..................................................................................385
 14.5.3. Using cursors to traverse text..........................................................................386
Keep the view cursor and text cursor in sync..........................................................388
 14.5.4. Accessing content using cursors......................................................................389
 14.6. Selected text............................................................................................................391
 14.6.1. Is text selected?................................................................................................392
 14.6.2. Selected text: Which end is which?.................................................................393
 14.6.3. Selected text framework..................................................................................394
vii