View source

{{DISPLAYTITLE:How to run a macro}}
{{Documentation/GSMacroTOC
|ShowPrevNext=block
|PrevPage=Documentation/OOoAuthors User Manual/Getting Started/Macro organization
|NextPage=Documentation/OOoAuthors User Manual/Getting Started/Extensions
}}__NOTOC__
A typical method to run a macro is as follows:

# Use '''Tools > Macros > Run Macro''' to open the Macro Selector dialog). 
# 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.

: [[Image:MacroSelector.png|thumb|none|500px|Use the Macro Selector dialog to run macros.]]

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.''

{|border="1" cellpadding=4 style="border-collapse:collapse;"
|-bgcolor=#EDEDED
!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. Open this dialog in either of these ways:

* Choose '''Tools > Customize''' from the main menu bar.
* Each toolbar has an icon [[Image:graphics11.png]] that opens a menu; choose the '''Customize Toolbar''' option.

[[Image:CustomizeDialog.png|thumb|none|500px|OpenOffice.org Customize dialog.]]

{{Documentation/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 [[Documentation/OOoAuthors User Manual/Getting Started/Menus and Toolbars|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 [[Documentation/OOoAuthors User Manual/Getting Started/Menus and Toolbars|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 [[Documentation/OOoAuthors User Manual/Getting Started/Keyboard Shortcuts|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.

{{Documentation/Caution|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. 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.

[[Image:MacroEvent.png|thumb|none|500px|Assign macro to an application level event.]]

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.

[[Image:MacroDocEvent.png|thumb|none|500px|Assign macro to the document open event.]]

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. When the document opens, the PrintHello macro is run.

[[Image:AssignMacro.png|thumb|none|500px|Print Hello is assigned to the Open Document event.]]

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.


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