Move Multiple Paragraphs

Microsoft Word comes with a stock command and associated keyboard shortcut (Alt+Shift+Up or Down arrows in Word for Windows and Control+Shift+Up or Down on a Mac), to move one or more paragraphs up or down in a document. I use them every day. The shortcuts are technically for outlines, but they work just fine for any text despite in the category in the keyboard shortcuts documentation page.

What’s different today is we need to implement our own variation to automatically select and move any number of paragraphs, so we can connect it to a Dragon script using a voice command. The emphasis in this article is on the Word VBA macro but see a previous article for a Dragon Professional script than can run it via voice.

We’ll further allow sloppy paragraph selections. This extra touch is convenient for some macros that have a clearly defined effect. The standard command mentioned above also works like this, so we might as well adopt the same behavior.

Create function skeleton

A previous blog post covers the steps to create an empty function. When you’re done, the skeleton for this macro will be something like:

As a reminder, the single quoted lines tell VBA the rest of the text on that line is a comment meant for human readers. Also, an underscore _ character tells VBA we're continuing the VBA step/command on the next editor line to improve readability for any humans. The editor does not care as long as we do not exceed 24 line continuations for a single command.

No keyboard shortcut here

Since this subroutine has parameters inside the parentheses, we won’t be able to assign it directly to a keyboard shortcut or a custom ribbon or quick launch bar button in Microsoft Word. However, we can still use the macro directly from other macros or call it using a Dragon Professional voice command script.

What return type?

Given it’s main purpose, this function doesn’t require a return type, but it is convenient to return the range of the moved paragraphs. Toward this end, we added “As Range” after the parameter parentheses to tell VBA the returned value will be a document range.

At the end of the function, we temporarily set the return value to Nothing since we haven't established the returned result.

Remember in VBA functions, we assign the returned value using the function name. We need to use Set because a range is an object. We can actually set the returned value anywhere within the function, but often this ends up being at the end because we are done with all changes at that point.

What parameters?

We have two parameters, but we have a few extra details to unpack with the second parameter.

How many paragraphs to move?

The first parameter is obviously the number of paragraphs to move which is named appropriately:

Recall VBA uses Dim to declare a variable with a type. It is required if Option Explicit is set for the VBA module. Otherwise, VBA will infer the type based on what data is assigned to it.

Not an Integer …

I used to use Integer numbers in similar macros because it makes more sense in terms of the possible number of paragraphs in a document. Integers in VBA have a maximum value of about 32,000 which probably includes most cases for a writer when using this function. We would probably never want to give the command: “Move that up 36513 paragraphs.” We’d find a different solution.

Use Long numbers (most of the time)

I started using a Long number type in most macro number parameters to avoid issues with parameter types clashing. Parameter types must match exactly when calling them with the Run method of the Application object (like we do from a Dragon Professional script). Such errors are annoying, and the tiny bit of extra storage required to use a Long value will never be noticed for a VBA macro.

I like to precede number variables with an “n” to remind myself what category of variable they are. This is just a personal preference and is not required. Further, a capital first letter “N” often informally indicates (to me) a constant value that will not change inside the subroutine, but I often violate the second preference for articles to make the variable names prettier.

End macro with selected paragraphs?

When working on a document, I prefer to finish the macro by selecting any moved text as a visual indicator of the change. However, we may not want this effect if we’re calling it from a voice command script.

What do we do?

We could just require a second parameter.

We need the parameter for a complete macro, but it’s a tad annoying to have to always specify our choice when we’ll use True most of the time.

I preceded the variable name with a “B” as a reminder that it is a Boolean type. As mentioned above, this is just a personal preference.

Optional parameters

We finally have a reason to talk about optional parameters.

Since both options are necessary but we will usually select the final moved text, we can simply include it as an optional parameter. We literally precede the parameter name with the keyword Optional.

Since it’s either a yes or no (True or False) value we use a Boolean data type.

Finally, if it’s optional, we need to specify a default value in case (probably most of the time) the user does not give one. We add an “= SomeDefaultValue” after the data type but still inside the parentheses. Now the second parameter reads as follows:

The default value must a fixed value like a number or plain text. Some constant object values are okay like Nothing, but it cannot require a function call (with rare exceptions) or any other calculation when the function is used (called a "runtime evaluation").

Calling the macro?

As advertised, the optional parameter allows us to call the function but not give that parameter.

The above command will move the current paragraph up three in the document. Since the optional argument is omitted, the macro will assume a True value for the variable inside the macro and end with the moved text selected. However, a user could instead override the default value and call the subroutine using:

This will move the current paragraph down two in the document (positive 2 means move the current paragraph forward by two paragraphs in the document). False as the second parameter indicates the macro should not select the moved text before it finishes.

Get current paragraph Range

We’ll need two Ranges variables for our task: one to identify the initial document paragraph(s) where the user is working and a second to mark the target moved-text position.

Remember, if we want to declare two variables on the same line, we simply separate them by commas. Both variables need their own type given even if they are the same type. Otherwise, a variable with a missing type will be assigned a generic Variant type.

The rParagraphs range will be set to span the initial partially selected paragraphs, but we’ll move the target range to the intended position.

Define paragraph(s) range

Define the paragraph range as the initial Selection range.

This also works if there is just an insertion point (the blinking I-bar) since that is basically a Selection that spans no document text (kind of, but the details do not matter here).

Recall we must use Set because a range is not just a plain value like a number or some plain text. As mentioned previously, I like to precede my range variables with an “r” as a reminder of what type of data the variable stores.

Ranges, like other objects in VBA, have various properties as well as methods or actions they can carry out on their content. We needed to access the Range property of the Selection because the Selection includes more information than just a Range of spanned document content.

Technically, we could let the Selection act like one of the ranges since it is almost the same thing, but using two ranges makes this function cleaner to implement. We also don’t modify the visible Selection on the screen until we’re ready to do so.

Allow a sloppy selection

The easiest method to capture the range of the paragraph (s) around the initial selection or insertion point is to use the range’s Expand method.

We specify a Unit using the standard paragraph constant wdParagraph. While it is not documented explicitly, Expand will extend the range both directions even if the initially selected text spans more than one paragraph.

Alternative methods

I was a little lazy above, so let’s expound on it just a little bit.

I am usually a apprehensive when utilizing a possible side-effect (selecting multiple paragraphs using Expand) of a method. The Microsoft documentation is not explicit (terse is an understatement for some Microsoft VBA documentation pages) about how the expansion is carried out, so we’re kind of guessing. If you prefer to be clear and explicit, you could instead use:

When using StartOf and EndOf, the Start or End positions of the range will not move if already at the respective location. In practice, the lazy version above seems to do the same thing, but I cannot guarantee it since the documentation is terse for the command.

No Selection change yet

We haven’t yet changed the Selection or insertion point, but with either expansion approach, the rParagraphs range now invisibly spans the entirety of any paragraphs connected to the initial Selection.

Move the target range

Now we want to position the target range at the intended location. It’s convenient to duplicate the paragraphs range now.

Unfortunately, there is a slight asymmetry in the logic depending on whether we’re moving up or down, so duplicating the paragraphs range at this moment sidesteps a subtle movement bug (computer speak for a logical error) by taking advantage of the fact rParagraphs spans one or more full paragraphs.

The Duplicate method ensures we have a new independent range. Otherwise, the two range variables would literally refer to the same range in the document. Meaning, as we move rTarget to the target location below, the rParagraphs range would also change. We don’t want that.

Move to the target paragraph

Now we want to move the target range to the intended copy location. The obvious method is the Move command.

We’re moving by paragraphs, so we needed to specify a Unit as wdParagraph. The Count is given as a macro parameter above as NParagraphs, so we include that value here.

Moves are initiated from the beginning of the range, so we don’t have to worry about tiny details (the Selection has an “active” side).

Up or down?

Negative values indicate moves backward, and positive values correspond to forward movement in the document. This may seem a little counter-intuitive at first, but it makes more sense when you think about how the document grows downward as you add content.

Moves collapse the range

After the move, the range collapses. That is, it spans no text (but there is a subtlety we’ll ignore for now), so its Start and End positions are the same in the document.

Subtle gotchas

This is the move that would result in a small bug if we were not careful. The target position movement works both directions with exactly the same command only because the range spans the entirety of the paragraph(s). When starting from the beginning of a paragraph, a paragraph Unit step moves up or down by exactly one paragraph. If we did not start at the beginning of the paragraph, the first up step would move to the beginning of the paragraph not to the previous paragraph.

See the Gotchas segment below if you’re also thinking ahead about possible problems like what happens if NParagraphs is zero.

Copy formatted text

We need to copy the original paragraph(s) text to the target location. We accomplish this using the FormattedText property.

We literally just set the two properties for the ranges equal.

What about Text?

There is also a Text property, but that would copy the text without any formatting.

Delete original text

Now we want to delete the original paragraph(s) text since it was “moved” to the new location. Just use the Delete method of the initial paragraphs range.

End with moved text selected

As previously advertised, we want to end the macro with the moved target text selected as a visual indicator of the change. Literally just use a Select method of the modified target range.

But only if user wants it

However, we only want to select the text if the user specified it. This is a user-interface decision and is not required, but you’ll probably regret not using sometime when you’re squinting at the screen, trying to figure out where the text went.

How?

We check the BSelected argument value the user provided when he or she called the macro (see above). We need a conditional statement to check the value of BSelected and only select the text if it is True.

We don’t need to check using BSelected = True.

Although it is not technically incorrect, BSelected already stores a Boolean (True-False) value, so we can just refer to it directly.

Benefits of ranges

We use two independent ranges, rParagraphs and rTarget, effectively as invisible selections in the document. Each range served a different purpose during the macro, but both variables evaporate into nothingness when the macro finishes, leaving us with only the document changes.

Gotchas?

The old “what could go wrong” segment …

No paragraphs?

What if someone tells the macro to move by zero paragraphs?

In this macro, we’re probably fine, but we should still think about things like this. There is no reason to continue through all the steps and copy formatted text to the same location in the document. If we’re given zero paragraphs for the move, nothing should happen; and we should just exit the macro.

Use a conditional statement to check the number of paragraphs at the beginning of the function. The condition is:

Exit the function

If the given number of paragraphs is zero, just exit the subroutine.

Set a valid returned range

However, we also need to set a returned value since it is a function. Moving a paragraph by zero paragraphs isn’t an invalid action. It’s just a logical issue. Setting the returned result to Nothing would be okay, indicating the user made a mistake, but it is probably excessive since Nothing generally means an invalid or undefined object (a range in our case).

With that in mind, returning the starting paragraph range makes sense and would be consistent with a “zero paragraph move.” We called this range rParagraphs earlier.

This means we need to define the rParagraphs range first (done below) before we check whether the user gave us a zero-paragraph move. The combined fool-proof check is now:

From there, we are confident we have a valid paragraph move number.