MacroButton Field Tips and Tricks - not just for macros

The MacroButton field is a field developed in early versions of Word (pre-Windows). The name comes from the ability to trigger a macro. It was early used to insert dummy text for typing and can still serve that function well, without any macros. It continues to work, well, in Word 2019.

MacroButton Fields - Syntax and Behavior

Syntax 

{ MacroButton MacroName DisplayText }

MacroButton - the field command

MacroName - name of macro being called - or "NoMacro"

DisplayText - text that acts as the "button" for the macro and is displayed in your document. Note that there are no quotation marks used in this field. DisplayText can be any text you want but will not wrap to a new line. There are limits on length. Instead of the DisplayText you can insert an inline picture or icon to act as a visual button for your macro. See below, though for images. The text in a MacroButton field prompt cannot be longer than a single line between the left and right indents for the paragraph. You can shrink the font size of the prompt text to fit more words on that single line.

Behavior

Clicking on a MacroButton field will select the field. Double-clicking on one will activate a macro if there is a macro designated. You can change this behavior to make the macro activate on a single click as well.

MacroButton Fields as Prompts

You can use the first behavior (selecting the field) to make simple click-and-type prompts. If you look at many of the templates that come from Microsoft with Word, you will find places that say something like "[Click here and type]." If you click at that spot, the whole prompt is selected and anything you type replaces it. Often, this is exactly what you want for a simple prompt. What you are seeing is a simple implementation of the "MacroButton" field. This use of the macrobutton field is the forerunner of Content Controls.

To insert a MacroButton field like this in your document type it then make it a field.

As is the case with all fields, you cannot simply type the field braces { }. You either have to use Word's Insert => Field or press Ctrl+F9 and type the field contents. To get: { MacroButton NoMacro DisplayText } you could simply type "MacroButton NoMacro DisplayText" and select it. Then press the Ctrl+F9 key combination to make it a field. Pressing F9 will update it to the field display of DisplayText. You must create or edit the field manually to get colors or other formatting in your prompt text that will disappear when the user actually uses it and types.

Inserting a MacroButton field like this in your document using the Field insertion dialog is a bit more involved:

(Word 97-2003) Insert => Field ... 

(Word 2007-2019) Insert => Quick Parts => Field ...

Where it says Field: type "MacroButton NoMacro prompt." The "MacroButton" is the name of the field. "NoMacro" is the name used by the field for the macro to be called - in this special case, none. The "prompt" is whatever prompt text you want. This can be "[Click here and type]" or the text that will usually be just fine but which the user might want to change. "NoMacro" is used as a convention to indicate that there is no macro being used. Note that if there was an available macro with the name "nomacro" that macro would be run by this field. Any name that does not indicate an available macro will give the same result, that is, the entire field will be selected when clicked on (as always happens with a MacroButton) but since no macro can be found, the result is selected text. If you want to format your prompt text, you need to do that by revealing the field code and editing. To me, typing the field and then using Ctrl+F9 to insert the braces is much easier.

As is the case with other fields, the F11 key will take you to the next field, selecting that field. When you use macrobutton fields as prompts, you may want to put an instruction in your documents to use F11 to go to the next field. I do this putting the instruction in blue or red text and a different font in a textbox formatted to float in front of text. The textbox is formatted to have no lines and no fill. The text in the textbox is formatted as hidden so it should not print. I have this textbox as an AutoText entry in my developer's template so that I can insert it easily when I prepare a new template.

Below is an example of how a Macrobutton Prompt appears in a document. (Screenshot) The field code for this prompt is:

{ MacroButton NoMacro This is a macrobutton prompt! When you click on it, all is selected. }

The first paragraph shows the prompt as displayed on the page. The second shows the prompt after it has been clicked on before typing; the third shows that the prompt colors do not show up in the text after the user types.

You can download a free Add-In that gives you a dialog box below to add a MacroButton prompt to your document where you want with a choice of colors for the prompt text.

Picture of custom dialog box from Add-In. Click to go to download page.

Dialog box from Add-In

MacroButton Fields to Run Macros

Instead of simply being a prompt for typing, this MacroButton field will run a macro if double-clicked. (This can be altered to a single click using VBA.) Instead of NoMacro, simply type the name of the macro. When inserting the field, you can click on the Options button and you will be given a list of available macros (possibly quite a long list) from which to select.

Where it says "Macros defined in active document" a more accurate caption would be "Macros available to active document." This list also includes all of Word's built-in commands, many of which are not found on the menus.

Note that the MacroButton field is selected when it is clicked or double-clicked. You may want to have your macro collapse the selection at some point so that your MacroButton field won't be inadvertently deleted. The language for this is: 

Selection.Collapse 
'Unselects the current selection and places 
'insertion point at beginning of selection.

Note also that a macro button prompt will print as ordinary text. (It is the field result). To avoid it being printed, you may want to put it in a no-border text box formatted as hidden text (Format => Font). Because of this, it is often easier to use a custom toolbar with a button on that toolbar. The toolbar will not print.

MacroButton Fields can be used in Protected Forms and will be active even in a protected portion of the document. They are often used in such forms as a replacement for hyperlinks (since regular hyperlinks are inactive in the protected portion of a form).

A simple example of macrobuttons can be found in the CheckBox template. This template/tutorial combines the powers of macros, autotext, and the macrobutton field.

MacroButton Fields where the Macro responds to the contents of the field (uses them as an argument or variable for the macro)

It is possible to use one macro that responds to the contents of the field to change what the macro does. Doing this with Private or AddIn fields incorporated in MacroButton fields is discussed in the MacroButtons page on the MVP FAQ site. The same technique can be used with just the display text of the MacroButton field.

The macro is:

Sub TestMacro2()
Dim MyString As String
    'Ignore first 24 characters of the macrobutton field -
    '   the words 'MacroButton TestMacro2', and the spaces
    MyString = Mid$(Selection.Fields(1).Code, 24)
    MsgBox MyString
End Sub

The field is:

{ MacroButton TestMacro2 [Click Here] }

This can be used to construct a list of templates in the Workgroup Templates folder as macrobuttons. When you double-click (or single-click as shown below) on the macrobutton, the macro creates a new document based on the named template. A single macro decides which template to open based on the template listed in the macrobutton field.

That is, the following fields both call the same macro:

{ Macrobutton TemplateListLoad Releases\Release - blank} (Displays: Releases\Release-Blank)

{ Macrobutton TemplateListLoad Log} (Displays: Log)

The macro uses the display information to decide which template to use. The macro is:

Sub TemplateListLoad()
'   Based on ideas from http://wordmvp.com/FAQs/TblsFldsFms/UsingMacroButton.htm
'   Macro written by Charles Kyle Kenyon
'   24 October 2002
'
    Dim sTemplateName As String
    Dim sTemplatesPath As String
    '
    '   Get workgroup templates path
    '
    sTemplatesPath = Options.DefaultFilePath(wdWorkgroupTemplatesPath) & "\"
    '
    '   Parse template name from Macrobutton field.
    '   (The selection is the entire field.)
    On Error GoTo ErrorHandler
    sTemplateName = Mid$(Selection.Fields(1).Code, 31) & ".dot"
    '   Use to create a new document based on the template
    Documents.Add Template:=sTemplatesPath & sTemplateName
    Selection.Collapse
    Exit Sub
    '
End Sub

Making MacroButtons respond to a single click

To me, double-clicking on a button is counter-intuitive. To make a macrobutton respond to a single click to run a macro the following VBA code has to be active:

Options.ButtonFieldClicks = 1

This has to be run before the user tries to click on the button. It can be in an AutoOpen or AutoNew macro in the template which contains the macrobutton or in an AutoExec macro in a global template. (Explaining these gets beyond the scope of this article; see Template Basics for more.)

Using MacroButtons to function as hyperlinks in protected forms.

In a document that has been "protected" as a form in Word, hyperlink fields don't work, but macrobutton fields do work. You can use a macrobutton for a hyperlink to an external document or web page (and even format it to look like a hyperlink) in a protected document. It is more work than merely inserting a hyperlink, though. (You can also use a macrobutton to link to an internal bookmark with reservations, see end of this section.)

  1. With your document not protected for forms, record a macro that opens the document to which you want to link. Save the macro in your document (not in Normal.dot) when you record it.
  2. Use the Macro Editor (Alt+F11) to edit your macro. At the end of the macro (just before "End Sub") add the following line.
      Selection.Collapse
  3. Where you want your hyperlink Press Ctrl+F9 to insert your field codes and type "MacroButton MyMacro displaytext." where "MyMacro" is the name of your macro and "displaytext" is what you want the hyperlink to show in your document. (See Syntax above)
  4. Press F9 to update your field. It should show your displaytext.
  5. Select your field and press Ctrl+Shift+S to get into the styles drop-down.
  6. Type "hyperlink" for the style name and press enter.

When you protect your document your pseudo-hyperlink should work fine. Remember to set the ButtonFieldClicks to 1. Also, the mouse pointer will not change to a little hand when passing over your pseudo-hyperlink - but we can't have everything, can we?

If you would like some pre-written code for your hyperlink macrobutton, you can download HyperJmp.zip from the Visual Basic MVP site.

For alternative coding, take a look at Using Hyperlinks in Protected Forms on the MVP site. They show how to use a single macro for all your hyperlinks in the document.

When the target of the link is within the protected form it doesn't work quite so well. It will jump to the field addressed by your bookmark if your bookmark is for a formfield, otherwise to the field following your bookmark. If there is no field following your non-field bookmark, it jumps to the first field in the document. Note that fields inserted with the Forms toolbar automatically have a bookmark assigned. (You can change that bookmark in the field's properties.) Thanks to Marcy T. for bringing this problem to my attention.

For more on protected forms, follow the links in my web resources page, especially those to Dian Chapman's excellent series of articles.

Example of MacroButton Field Use in Multiple Ways - The Microsoft Fax Transmittal Template from Word 97

Note the checked box by "For Review." Here is the same template after toggling display of Field Codes (Alt+F9). The prompts for user input are MacroButton fields not associated with any macro. A dummy name of "NoMacro" is inserted but the purpose of the field is to display the prompt. The checkboxes in the form are MacroButton fields, not Form Checkboxes or Content Controls! Both of these use the property of MacroButton fields to select the entire field when clicked on. The display text for the checkbox fields is the unchecked or checked box.

If there were an active macro named NoMacro (or nomacro) these MacroButton fields would call that macro!

The name of the macro called by the (unchecked) Urgent checkbox is "CheckIt." The one called by the (checked) For Review checkbox is "UncheckIt." Look again at the form with the field codes not showing. All you see is the display text - the checked and unchecked boxes.

See Checkbox Add-In for samples.

Different behavior with images for text in .doc vs .docx formatted documents

An image does not work well as a prompt in document (templates) formatted as .docx or .docm (.dotx or .dotm). These are the document and template formats for the Ribbon versions of Word (2007+). See this post on the Microsoft Answers forum. The image is selected, not the field. If the image is deleted by the user and the user types, that typing becomes the prompt for the field. Clicking or double-clicking on the field will not run a macro.

If the same document is saved in .doc or .dot format, the macrobutton field will act as specified. The screenshot below is from a document in .docx format when the MacroButton Field has been clicked on.

Here is a screen shot of the same thing, except the same document has been saved in .doc format:

In the .doc format, clicking on the image selects the field containing the image (and a double-click will run an associated macro). If the user types anything, the image is deleted, the field is deleted, leaving only the typing. When in .docx format, the image is selected in the field. No macro is run. If the image is deleted by the user and the user types, what the user types becomes the new MacroButton field prompt! If there is no image, or if the user clicks on a text prompt included with the image, the field is selected, including the image, and replaced by typing.

Here is another sample using a smaller image, in .docx format:

3. shows the field structure with the button image following the text.

1. shows what it looks like when the image is clicked on. Note the image moves in front of the text even though formatted to be inline with text. If there is a macro, it will not run in this condition.

2. Shows what it looks like when the space after the text is clicked on or the field is entered using the F11 (next field) function key. When this is done, if there is a macro, it will run.

What happens in these instances when text is typed?

In Word 2007 and later when you click on the image, any text typed is added to the MacroButton Field prompt text. If the field itself is selected or you click in the area following the image, the field is replaced by typing. In this second instance, if there is a macro, it is run first.

If the same fields are saved in a .doc (Word 97-2003) format, the field simply acts as a macrobutton field.

See Greg Maxey's page on Toggle objects for some ways to get Word to respond to images in macrobutton fields. One method is with spaces, another is with the IncludePicture field inserting the image. The second suggestion comes from Doug Robbins. An example using the IncludePicture field:

{ Macrobutton NoMacro { INCLUDEPICTURE "https://addbalance.com/word/images/PillcrowFlying.gif" } }

Using that construction, the image is selected with the macrobutton (and replaced by typing).

MacroButton Field Prompts compared to Content Controls

Macrobutton prompts and text content controls can have a similar appearance in a document. Here is a screenshot showing plain text Content Controls and a MacroButton field prompt. Both have the placeholder text formatted using the PlaceHolderText style.

MacroButton Fields and the Table of Contents

If you have a MacroButton Field that is in text that shows up in a Table of Contents, it will be formatted as a Hyperlink in the Table of Contents and the Macrobutton Field will be an active field in the TOC. (This is not true of a hyperlink field.)

Additional references on MacroButton fields

Click to return to table of contents page of Legal Users' Guide to Microsoft Word.Click to go to Microsoft Word new users frequently asked questions site in a new browser window.
(this guide table of contents) ----- (MS Word New Users FAQ)

Search Usersguide to Microsoft Word using Google