53.5. How to Develop a Macro

Developing a macro with programming code is an easy task. You just write your code and debug it and don't need to worry about compilation and other stuff. You may notice that macro development is easier in comparison with other development scenarios like developing an add-in or a Windows application.

However, macro development applies your knowledge in object-oriented programming by using concepts like classes, modules, and methods to build a macro.

You can even use user interface elements like Windows Forms in your macros. This isn't a common scenario, but it can be done easily. As with a normal project, you add a reference to Windows Forms assemblies in your macro project, then add Windows Forms to your project and load them in your code. However, here we won't get into details about this here.

The best way to understand the development process is by seeing an example. Here you see an example that is a built-in part of Visual Studio. The accessibility module located in the Samples macro project that comes with the default Visual Studio installation is a module that contains a few macros to improve the accessibility of the Visual Studio IDE by changing the size of fonts and their colors. The code for this module is shown here:

Imports EnvDTE
Imports System
Imports EnvDTE80
Imports System.Diagnostics
Imports Microsoft.Win32

Public Module Accessibility

    Private Const fontSizeIncrement As Integer = 2
    Private Const minimumSupportedEditorSize As Integer = 3
    Private whiteColor As UInt32 = Convert.ToUInt32(&HFFFFFF) ' FFFFFF is hex value
of the RGB color white.
    Private blackColor As UInt32 = Convert.ToUInt32(0)        ' 0 is the value of
the RGB color white.

    ' Changes the font size to match the font size of the operating system.
    Public Sub UpdateTextEditorFontSizeToMatchDisplayProperties()
        Dim textEditorFontsAndColors As Properties
        Dim font As System.Drawing.Font
        Dim pointSize As Integer
        Dim fontSize As[Property]

        ' Get font size from menu font to use as an approximation.

font = System.Windows.Forms.SystemInformation.MenuFont
        pointSize = font.GetHeight() - 3 ' Subtract 3 for adjustment.

        ' Update the text edit font size.
        textEditorFontsAndColors = DTE.Properties("FontsAndColors", "TextEditor")
        fontSize = textEditorFontsAndColors.Item("FontSize")
        fontSize.Value = pointSize
    End Sub

    ' Increases the font size used within the editor.
    Public Sub IncreaseTextEditorFontSize() ' Useful to bind to a keystroke, like
Ctrl+Alt+Shift+DownArrow.
        Dim textEditorFontsAndColors As Properties

        textEditorFontsAndColors = DTE.Properties("FontsAndColors", "TextEditor")
        textEditorFontsAndColors.Item("FontSize").Value += fontSizeIncrement
    End Sub

    ' Decreases the font size used within the editor.
    Public Sub DecreaseTextEditorFontSize() ' Useful to bind to a keystroke, like
Ctrl+Alt+Shift+UpArrow.
        Dim textEditorFontsAndColors As Properties
        Dim fontSize As[Property]

        textEditorFontsAndColors = DTE.Properties("FontsAndColors", "TextEditor")
        fontSize = textEditorFontsAndColors.Item("FontSize")
        If fontSize.Value >= minimumSupportedEditorSize Then
            fontSize.Value -= fontSizeIncrement
        End If
    End Sub

    ' Turns all colors used within the editor to black and white, or
    '   restores the colors used before the colors were turned black and white.
    Public Sub ToggleTextEditorGrayScale()
        Dim applicationRegistryRootKey As RegistryKey
        Dim accessibilityKey As RegistryKey
        Dim textEditorFontsAndColors As Properties
        Dim fontsAndColors As FontsAndColorsItems
        Dim editorInGrayScale As Boolean

        ' Determine whether the user has toggled grayscale by looking up info in
registry.
        applicationRegistryRootKey = Registry.CurrentUser.OpenSubKey
(DTE.RegistryRoot, True)
        accessibilityKey = applicationRegistryRootKey.OpenSubKey
("Accessibility", True)

        ' Create key if it does not exist.
        If accessibilityKey Is Nothing Then
            applicationRegistryRootKey.CreateSubKey("Accessibility")

accessibilityKey = applicationRegistryRootKey.OpenSubKey
("Accessibility", True)
            accessibilityKey.SetValue("TextEditorInGrayScale", 0)
        End If

        ' Get current editor grayscale state.
        editorInGrayScale = CType(accessibilityKey.GetValue
("TextEditorInGrayScale"), Boolean)

        ' Get the Fonts and Colors object.
        textEditorFontsAndColors = DTE.Properties("FontsAndColors", "TextEditor")
        fontsAndColors = textEditorFontsAndColors.Item("FontsAndColorsItems")
.Object

        ' Determine whether grayscale settings or previous settings should be
applied.
        If editorInGrayScale Then
            ' Revert to previous colors found from the registry.
            For Each displayItem As ColorableItems In fontsAndColors
                displayItem.Background = UInt32.Parse(accessibilityKey.GetValue
(displayItem.Name + "_BG"))
                displayItem.Foreground = UInt32.Parse(accessibilityKey.GetValue
(displayItem.Name + "_FG"))
            Next

            ' Toggle flag in registry to indicate text editor is not in gray scale
state.
            accessibilityKey.SetValue("TextEditorInGrayScale", 0)
        Else
            ' Write current colors into registry and apply grayscale.
            For Each displayItem As ColorableItems In fontsAndColors
                accessibilityKey.SetValue(displayItem.Name + "_BG", displayItem
.Background.ToString)
                accessibilityKey.SetValue(displayItem.Name + "_FG", displayItem
.Foreground.ToString)
                displayItem.Background = whiteColor
                displayItem.Foreground = blackColor
            Next

            ' Toggle flag in registry to indicate text editor is in gray scale
state.
            accessibilityKey.SetValue("TextEditorInGrayScale", 1)
        End If
    End Sub

    ' Makes tool windows appear in the MDI document space.
    Public Sub MaximizeToolWindowsInEnvironment()
        For Each window As Window In DTE.Windows
            ' Check that this is a tool window and not a document window.

If (window.Document Is Nothing) Then
                ' Turn off auto-hiding.
                Try
                    If window.AutoHides = True Then
                        window.AutoHides = False
                    End If
                Catch exception As Exception
                End Try

                ' Set to undockable (which means show the document as maximized).
                Try
                    window.Linkable = False
                Catch
                End Try
            End If
        Next
    End Sub

End Module

Let's take a quick look at this module to get some information about macro development.

First, you see a few definitions for private constants and fields in the code. Then there are five public subroutines without any parameters, which are actually five macros that accomplish different tasks. Code comments make the code more readable and easier to understand, but as a case study let's determine the code for the UpdateTextEditorFontSizeToMatchDisplayProperties macro.

This macro changes the font size for the Visual Studio IDE to match the font size of the system.

It defines four variables for its work. First it gets the system font size by calling the System.Windows.Forms.SystemInformation.MenuFont. Then it reduces the height of the font size. The next step is to get the font and color properties of the Visual Studio text editor by calling the Properties method of the DTE object and passing the string names of the property and object names.

This Properties object contains a list of some properties for its own. Its FontSize property can be updated to change the font size for the editor at the last stage.

The second macro is IncreaseTextEditorFontSize, which increases the text editor font size by a constant value to make it more readable. This macro is simpler and uses the same approach to get access to the FontsAndColors property of the text editor. It then increases the FontSize property by the fontSizeIncrement constant value.

The last example is the MaximizeToolWindowsInEnvironment macro. This macro maximizes all tool windows in the IDE in the MDI space.

This macro first iterates through all the Windows instances in Visual Studio that are accessible via the DTE.Windows property. In each iteration, it checks for the Document property of the window to see if it's null, because if this property is null then the window is a tool window, not a document window.

Inside the if case it checks for the AutoHides property of the window and sets it to false, then sets the Linkable property to false. This latter property maximizes the window.

Before finishing the discussion about macro development it's worthwhile to point out that macro debugging is similar to debugging any other type of .NET application. You simply start your macro project in debug mode by pressing F5 or choosing appropriate menu items in the Macros IDE. You can use the same debugging tools like breakpoints and visualizers in your macro projects as well.