View source for EN/documentation/ooo3 user guides/getting started/creating a simple macro

<section begin=title /><noinclude>{{DISPLAYTITLE:</noinclude>Creating a simple macro<noinclude>}}</noinclude><section end=title />

{{Documentation/GS3MacroTOC
|ShowPrevNext=block
|PrevPage=EN/documentation/ooo3_user_guides/getting_started/getting_started_with_macros
|NextPage=EN/documentation/ooo3_user_guides/getting_started/creating_a_macro
}}__NOTOC__
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.)

<ol>
<li>Use '''Tools > Macros > Record Macro''' to start recording a macro. A small window is displayed so you know that OpenOffice.org is recording.</li>

[[Image:StopRecording.png]]

<li>Type the desired information or perform an appropriate series of operations. In this case, I typed my name, ''Andrew Pitonyak''.</li>

<li>Click the '''Stop Recording''' button to stop recording, save the macro, and display the OpenOffice.org Basic Macros dialog.</li>

[[Image:MacroOrganizer3.png|thumb|none|500px|OOo Macro Organizer dialog, DBInspection library selected.]]

<li>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.</li>

<li>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.</li>

<li>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.</li>

[[Image:MacroName.png|thumb|none|500px|Naming a new macro]]
</ol>

If you followed all of the steps, the Standard library now contains a module named Recorded, which contains the EnterMyName macro. When OOo creates a new module, it automatically adds the macro named Main.

==Running the macro==

Use '''Tools > Macros > Run Macro''' to open the Macro Selector dialog. Select the newly created macro and click '''Run'''.

[[Image:RunMacro3.png|thumb|none|500px|Select your macro and click Run.]]

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 above). 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.

{{Documentation/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—symbolic constants are an advanced topic not usually needed by people who use the macro recorder.}}

===Defining subroutines with SUB===

Individual macros are stored in subroutines defined with the keyword SUB. The end of a subroutine is indicated by the words END SUB. The code starts by defining the subroutine named Main, which is empty and does nothing. The next subroutine, EnterMyName, contains the generated code.

{{Documentation/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 macro so that values can be passed to the subroutine. The values are called arguments. Recorded macros do not accept arguments.
* Another kind of subroutine is called a function. A function is a subroutine that returns a value. The keyword FUNCTION is used rather than SUB to define a function. Generated macros are always of type SUB.

===Defining variables using DIM===

You can write information on a piece of paper so that you can look at it later. A variable, like a piece of paper, contains information that can be changed and read. 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 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.

===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 EnterMyName</tt>

Declare two variables:

:<tt>dim document   as object</tt>
:<tt>dim dispatcher as 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 = ThisComponent.CurrentController.Frame</tt>

Most tasks in OpenOffice.org are accomplished by dispatching a command. OOo version 2.0 introduced the dispatch helper service, which does most of the work to use dispatches in macros. 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 = createUnoService("com.sun.star.frame.DispatchHelper")</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 args1(0) as new com.sun.star.beans.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(0).Name = "Text"</tt>
:<tt>args1(0).Value = "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 <tt>.uno:InsertText</tt>. 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.executeDispatch(document, ".uno:InsertText", "", 0, args1())</tt>

Finally, the end of the subroutine.

:<tt>end sub</tt>

{{Manual}}
[[Category:Getting Started (Documentation)]]