Difference between revisions of "Documentation/OOoAuthors User Manual/Getting Started/Getting Started with Macros"

From Apache OpenOffice Wiki
Jump to: navigation, search
(Creating a macro)
 
(32 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{NeedsWork}}
+
{{DISPLAYTITLE:Getting Started with Macros}}
This page was created by converting ODT to Mediawiki using Writer2MediaWiki.
+
{{Documentation/GSMacroTOC
 
+
|ShowPrevNext=block
This is Chapter '''17''' of '''Getting Started with OpenOffice.org 2.x''' (Third edition), produced by the [http://oooauthors.org/ OOoAuthors group]. A PDF of this chapter is available from the [http://documentation.openoffice.org/manuals/oooauthors2/ OOoAuthors Guides page] at OpenOffice.org.
+
|PrevPage=Documentation/OOoAuthors User Manual/Getting Started/Saving Draw documents as web pages
 
+
|NextPage=Documentation/OOoAuthors User Manual/Getting Started/Creating a simple macro
[[User_Manuals| &lt;&lt; User Manuals page]]<br>
+
}}
[[Getting Started| &lt;&lt; Getting Started Table of Contents]]<br>
+
This is Chapter '''17''' of '''Getting Started with OpenOffice.org 2.x''' (Fourth edition), produced by the [http://oooauthors.org/ OOoAuthors group]. A PDF of this chapter is available from the [http://documentation.openoffice.org/manuals/oooauthors2/ OOoAuthors Guides page] at OpenOffice.org.
[[Getting Started: Creating Web Pages| &lt;&lt; Chapter 16 Creating Web Pages]] &nbsp;&nbsp;|
+
&nbsp;&nbsp;[[Getting Started: Keyboard Shortcuts|Appendix A Keyboard Shortcuts &gt;&gt;]]
+
 
+
  
 
== Your first macro ==
 
== Your first macro ==
Line 15: Line 12:
 
OpenOffice.org macros are usually written in a language called StarBasic, or just abbreviated Basic. Although you can learn Basic and write macros, there is a steep learning curve to writing macros from scratch. The usual method for a beginner is to use the built-in macro recorder, which records your keystrokes and saves them for use.
 
OpenOffice.org macros are usually written in a language called StarBasic, or just abbreviated Basic. Although you can learn Basic and write macros, there is a steep learning curve to writing macros from scratch. The usual method for a beginner is to use the built-in macro recorder, which records your keystrokes and saves them for use.
  
Most tasks in OpenOffice.org are accomplished by “dispatching a command" (sending a command), which is intercepted and used. The macro recorder works by recording the commands that are dispatched (see “The dispatch framework" on page 8).
+
Most tasks in OpenOffice.org are accomplished by “dispatching a command" (sending a command), which is intercepted and used. The macro recorder works by recording the commands that are dispatched (see [[Documentation/OOoAuthors User Manual/Getting Started/Sometimes the macro recorder fails#The dispatch framework|The dispatch framework]]).
 
+
 
+
=Creating a simple macro=
+
 
+
Imagine repeatedly entering simple information. Although you can store the information in the clipboard, if you use the clipboard for something else, the contents are changed. Storing the contents as a macro is a simple solution. (In some simple cases, including the example used here, a better solution is to use AutoText.)
+
 
+
# Use '''Tools > Macros > Record Macro''' to start recording a macro. A small window is displayed so you know that OpenOffice.org is recording.
+
: inline:graphics1.png
+
 
+
# Type the desired information or perform an appropriate series of operations. In this case, I typed my name, ''Andrew Pitonyak''.
+
# Click the '''Stop Recording''' button to stop recording, save the macro, and display the OpenOffice.org Basic Macros dialog (see Figure 1).
+
: inline:Frame1.png
+
 
+
# Be certain to open the library container named ''My Macros''. Find the library named ''Standard'' under My Macros. Be warned, ''every'' library container has a library named Standard. Select the Standard library and click '''New Module''' to create a new module to contain the macro.
+
: inline:Frame2.png
+
 
+
# The default module name is Module1; choose a better name. Although it is still not descriptive, I used Recorded. Type a descriptive name and click '''OK''' to create the module. The OpenOffice.org Basic Macros dialog is displayed again, showing the new module.
+
# Highlight the newly created module. In the upper left corner, type the macro name to use, such as “EnterMyname", and then click '''Save''' to save the macro.
+
 
+
If you followed all of the steps, the Standard library now contains a module named Recorded, which contains the EnterMyName macro, as shown in Figure 3. When OOo creates a new module, it automatically adds the macro named Main; as seen in Figure 3.
+
 
+
==Running the macro==
+
 
+
Use '''Tools > Macros > Run Macro''' to open the Macro Selector dialog (see Figure 3). Select the newly created macro and click '''Run'''.
+
 
+
: inline:Frame4.png
+
 
+
There are other methods to run a macro. For example, use '''Tools > Macros > Organize Macros > OpenOffice.org Basic''' to open the macro organizer, which contains a '''Run''' button as well. The author, an avid macro writer, prefers the macro organizer because the dialog usually opens faster, but the selection process may be slightly slower.
+
 
+
==Viewing and editing the macro==
+
 
+
You can view and edit the macro that was just created. Use '''Tools > Macros > Organize Macros > OpenOffice.org Basic''' to open the OpenOffice.org Basic Macros dialog (see Figure 3). Select the new macro and click '''Edit''' to open the macro in the Basic IDE (Integrated Development Environment).
+
 
+
''Listing 1: Generated "EnterMyname" macro.''
+
 
+
<code>
+
  REM  *****  BASIC  *****
+
  Sub Main
+
 
+
  End Sub
+
 
+
  sub EnterMyName
+
  rem ---------------------------------------------------------------
+
  rem define variables
+
  dim document  as object
+
  dim dispatcher as object
+
  rem ---------------------------------------------------------------
+
  rem get access to the document
+
  document  = ThisComponent.CurrentController.Frame
+
  dispatcher = createUnoService("com.sun.star.frame.DispatchHelper")
+
 
+
  rem ---------------------------------------------------------------
+
  dim args1(0) as new com.sun.star.beans.PropertyValue
+
  args1(0).Name = "Text"
+
  args1(0).Value = "Andrew Pitonyak"
+
 
+
  dispatcher.executeDispatch(document, ".uno:InsertText", "", 0, args1())
+
  end sub
+
</code>
+
 
+
The macro in Listing 1 is not as complicated as it first appears. Learning a few things helps significantly in understanding the generated macros. The discussion starts with features near the top of the macro listing and describes them. If you like to avoid details, then simply change the text “Andrew Pitonyak" to what you want to insert at the current cursor position.
+
 
+
===Comments start with REM===
+
 
+
The keyword REM, short for ''remark'', starts a macro comment. All text after REM (on the same line) is ignored. As a short cut, the single quote character can also be used to start a comment.
+
 
+
{|
+
| ||  '''Tip'''  ||StarBasic is not case-sensitive for keywords, so REM, Rem, and rem all start a comment. If you use symbolic constants defined by the API, it is safer to assume that the names are case-sensitive—if this matters to you, then you are probably too advanced to read this document.||
+
|-
+
|}
+
 
+
===Defining subroutines with SUB===
+
 
+
:Individual macros are stored in subroutines defined with the keyword SUB. A subroutine ends using the words END SUB. The macro starts by defining the subroutine named Main, which is empty and does nothing. The next subroutine, EnterMyName, is the subroutine of interest, and it contains the newly generated code.
+
 
+
{|
+
| ||  '''Tip'''  ||OpenOffice.org creates an empty subroutine named Main when it creates a module.||
+
|-
+
|}
+
 
+
:There are advanced topics that are beyond the scope of this document, but knowing about them might be of interest:
+
 
+
** You can write a subroutine so that values are sent into the macro when it is called from another macro. Recorded macros do not accept arguments from other macros.
+
** Another kind of subroutine is called a function. A function is a subroutine that can return a value to a calling macro. The keyword FUNCTION is used rather than SUB to define a function. Generated macros are always of type SUB.
+
 
+
===Defining variables using DIM===
+
 
+
:A very simple macro can use hard coded values for everything. Unfortunately, even simple macros that interact with OpenOffice.org must store intermediate values. Storing an intermediate value is similar to writing information on a piece of paper so that you can look at it later. The DIM statement is similar to setting aside a piece of paper to be used to store a message or note.
+
 
+
:The EnterMyName macro defines the variables ''document'' and ''dispatcher'' as type ''object''. Other common variable types include ''string'', ''integer'', and ''date''. A third variable named ''args1'' is defined. ''Args1'' is a very complicated type; it is an array of property values. A variable of type ''array'' allows a single variable to contain multiple values, similar to storing multiple pages in a single book. Values in an array are usually numbered starting from zero. The number in the parentheses indicates the highest usable number to access a storage location. In this example, there is only one value, and it is numbered zero. This sounds confusing, but for now, ignore the problem and more examples will clarify the concept.
+
 
+
===Pulling the macro together===
+
 
+
:The following details are very complete; it is not important to understand all of the details. The first line defines the start of the macro.
+
 
+
:<tt>sub</tt><tt> </tt><tt>EnterMyName</tt>
+
 
+
:Declare two variables:
+
 
+
:<tt>dim</tt><tt> </tt><tt>document</tt><tt>  </tt><tt>as</tt><tt> </tt><tt>object</tt>
+
 
+
:<tt>dim</tt><tt> </tt><tt>dispatcher</tt><tt> </tt><tt>as</tt><tt> </tt><tt>object</tt>
+
 
+
:ThisComponent refers to the current document.
+
 
+
:The CurrentController property of a document refers to a service that “controls" the document. For example, when you type, it is the current controller that notices. The current controller then dispatches the changes to the document's frame.
+
 
+
:The Frame property of a controller returns a main frame for a document. Therefore, the variable named ''document'' refers to a document's frame, which receives dispatched commands.
+
 
+
:<tt>document</tt><tt> </tt><tt>=</tt><tt> </tt><tt>ThisComponent</tt><tt>.</tt><tt>CurrentController</tt><tt>.</tt><tt>Frame</tt>
+
 
+
:Most tasks in OpenOffice.org are accomplished by dispatching a command. Starting with OOo version 2.0, a dispatch helper object is available, which greatly facilitates executing dispatches from a macro. The method CreateUnoService accepts the name of a service and it tries to create an instance of that service. On completion, the dispatcher variable contains a reference to a DispatchHelper.
+
 
+
:<tt>dispatcher</tt><tt> </tt><tt>=</tt><tt> </tt><tt>createUnoService</tt><tt>(</tt><tt>"com.sun.star.frame.DispatchHelper"</tt><tt>)</tt>
+
 
+
:Declare an array of properties. Each property has a name and a value. In other words, it is a name/value pair. The created array has one property at index zero.
+
 
+
:<tt>dim</tt><tt> </tt><tt>args1</tt><tt>(</tt><tt>0</tt><tt>)</tt><tt> </tt><tt>as</tt><tt> </tt><tt>new</tt><tt> </tt><tt>com</tt><tt>.</tt><tt>sun</tt><tt>.</tt><tt>star</tt><tt>.</tt><tt>beans</tt><tt>.</tt><tt>PropertyValue</tt>
+
 
+
:Give the property the name “Text" and the value “Andrew Pitonyak", which is the text that is inserted when the macro is run.
+
 
+
:<tt>args1</tt><tt>(</tt><tt>0</tt><tt>).Name</tt><tt> </tt><tt>=</tt><tt> </tt><tt>"Text"</tt>
+
 
+
:<tt>args1</tt><tt>(</tt><tt>0</tt><tt>).</tt><tt>Value</tt><tt> </tt><tt>=</tt><tt> </tt><tt>"Andrew Pitonyak"</tt>
+
 
+
:This is where the magic happens. The dispatch helper sends a dispatch to the document's frame (stored in the variable named document) with the command “.uno:InsertText". The next two arguments, ''frame name'' and ''search flags'', are beyond the scope of this document. The last argument is the array of property values to be used while executing the command InsertText.
+
 
+
:<tt>dispatcher</tt><tt>.</tt><tt>executeDispatch</tt><tt>(</tt><tt>document</tt><tt>,</tt><tt> </tt><tt>".uno:InsertText"</tt><tt>,</tt><tt> </tt><tt>""</tt><tt>,</tt><tt> </tt><tt>0</tt><tt>,</tt><tt> </tt><tt>args1</tt><tt>())</tt>
+
 
+
:Finally, the end of the subroutine.
+
 
+
:<tt>end</tt><tt> </tt><tt>sub</tt>
+
 
+
:
+
 
+
=Creating a macro=
+
 
+
A recorded macro repeats the same task over and over again. Before creating a recorded macro, I usually ask two questions:
+
 
+
# Can the task be summarized as a simple set of commands that do not change?
+
# Can the steps be arranged such that the last command leaves the cursor ready for the next command?
+
 
+
==A complicated example==
+
 
+
I frequently copy rows and columns of data from a web site and format them as a table in a text document. First, I copy the table from the web site to the clipboard. To avoid strange formatting and fonts, I paste the text into a Writer document as unformatted text. I reformat the text with tabs between columns so that I can use '''Table > Convert > Text to Table''' to convert to a table.
+
 
+
I inspect the text to see if I can record a macro to format the text (remember the two questions that I ask). As an example, I copied the FontWeight constants group from the OpenOffice.org web site. The first column indicates the constant name. Each name is followed by a space and a tab.
+
 
+
: inline:Frame8.png
+
 
+
:I want the first column to contain the numeric value, the second column the name, and the third column the description. The desired work is easily accomplished for every row except for DONTKNOW and NORMAL, which do not contain a numeric value—but I know that the values are 0 and 100, so I will enter those manually.
+
 
+
The data can be cleaned in multiple ways—all of them easy. The first example uses keystrokes that assume the cursor is at the start of the line with the text THIN.
+
 
+
# Use '''Tools > Macros > Record Macro''' to start recording.
+
# Press ''Ctrl+Right Arrow'' to move the cursor to the start of “specifies".
+
# Press ''Backspace'' twice to remove the tab and the space.
+
# Press ''Tab'' to add the tab without the space after the constant name.
+
# Press ''Delete'' to delete the lower case s and then press ''S'' to add an upper case S.
+
# Press ''Ctrl+Right Arrow'' twice to move the cursor to the start of the number.
+
# Press ''Ctrl+Shift+Right Arrow'' to select and move the cursor before the % sign.
+
# Press ''Ctrl+C'' to copy the selected text to the clipboard.
+
# Press ''End'' to move the cursor to the end of the line.
+
# Press ''Backspace'' twice to remove the two trailing spaces.
+
# Press ''Home'' to move the cursor to the start of the line.
+
# Press ''Ctrl+V'' to paste the selected number to the start of the line.
+
# Pasting the value also pasted an extra space, so press ''Backspace'' to remove the extra space.
+
# Press ''Tab'' to insert a tab between the number and the name.
+
# Press ''Home'' to move to the start of the line.
+
# Press ''down arrow'' to move to the next line.
+
# Stop recording the macro and save the macro.
+
 
+
It takes much longer to read and write the steps than to record the macro. Work slowly and think about the steps as you do them. With practice this becomes second nature.
+
 
+
The generated macro has been modified to contain the step number in the comments to match the code to the step above.
+
 
+
''Listing 2: Copy the numeric value to the start of the column.''
+
 
+
<code>
+
  sub CopyNumToCol1
+
  rem ----------------------------------------------------------------------
+
  rem define variables
+
  dim document  as object
+
  dim dispatcher as object
+
  rem ----------------------------------------------------------------------
+
  rem get access to the document
+
  document  = ThisComponent.CurrentController.Frame
+
  dispatcher = createUnoService("com.sun.star.frame.DispatchHelper")
+
 
+
  rem (2) Press Ctrl+Right Arrow to move the cursor to the start of “specifies”.
+
  dispatcher.executeDispatch(document, ".uno:GoToNextWord", "", 0, Array())
+
 
+
  rem (3) Press Backspace twice to remove the tab and the space.
+
  dispatcher.executeDispatch(document, ".uno:SwBackspace", "", 0, Array())
+
 
+
  rem ----------------------------------------------------------------------
+
  dispatcher.executeDispatch(document, ".uno:SwBackspace", "", 0, Array())
+
 
+
  rem (4) Press Tab to add the tab without the space after the constant name.
+
  dim args4(0) as new com.sun.star.beans.PropertyValue
+
  args4(0).Name = "Text"
+
  args4(0).Value = CHR$(9)
+
 
+
  dispatcher.executeDispatch(document, ".uno:InsertText", "", 0, args4())
+
 
+
  rem (5) Press Delete to delete the lower case s ....
+
  dispatcher.executeDispatch(document, ".uno:Delete", "", 0, Array())
+
 
+
  rem (5) ... and then press S to add an upper case S.
+
  dim args6(0) as new com.sun.star.beans.PropertyValue
+
  args6(0).Name = "Text"
+
  args6(0).Value = "S"
+
 
+
  dispatcher.executeDispatch(document, ".uno:InsertText", "", 0, args6())
+
 
+
  rem (6) Press Ctrl+Right Arrow twice to move the cursor to the number.
+
  dispatcher.executeDispatch(document, ".uno:GoToNextWord", "", 0, Array())
+
 
+
  rem ----------------------------------------------------------------------
+
  dispatcher.executeDispatch(document, ".uno:GoToNextWord", "", 0, Array())
+
 
+
  rem (7) Press Ctrl+Shift+Right Arrow to select the number.
+
  dispatcher.executeDispatch(document, ".uno:WordRightSel", "", 0, Array())
+
 
+
  rem (8) Press Ctrl+C to copy the selected text to the clipboard.
+
  dispatcher.executeDispatch(document, ".uno:Copy", "", 0, Array())
+
 
+
  rem (9) Press End to move the cursor to the end of the line.
+
  dispatcher.executeDispatch(document, ".uno:GoToEndOfLine", "", 0, Array())
+
 
+
  rem (10) Press Backspace twice to remove the two trailing spaces.
+
  dispatcher.executeDispatch(document, ".uno:SwBackspace", "", 0, Array())
+
 
+
  rem ----------------------------------------------------------------------
+
  dispatcher.executeDispatch(document, ".uno:SwBackspace", "", 0, Array())
+
 
+
  rem (11) Press Home to move the cursor to the start of the line.
+
  dispatcher.executeDispatch(document, ".uno:GoToStartOfLine", "", 0, Array())
+
 
+
  rem (12) Press Ctrl+V to paste the selected number to the start of the line.
+
  dispatcher.executeDispatch(document, ".uno:Paste", "", 0, Array())
+
 
+
  rem (13) Press Backspace to remove the extra space.
+
  dispatcher.executeDispatch(document, ".uno:SwBackspace", "", 0, Array())
+
 
+
  rem (14) Press Tab to insert a tab between the number and the name.
+
  dim args17(0) as new com.sun.star.beans.PropertyValue
+
  args17(0).Name = "Text"
+
  args17(0).Value = CHR$(9)
+
 
+
  dispatcher.executeDispatch(document, ".uno:InsertText", "", 0, args17())
+
 
+
  rem (15) Press Home to move to the start of the line.
+
  dispatcher.executeDispatch(document, ".uno:GoToStartOfLine", "", 0, Array())
+
 
+
  rem (16) Press down arrow to move to the next line.
+
  dim args19(1) as new com.sun.star.beans.PropertyValue
+
  args19(0).Name = "Count"
+
  args19(0).Value = 1
+
  args19(1).Name = "Select"
+
  args19(1).Value = false
+
 
+
  dispatcher.executeDispatch(document, ".uno:GoDown", "", 0, args19())
+
  end sub
+
</code>
+
 
+
Cursor movements are used for all operations (as opposed to searching). If run on the DONTKNOW line, the word ''weight'' is moved to the front of the line, and the first “The" is changed to “She". This is not perfect, but I should not have run the macro on the lines that did not have the proper format; I need to do these manually.
+
 
+
==Running the macro quickly==
+
 
+
It is tedious to repeatedly run the macro using '''Tools > Macros > Run Macro''' (see Figure 3). The macro can be run from the IDE. Use '''Tools > Macros > Organize Macros > OpenOffice.org Basic''' to open the Basic Macro dialog. Select your macro and click '''Edit''' to open the macro in the IDE.
+
 
+
The IDE has a '''Run Basic''' icon in the toolbar that runs the first macro in the IDE. Unless you change the first macro, it is the empty macro named Main. Modify Main so that it reads as shown in Listing 3.
+
 
+
''Listing 3: Modify Main to call CopyNumToCol1.''
+
 
+
:<tt>Sub</tt><tt> </tt><tt>Main</tt>
+
 
+
:<tt>  </tt><tt>CopyNumToCol1</tt>
+
 
+
:<tt>End</tt><tt> </tt><tt>Sub</tt>
+
 
+
:Now, you can run CopyNumToCol1 by repeatedly clicking the '''Run Basic''' icon in the toolbar of the IDE. This is very fast and easy, especially for temporary macros that will be used a few times and then discarded.
+
 
+
'''Sometimes the macro recorder fails'''
+
----
+
:Understanding the OpenOffice.org internals helps to understand how and why the macro recorder frequently fails. The primary offender is related to the dispatch framework and its relationship to the macro recorder.
+
 
+
:'''The dispatch framework''''''The dispatch framework'''
+
 
+
:The purpose of the dispatch framework is to provide a uniform access to components (documents) for commands that usually correspond to menu items. I can use '''File > Save''' from the menu, the shortcut keys ''Ctrl+S'', or click on the '''Save''' toolbar icon. All of these commands are translated into the same “dispatch command", which is sent to the current document.
+
 
+
:The dispatch framework can also be used to send “commands" back to the UI (User Interface). For example, after saving the document, the File Save command is disabled. As soon as the document has been changed, the File Save command is enabled.
+
 
+
:If we see a dispatch command, it is text such as .uno:InsertObject or .uno:GoToStartOfLine. The command is sent to the document's frame, and the frame passes on the command until an object is found that can handle the command.
+
 
+
:'''How the macro recorder uses the dispatch framework'''
+
 
+
:The macro recorder records the generated dispatches. The recorder is relatively simple to implement and the same commands that are issued are recorded for later use. The problem is that not all dispatched commands are complete. For example, inserting an object generates the following code:
+
 
+
:<tt>dispatcher</tt><tt>.</tt><tt>executeDispatch</tt><tt>(</tt><tt>document</tt><tt>,</tt><tt> </tt><tt>".uno:InsertObject"</tt><tt>,</tt><tt> </tt><tt>""</tt><tt>,</tt><tt> </tt><tt>0</tt><tt>,</tt><tt> </tt><tt>Array</tt><tt>())</tt>
+
 
+
:It is not possible to specify what kind of object to create or insert. If an object is inserted from a file, you cannot specify which file to insert.
+
 
+
:I recorded a macro and used '''Tools > Options''' to open and modify configuration items. The generated macro does not record any configuration changes; in fact, the generated code is commented so it will not even be run.
+
 
+
:<tt>rem dispatcher.executeDispatch(document, ".uno:OptionsTreeDialog", "", 0, Array())</tt>
+
 
+
:If a dialog is opened, the command to open the dialog is likely to be generated. Any work done inside the dialog is not likely to be recorded. Examples include macro organization dialogs, inserting special characters, and similar types of dialogs. Other possible problems using the macro recorder include things such as inserting a formula, setting user data, setting filters in Calc, actions in database forms, and exporting a document to an encrypted PDF file. You never know for certain what will work unless you try it, however. The actions from the search dialog are properly captured, for example.
+
 
+
:'''Other options'''
+
 
+
:When the macro recorder is not able to solve a specific problem, the usual solution is to write code using the OpenOffice.org objects. Unfortunately, there is a steep learning curve for the OOo objects. It is usually best to start with simple examples and then branch out slowly as you learn more. Learning to read generated macros is a good place to start.
+
 
+
:If you record Calc macros, and the recorder can correctly generate a macro, there is an add-in created by Paolo Mantovani, which converts Calc macros when they are recorded. The final code manipulates OpenOffice.org objects rather than generating dispatches. This can be very useful for learning the object model.
+
 
+
:You can download the macro recorder from Paolo's web site directly or from the OOo Macros web site. You should check both places to see which contains the latest version.
+
 
+
:[http://www.paolo-mantovani.org/downloads/DispatchToApiRecorder/ http://www.paolo-mantovani.org/downloads/DispatchToApiRecorder/]  
+
 
+
:[http://www.ooomacros.org/user.php http://www.ooomacros.org/user.php]
+
 
+
'''Macro ''''''organization''''''organization'''
+
----
+
:In OpenOffice.org, macros are grouped in modules, modules are grouped in libraries, and libraries are grouped in library containers. A library is usually used as a major grouping for either an entire category of macros, or for an entire application. Modules usually split functionality types such as user interaction and calculations. Individual macros are subroutines and functions.
+
 
+
: inline:Frame5.png
+
 
+
:Use '''Tools > Macros > Organize Macros > OpenOffice.org Basic''' to open the OpenOffice.org Basic Macros dialog (see Figure 5). All available library containers are shown in the ''Macro from'' list. Every document is a library container, capable of containing multiple libraries. The application itself acts as two library containers, one container for macros distributed with OpenOffice.org called OpenOffice.org Macros, and one container for personal macros called My Macros. As shown in Figure 5, only two documents are currently open.
+
 
+
: inline:Frame7.png
+
 
+
:The OpenOffice.org Macros are stored with the application runtime code, which may not be editable to you unless you are an administrator. This is just as well since these macros should not be changed and you should not store your own macros in the OOo container.
+
 
+
:Unless your macros are applicable to a single document, and only to a single document, your macros will probably be stored in the My Macros container. The My Macros container is stored in your user area or home directory.
+
 
+
:If a macro is contained in a document, then a recorded macro will attempt to work on that document; primarily because it uses “ThisComponent" for its actions.
+
 
+
:Every library container contains a library named ''Standard''. It is better to create your own libraries with meaningful names than to use the Standard library. Not only are meaningful names easier to manage, but they can also be imported into other library containers whereas the Standard library cannot.
+
 
+
{|
+
| ||  '''Caution '''<br/> inline:graphics9.png  ||OpenOffice.org allows you to import libraries into a library container, but it will not allow you to overwrite the library named Standard. Therefore, if you store your macros in the Standard library, you cannot import them into another library container.||
+
|-
+
|}
+
 
+
:Just as it makes good sense to give your libraries meaningful names, it is prudent to use meaningful names for your modules. By default, OpenOffice.org uses names such as Module1. Feel free to use your own meaningful name.
+
 
+
:As you create your macros, you must decide where to store them. Storing a macro in a document is useful if the document will be shared and you want the macro to be included with the document. Macros stored in the application library container named My Macros, however, are globally available to all documents.
+
 
+
:Macros are not available until the library that contains them is loaded. The Standard library and Template library, however, are automatically loaded. A loaded library is displayed differently from a library that is not loaded. To load the library and the modules it contains, double-click on the library.
+
 
+
:'''Where are macros ''''''stored?'''
+
 
+
:OpenOffice.org stores user-specific data in a directory under the user's home directory. For example, on Windows, this is C:\Documents and Settings\<name>\Application Data. User macros are stored in OpenOffice.org2\user\basic. Each library is stored in its own directory off the basic directory.
+
 
+
:It is not important to understand where macros are stored for casual use. If you know where they are stored, however, you can create a backup, share your macros, or inspect them if there is an error. For example, on one or more of my OpenOffice.org upgrades, all of my macros disappeared. Although the macros were still on disk, the macros were not copied to the new directories. The solution was to import the macros into the new installation.
+
 
+
:Use '''Tools > Macros > Organize Dialogs''' to open the OpenOffice.org Macros organizer dialog. Another common way to open this dialog is to use '''Tools > Macros > Organize Macros > OpenOffice.org Basic''' to open the OpenOffice.org Macros dialog and then click the '''Organizer''' button (see Figure 6).
+
 
+
: inline:Frame17.png
+
 
+
:The OpenOffice.org Macro Organizer dialog provides functionality to create, delete, and rename libraries, modules, and dialogs. Select the library container to use and then click the '''Import''' button to import macro libraries (see Figure 7).
+
 
+
{|
+
| ||  '''Tip'''  ||You cannot import the library named Standard.||
+
|-
+
|}
+
 
+
{|
+
| ||  '''Tip'''  ||On Linux, the OpenOffice.org-specific files are stored in a directory whose name begins with a period. Directories and files with names beginning with a period are not shown in a normal selection dialog. To open the directory, I navigated to the parent directory, entered the name .openoffice.org2, and then clicked '''Open'''. This opened the directory, which was not initially shown.||
+
|-
+
|}
+
 
+
: inline:Frame18.png
+
 
+
:Navigate to the directory containing the library to import. There are usually two files from which to choose, dialog.xlb and script.xlb. It does not matter which of these two files you select; both will be imported. Select a file and click '''Open''' to continue (see Figure 8).
+
 
+
: inline:Frame19.png
+
 
+
:If the library already exists, it will not be replaced unless '''Replace existing libraries''' is checked. If '''Insert as reference''' is checked, the library is referenced in its current location, but you cannot edit the library. If '''Insert as reference''' is not checked, however, the library is copied to the user's macro directory.
+
 
+
:Macros can be stored in libraries inside OpenOffice.org documents. Select a document rather than a directory on disk (as shown in Figure 7) to import libraries contained in a document.
+
 
+
:'''Downloading macros to import'''
+
 
+
:Macros are available for download. Some macros are contained in documents, some as regular files that you must select and import, and some as macro text that should be copied and pasted into the Basic IDE; use '''Tools > Macros > Organize Macros > OpenOffice.org Basic''' to open the OpenOffice.org Macros dialog, choose the macro to edit, and then click '''Edit''' to open the macro in the Basic IDE.
+
 
+
:Some macros are available as free downloads on the Internet (see Table 1).
+
 
+
:''Table ''''1''''. Places to find macro examples.''
+
 
+
{|
+
| ||'''''Location'''''||'''''Description'''''||
+
|-
+
| ||[http://www.ooomacros.org/ http://www.ooomacros.org/]||Excellent collection of packaged macros.||
+
|-
+
| ||[http://www.pitonyak.org/oo.php http://www.pitonyak.org/oo.php]||Reference materials regarding macros.||
+
|-
+
| ||[http://www.pitonyak.org/database/ http://www.pitonyak.org/database/]||Reference materials regarding database macros.||
+
|-
+
| ||[http://development.openoffice.org/ http://development.openoffice.org/]||Lots of links to everything.||
+
|-
+
| ||[http://www.oooforum.org/ http://www.oooforum.org/]||Many examples and help.||
+
|-
+
|}
+
 
+
'''How to ''''''run a macro'''
+
----
+
:A typical method to run a macro is as follows:
+
 
+
## Use '''Tools > Macros > Run Macro''' to open the Macro Selector dialog (see Figure 9).
+
## Select the library and module in the Library list (left hand side).
+
## Select the macro in the Macro name list (right hand side).
+
## Click '''Run''' to run the macro.
+
: inline:Frame3.png
+
 
+
:Although you can use '''Tools > Macros > Run Macro''' to run all macros, this is not efficient for frequently run macros. A more common technique is to assign a macro to a toolbar button, menu item, keyboard shortcut, or a button embedded in a document. While choosing a method, it is also good to ask questions such as:
+
 
+
** Should the macro be available for only one document, or globally for all documents?
+
** Does the macro pertain to a specific document type, such as a Calc document?
+
** How frequently will the macro be used?
+
:The answers will determine where to store the macro and how to make it available. For example, you will probably not add a rarely used macro to a toolbar. To help determine your choices, see Table 2.
+
 
+
:''Table ''''2''''. Methods for starting a macro.''
+
 
+
{|
+
| ||'''''Type'''''||'''''OpenOffice.org'''''||'''''Document Type'''''||'''''Document'''''||
+
|-
+
| ||Toolbar||No||Yes||Yes||
+
|-
+
| ||Menu||No||Yes||Yes||
+
|-
+
| ||Shortcut||Yes||Yes||No||
+
|-
+
| ||Event||Yes||No||Yes||
+
|-
+
|}
+
 
+
:To add a menu item, keyboard shortcut, or toolbar icon that calls a macro, use the Customize dialog (see Figure 10). Open this dialog in either of these ways:
+
 
+
** Choose '''Tools > Customize''' from the main menu bar.
+
** Each toolbar has an icon  inline:graphics11.png  that opens a menu; choose the '''Customize Toolbar''' option.
+
: inline:Frame9.png
+
 
+
{|
+
| ||  '''Tip'''  ||Complete coverage of the Customize dialog is beyond the scope of this document. Click the '''Help''' button to access the help pages included with OpenOffice.org.||
+
|-
+
|}
+
 
+
:The Customize dialog contains tabs to configure menus, keyboard bindings, toolbars, and events.
+
 
+
:'''Toolbar'''
+
 
+
:Macros can be added to toolbars. To see more about modifying toolbars, see Chapter 4 (Menus and Toolbars).
+
 
+
:'''Menu item'''
+
 
+
:Use '''Tools > Customize''' to open the Customize dialog, and select the Menus tab. You can modify an existing menu, or create new menus that call macros. To see more about modifying menus, see Chapter 4 (Menus and Toolbars).
+
 
+
:'''Keyboard shortcuts'''
+
 
+
:Use '''Tools > Customize''' to open the Customize dialog, and select the Keyboard tab. Assigning keyboard shortcuts is discussed in Appendix A (Keyboard Shortcuts).
+
 
+
:'''Event'''
+
 
+
:In OpenOffice.org, when something happens, we say that an event occurred. For example, a document was opened, a key was pressed, or the mouse moved. OpenOffice.org allows events to cause a macro to be called; the macro is then called an event handler. Full coverage of event handlers is well beyond the scope of this document, but a little knowledge can accomplish much.
+
 
+
{|
+
| ||  '''Caution '''<br/> inline:graphics16.png  ||Be careful when you configure an event handler. For example, assume that you write an event handler that is called every time that a key is pressed, but you make a mistake so the event is not properly handled. One possible result is that your event handler will consume all key presses, forcing you to forcibly terminate OpenOffice.org.||
+
|-
+
|}
+
 
+
:Use '''Tools > Customize''' to open the Customize dialog, and select the Events tab (see Figure 11). The events in the Customize dialog are related to the entire application and specific documents. Use the Save In box to choose OpenOffice.org, or a specific document.
+
 
+
: inline:Frame14.png
+
 
+
:A common use is to assign the Open Document event to call a specific macro. The macro then performs certain setup tasks for the document. Select the desired event and click the '''Macro''' button to open the Macro Selector dialog (see Figure 12).
+
 
+
:Select the desired macro and click '''OK''' to assign the macro to the event. The Events tab shows that the event has been assigned to a macro (see Figure 13). When the document opens, the PrintHello macro is run.
+
 
+
: inline:Frame15.png
+
 
+
: inline:Frame16.png
+
 
+
:Many objects in a document can be set to call macros when events occur. The most common usage is to add a control, such as a button, into a document. Even double-clicking on a graphic opens a dialog with a Macros tab that allows you to assign a macro to an event.
+
 
+
'''Extensions'''
+
----
+
:An extension is a package that can be installed into OpenOffice.org to add new functionality. Extensions can be written in almost any programming language and may be simple or sophisticated. Extensions can be grouped into types:
+
 
+
** Calc Add-Ins, which provide new functionality for Calc, including new functions that act like normal built-in functions
+
** New components and functionality, which normally include some level of UI integration such as new menus or toolbars
+
** Data pilots that are used directly in Calc
+
** Chart Add-Ins with new chart types
+
** Linguistic components such as spell checkers
+
** Document templates and images
+
:Although individual extensions can be found in different places, there is an extension repository at: [http://wiki.services.openoffice.org/wiki/Extensions_repository http://wiki.services.openoffice.org/wiki/Extensions_repository]. To learn more about extensions, see Chapter 12 (Working with Templates) in this book.
+
 
+
'''Writing macros without the recorder'''
+
----
+
:The examples covered in this chapter are created using the macro recorder and the dispatcher. You can also write macros that directly access the objects that comprise OpenOffice.org. In other words, you can directly manipulate a document.
+
 
+
:Directly manipulating OOo's internal objects is an advanced topic that is beyond the scope of this chapter. A simple example, however, demonstrates how this works.
+
 
+
:''Listing ''''4'''': Append the text “Hello" to the current document.''
+
 
+
:<tt>Sub</tt><tt> AppendHello</tt>
+
 
+
:<tt>  </tt><tt>Dim</tt><tt> oDoc</tt>
+
 
+
:<tt>  </tt><tt>Dim</tt><tt> sTextService$</tt>
+
 
+
:<tt>  </tt><tt>Dim</tt><tt> oCurs</tt>
+
 
+
:<tt>  </tt>
+
 
+
:<tt>  </tt><tt>REM ThisComponent refers to the currently active document.</tt>
+
 
+
:<tt>  oDoc </tt><tt>=</tt><tt> ThisComponent</tt>
+
 
+
:
+
 
+
:<tt>  </tt><tt>REM Verify that this is a text document  </tt>
+
 
+
:<tt>  sTextService </tt><tt>=</tt><tt> </tt><tt>"com.sun.star.text.TextDocument"</tt>
+
 
+
:<tt>  </tt><tt>If</tt><tt> </tt><tt>NOT</tt><tt> oDoc</tt><tt>.</tt><tt>supportsService</tt><tt>(</tt><tt>sTextService</tt><tt>)</tt><tt> </tt><tt>Then</tt>
+
 
+
:<tt>    MsgBox </tt><tt>"This macro only works with a text document"</tt>
+
 
+
:<tt>    </tt><tt>Exit</tt><tt> </tt><tt>Sub</tt>
+
 
+
:<tt>  </tt><tt>End</tt><tt> </tt><tt>If</tt>
+
 
+
:<tt>  </tt>
+
 
+
:<tt>  </tt><tt>REM Get the view cursor from the current controller.</tt>
+
 
+
:<tt>  oCurs </tt><tt>=</tt><tt> oDoc</tt><tt>.</tt><tt>currentController</tt><tt>.</tt><tt>getViewCursor</tt><tt>()</tt>
+
 
+
:<tt>  </tt>
+
 
+
:<tt>  </tt><tt>REM Move the cursor to the end of the document</tt>
+
 
+
:<tt>  oCurs</tt><tt>.</tt><tt>gotoEnd</tt><tt>(</tt><tt>False</tt><tt>)</tt>
+
 
+
:<tt>  </tt>
+
 
+
:<tt>  </tt><tt>REM Insert text "Hello" at the end of the document</tt>
+
 
+
:<tt>  oCurs</tt><tt>.Text.</tt><tt>insertString</tt><tt>(</tt><tt>oCurs</tt><tt>,</tt><tt> </tt><tt>"Hello"</tt><tt>,</tt><tt> False</tt><tt>)</tt><tt>  </tt>
+
 
+
:<tt>End</tt><tt> </tt><tt>Sub</tt>
+
 
+
'''Finding more information'''
+
----
+
:Numerous resources are available that provide help with writing macros. Use '''Help > OpenOffice.org Help''' to open the OOo help pages. The upper left corner of the OOo help system contains a drop-down list that determines which help set is displayed. To view the help for Basic, the drop-down must display ''Help about OpenOffice.org Basic''.
+
 
+
:'''Included material'''
+
 
+
:Many excellent macros are included with OOo. Use '''Tools > Macros > Organize Macros > OpenOffice.org Basic''' to open the Macro dialog. Expand the Tools library in the OpenOffice.org library container. Inspect the Debug module—some good examples include WritedbgInfo(document) and printdbgInfo(sheet).
+
 
+
:'''Online resources'''
+
 
+
:The following links and references contain information regarding macro programming:
+
 
+
** [http://www.openoffice.org/ http://www.openoffice.org] (the main link)
+
** [http://codesnippets.services.openoffice.org/ http://codesnippets.services.openoffice.org/] (categorized examples)
+
** [http://www.oooforum.org/ http://www.oooforum.org] (if you need help with your macros this is a good place to ask, probably one of the best supported OOo forums on the web)
+
** [http://api.openoffice.org/docs/common/ref/com/sun/star/module-ix.html http://api.openoffice.org/docs/common/ref/com/sun/star/module-ix.html] (official IDL reference, here you'll find almost every command with a description)
+
** [http://api.openoffice.org/DevelopersGuide/DevelopersGuide.html http://api.openoffice.org/DevelopersGuide/DevelopersGuide.html] (official documentation that contains a detailed explanation)
+
** [http://www.pitonyak.org/oo.php http://www.pitonyak.org/oo.php] (Andrew Pitonyak's macro page)
+
** [http://www.pitonyak.org/AndrewMacro.odt http://www.pitonyak.org/AndrewMacro.odt] (numerous examples of working macros)
+
** [http://www.pitonyak.org/book/ http://www.pitonyak.org/book/] (Andrew Pitonyak wrote a book on macros)
+
** [http://www.pitonyak.org/database/ http://www.pitonyak.org/database/] (numerous macro examples using Base)
+
** [http://docs.sun.com/app/docs http://docs.sun.com/app/docs] (Sun wrote a book on macro programming—very well written and laid out)
+
** [http://documentation.openoffice.org/ http://documentation.openoffice.org] (contains content related to macros)
+
** [http://ooextras.sourceforge.net/ http://ooextras.sourceforge.net/] (examples)
+
** [http://sourceforge.net/project/showfiles.php?group_id=43716 http://sourceforge.net/project/showfiles.php?group_id=43716] (examples)
+
** [http://homepages.paradise.net.nz/hillview/OOo/ http://homepages.paradise.net.nz/hillview/OOo/] (numerous excellent macros, including reveal codes macros, key macros, and information on converting from MS Office)
+
:'''Published material'''
+
 
+
:The following published sources contain macro examples. The most obvious example is the documentation from Sun. Start from Sun's documentation site [http://docs.sun.com/app/docs http://docs.sun.com/app/docs] and search for StarOffice documentation.
+
 
+
:Andrew Pitonyak wrote a book called ''OpenOffice.org Macros Explained''. Two chapters are available as direct downloads from the publisher. See [http://www.pitonyak.org/book/ http://www.pitonyak.org/book/.]
+
 
+
:Dr. Mark Alexander Bain wrote ''Learn OpenOffice.org Spreadsheet Macro Programming'' (see [http://www.packtpub.com/openoffice-ooobasic-calc-automation/book http://www.packtpub.com/openoffice-ooobasic-calc-automation/book]).
+
 
+
  
 
{{CCBY}}
 
{{CCBY}}
[[Category: Documentation]]
+
[[Category:Getting Started (Documentation)]]

Latest revision as of 07:16, 18 September 2008


This is Chapter 17 of Getting Started with OpenOffice.org 2.x (Fourth edition), produced by the OOoAuthors group. A PDF of this chapter is available from the OOoAuthors Guides page at OpenOffice.org.

Your first macro

A macro is a saved sequence of commands or keystrokes that are stored for later use. An example of a simple macro is one that “types" your address. The OpenOffice.org macro language is very flexible, allowing automation of both simple and complex tasks. Macros are especially useful to repeat a task the same way over and over again.

OpenOffice.org macros are usually written in a language called StarBasic, or just abbreviated Basic. Although you can learn Basic and write macros, there is a steep learning curve to writing macros from scratch. The usual method for a beginner is to use the built-in macro recorder, which records your keystrokes and saves them for use.

Most tasks in OpenOffice.org are accomplished by “dispatching a command" (sending a command), which is intercepted and used. The macro recorder works by recording the commands that are dispatched (see The dispatch framework).

Content on this page is licensed under the Creative Common Attribution 3.0 license (CC-BY).
Personal tools