Quickly applying a scene heading style

In addition to Scene and Subscene headings, I created more editing related styles including “Scene Edited” and “Subscene Edited”. These aren’t my exact names since it evolved over time but close enough. I want to quickly mark a scene as edited without having to move there and manually apply the edited paragraph style. That is today’s macro, but it relies on two previous functions given in member content to make things easier and more robust:

• One function returns a heading range based on a given starting range.
• Another function toggles the style of a given paragraph.

We’ll leverage both functions to create a short macro to quickly toggle the heading paragraph style of a scene.

A little heading terminology

We need some common terminology. When I refer to a “heading paragraph”, I mean the first paragraph of a heading. The “heading content” is everything below the heading paragraph that is part of the heading. Thus, “heading” by itself refers to all the above.

Macro skeleton

Since the intention is to assign this macro to a keyboard shortcut in Word (not on screen), we need to create a VBA subroutine not a function (functions return a value). Our macro skeleton is:

The Subscene Edited macro will be a trivial modification, so we’ll just work with the Scene version.

Word macros and keyboard shortcuts

Any macros assigned to keyboard shortcuts or custom buttons in Word cannot have any parameters or even be a function. However, if you own Dragon Professional, which is a separate paid application with a hefty price tag, voice command scripts aren’t restricted in the same way (see separate introductory article if this sounds interesting).

Set a working range

A common initial step in a macro is to create a range variable to work with the document content. We’ll call our variable name r just to keep the name short.

A range variable is something like an invisible Selection or insertion point sharing many features with the Selection, but they’re not exactly the same.

Previous heading range function

We previously introduced a function that gets the heading range around a given location in the document (several function variations are presented in the article). The basic usage is something like:

We “pass” it a previously defined range variable, which we’re calling TargetRange, around which we want the full heading range. We store the result in a range variable named rHeading here, but the names will vary.

Fortunately for our derived Scene and Scene Edited heading styles, this function works with standard or derived heading styles.

Get our current heading range

The heading range corresponding to the current user position or selection in the document is accessed using the Selection’s Range property.

This works whether the initial Selection includes any spanned text or if it is just an insertion point (i.e., the blinking I-bar waiting for you to type).

We need to store the heading range somewhere, so we use the above working range r. We “call” the function to get the current heading range and store the result:

Now our working range r is assigned to the entire heading range around the initial position in the document. We used Set because ranges are objects with more information than a typical value like a number.

Using this working range r, we can access heading paragraph without affecting the user’s current position or selection.

Was a heading range found?

What if no headings existed in the document? Is that a problem?

We need to verify that a heading range was found. If not, the function literally returns Nothing (meaning no range was assigned to r). Since a range is an object, we can check whether it is equal to Nothing using the “Is” operator.

Technically, Is compares whether two objects are the same thing, but Nothing is the value objects have when not assigned to anything in the document yet, so we also use it to compare an object variable to Nothing.

Conditional statement

Since this is a Boolean value, we can use it directly in a conditional statement:

If you want more background on conditional statements in VBA, see this previous article for a quick review.

Exit the macro

As we’ve done before, we need to exit the macro if the target range is not yet assigned to anything in the document. Macros are technically called “subroutines” in VBA which are usually abbreviated as “Sub”. Since the command is so short, I used the more compact If statement notation on a single line.

This is a subroutine, so there is no value to return for the macro like we’ve done in previous functions. We just exit if there is a problem with the heading range.

In my testing, this will likely not be a problem even if a document has no headings, but it is definitely safer to include it just in case something strange occurs.

Toggle heading paragraph style

We want to toggle the Scene style of the heading paragraph to indicate we just finished editing it (or vice versa). A previous set of macros toggled the current paragraph style, but we need to change the style of the heading paragraph of our range without moving there. That last part is half the point of this macro. We don’t want to require unnecessary manual steps for anyone using the macro.

Our function to toggle a given paragraph style is:

It takes three arguments starting with the paragraph of interest which we call SomeParagraph here. Then we give the function two styles, StyleA and StyleB. The style names can be plain text names or names stored in String variables. The function alternates between them each time the macro is run.

First paragraph

We need the first paragraph of the heading which we’ll call Paragraph1.

We declared it as a Paragraph since the function wants this specific data type (makes sense too since it works specifically with a paragraph).

The first paragraph is literally the first one contained within the heading range r. We’ve mentioned the Paragraphs collection of a range variable before which contains all paragraphs even partially within the range variable.

We just need to reference the First paragraph of the collection using the First property.

We finally store this paragraph in our Paragraph1 variable.

We used Set because a Paragraph is an object much like a range.

Not using first paragraph’s range

Note we are not using the Range property of the first paragraph.

We’ve used ranges and range variables a lot, but our ToggleParagraphStyle function specifically wants a Paragraph variable not its range.

Style names

We need the two names of paragraph styles that exist in the document. For our case here, we’ll use the previously mentioned scene heading names “Scene” and “Scene Edited”. It’s not necessary to declare them as new string variables since we can just use them as plain text in double quotes.

No style validations here

We don’t need to validate whether the styles exist in this macro since the function does that for us, so there shouldn’t be a problem if we switch to another document where they don’t exist yet.

Function call

Given the function above, we pass the paragraph variable and the two style names.

We need to use “Call” for the function because it has arguments. This is actually a function not a subroutine, so using Call essentially ignores the returned information from the function. We don’t need the returned value, so there is no need to declare a variable to store it and then not use it anywhere.

More concise alternative

We could skip the paragraph variable stuff, but the result is a little messier if you’re not used to looking at it.

This works because r.Paragraphs.First is already a Paragraph object, so just skip assigning it to a middleman variable Paragraph1 and pass it directly to the function. Use whichever version you prefer. I like the conciseness of this version but the clarity of the previous, but we can only chase one rabbit.