VBA improvements in Office 2016

Recently, we shared an overview of the new extensibility capabilities available for developers as part of the new Office 2016. In addition to the improvements discussed there, including connecting the applications you build to the data and services available in Office 365 and creating add-ins that connect to third-party services, we continue to support developers working in VBA by adding new objects and members to the VBA object model across nearly all the Office applications.

One thing to note, our engineering focus is Office web add-ins – web add-ins work across devices and platforms, and developers enjoy a modern web development experience. Support for web add-ins is already available in Office 2013 and 2016 for Windows, Office for iPad, and Outlook for Mac today, and they’ll come to the rest of Office clients over time.

Office 2016 for Windows

New VBA object model features

Several Office desktop applications have new features that are exposed in the VBA object model. Here are some of the highlights:

  • Excel has a new set of data import and shaping features that are based on Power Query technology and that let users query information in files, databases, Azure sites, and from other sources, and to combine queries. To support this feature, Excel exposes the new Queries and WorkbookQuery objects, and their associated properties and methods. For more information about Power Query, see this blog post and download this sample. Excel exposes several new methods on the WorksheetFunction object to enable forecasting of statistical functions. Finally, there are a number of new objects related to the existing Model object, such as the ModelFormatBoolean and ModelFormatCurrency objects, and many new properties on each of these new objects.
  • Outlook has added a new PreviewPane object and a new WordEditor property on that object, which allow access to the body of the message currently loaded in the preview pane. This property is intended to let Windows-Eyes and other screen readers to have access to the body of a message in the preview pane.
  • Project adds new Engagement and EngagementComment objects and associated methods and properties to allow programmatic access to engagements scheduled in a project.
  • Visio has added new OM to permit information rights management (IRM) of Visio documents.



Office 2016 for Mac

Since the launch of Office 2016 for Mac in July, Mac OS X users around the world have been able to take advantage of the highly anticipated new features and improvements since the 2011 release. At the same time, some of our users also have sent us feedback requesting further improvements to our VBA support, particularly around VBA add-ins.

In response to this feedback, we’ll further improve Office 2016 for Mac's support for VBA add-ins. Specifically, we’ll be adding Office ribbon customization via Ribbon XML, and making other improvements to Word, Excel, and PowerPoint for Mac to match their Windows desktop versions.

Ribbon customization via Ribbon XML

We are excited to announce that with the latest Office for Mac update, you’ll be able to fully customize the ribbon across Word, Excel, and PowerPoint for the Mac using familiar Ribbon XML.

Here’s how the Mac Word ribbon looks with a custom tab.

Ribbon customization via Ribbon XML

If you’ve been customizing the ribbon on Office for Windows, you’ll find the Mac experience to be very similar. However, there are certain important differences to know about, as described in the table below.

Comparison of ribbon customization functionality in Office 2016 for Mac and Windows

Comparison of ribbon customization functionality in Office 2016 for Mac and Windows
* Most familiar Office Fluent Control Identifiers are compatible with Office for Mac. Some may not be available.
** May support this in future.
*** Office 2016 for Mac doesn't support third-party COM-Add-ins. No current plans to support these in the future. Ribbon customization via Ribbon XML is now available, however, it remains in preview and is disabled by default for this update. Follow the steps below to enable or disable it across Word, Excel and PowerPoint using the Terminal on Mac.

To enable Ribbon XML:

  1. Open Terminal.
  2. Type this command:
    “defaults write com.microsoft.office EnableRibbonXmlDeveloperMode -bool YES”
  3. Reboot the app.


To disable Ribbon XML:

  1. Open Terminal.
  2. Type this command:
    “defaults write com.microsoft.office EnableRibbonXmlDeveloperMode -bool NO”
  3. Reboot the app.



In early 2016, ribbon customization via Ribbon XML will be enabled by default for all customers.

FAQ

How do I edit Ribbon XML?

You can edit Ribbon XML by using familiar Custom UI Editor Tool, which remains available only on Windows.

Will these updates be pushed as part of the auto-update process?

Yes. These updates will be pushed to all customers using Microsoft Auto Updater.

Is the structure of the XML file the same as that for Office for Windows?

Yes, Office 2016 for Mac ribbon reads customizations from CustomUI.xml and CustomUI14.xml.

Will the Office 2016 for Mac ribbon load the XML from both files, CustomUI.xml and CustomUI14.xml?

Yes, and just like the behavior in Office for Windows, CustomUI14.xml will be given preference over CustomUI.xml.

Will the Office 2016 for Mac ribbon accept PNG files that are loaded into the document's custom UI as control images?

Yes.

Visual Basic Editor

You spoke, we heard!

As we continue to improve the overall Visual Basic story on Office 2016 for Mac, we’ve added the following features to Visual Basic Editor:

  • Ability to add modules from within the Project Viewer

    Ability to add modules from within the Project Viewer
  • Ability to add library references using a dialog

    Ability to add library references using a dialog  
  • Ability to use shortcut keys for debugging within Visual Basic Editor, such as Command+Shift+I for Step Into, Command+Shift+O for Step Over.



New Commands

You might not be aware that we recently added two new commands to the Visual Basic object model for Mac: GrantAccessToMultipleFiles and AppleScriptTask.

We also added a new conditional, “MAC_OFFICE_VERSION”. (See New Commands Documentation later in this article.)

As Office 2016 for Mac is sandboxed, users are prompted to grant access every time a file access request is made. GrantAccessToMultipleFiles is a command that takes an array of file pointers and helps minimize the number of these prompts.

Sandboxing also severely breaks the previously existing MacScript command that allows the use of inline AppleScript in Visual Basic. This is where AppleScriptTask can help. Users can store an AppleScript file at a specified location on the disk and use AppleScriptTask within VB to invoke it. The location of these scripts is specified by the operating system and cannot be altered.

The MAC_OFFICE_VERSION conditional lets macros determine what version of Mac Office the user is running. This comes handy in cases where certain commands (like the two above) are available only on a given version, and invoking them on another version may result in errors.

Since Office 2016 for Mac Beta, we’ve been keeping close watch on issues relating to these new commands and have been making fixes. With this update, we’re releasing some important fixes that will considerably improve the overall performance of these commands. In particular, we’ve fixed various timeout issues related to AppleScriptTask.

New Commands Documentation

AppleScriptTask

The AppleScriptTask command executes an AppleScript script. This is similar to the MacScript command except that it runs an AppleScript file located outside the sandboxed app.

For example:


Dim myScriptResult as String
myScriptResult = AppleScriptTask ("MyAppleScriptFile.applescript", "myapplescripthandler", "my parameter string") 



Where:

  • The “MyAppleScriptFile.applescript” file must be in ~/Library/Application Scripts/[bundle id]/. The extension applescript is not mandatory; .scpt may also be used.
  • “myapplescripthandler” is the name of a script handler in the “MyAppleScriptFile.applescript” file
  • “my parameter string” is the single input parameter to the “myapplescripthandler” script handler.
  • The corresponding AppleScript for Excel would be in a file named "MyAppleScriptFile.applescript" that is located in ~/Library/Application Scripts/com.microsoft.Excel/.



Note The bundle IDs for Mac Word, Excel, and PowerPoint are:

  • com.microsoft.Word
  • com.microsoft.Excel
  • com.microsoft.Powerpoint



The following is an example of a handler.


on myapplescripthandler(paramString)

#do something with paramString 
return "You told me " & paramString 


end myapplescripthandler 



GrantAccessToMultipleFiles

Unlike VB macros in Office for Mac 2011, VB macros in Office 2016 for Mac don’t have access to external files by default. The Office 2016 for Mac apps are sandboxed and so they lack the required permissions to access external files.

Existing macro file commands are changed to prompt the user for file access if the app doesn’t already have access to it. This means that macros that access external files cannot run unattended; they’ll need user interaction to approve file access the first time each file is referenced. You can use the GrantAccessToMultipleFiles command to minimize the number of prompts and make the experience better (see below).

GrantAccessToMultipleFiles

This command lets you input an array of file paths and prompt the user for permission to access them.


Boolean  GrantAccessToMultipleFiles(fileArray) 

Parameters 
fileArray  An array of POSIX file paths.

Return values
True   The user grants permission to the files. 
False  The user denies permission to the files. 


Note Once permissions are granted, they’re stored with the app and the user doesn’t need to grant permission to the particular file anymore.

Example:

Sub requestFileAccess()  
  
'Declare Variables  
    Dim fileAccessGranted As Boolean  
    Dim filePermissionCandidates 
  
 'Create an array with file paths for which permissions are needed  
    filePermissionCandidates = Array("/Users//Desktop/test1.txt", "/Users//Desktop/test2.txt") 
  
'Request access from user  
    fileAccessGranted = GrantAccessToMultipleFiles(filePermissionCandidates) 
'returns true if access granted, otherwise, false 
End Sub



MAC_OFFICE_VERSION

In Office 2016 for Mac, this new conditional tests which VB version the user is running. The following example shows how to use it in your code.

Sub VersionConditionals()

#If MAC_OFFICE_VERSION >= 15 Then
    Debug.Print "We are running on Mac 15+"
#Else
    Debug.Print "We are not running on Mac 15+"
#End If
#If Mac Then
    Debug.Print "We are running on a Mac"
#Else
    Debug.Print "We are not running on a Mac"
#End If
End Sub


Note The "#If Mac" conditional remains unchanged from Office for Mac 2011.

Plan Ahead

Starting in Office 2016 for Mac, custom menus that were supported in Office for Mac 2011 are not supported anymore. We’re officially deprecating support for custom menus and CommandBar controls. A few legacy CommandBar controls may continue to appear on the Add-ins tab, however, we advise that you don’t write new code that uses either of the two. Starting today, if you have a VB add-in that requires a UI, it’s best to use Ribbon XML to write that UI.

Overview of UI Extensibility points and corresponding support in Office 2016 for Mac

Overview of UI Extensibility points and corresponding support in Office 2016 for Mac  

Overall, as we’ve mentioned before, we recommend that customers develop macros or VB add-ins in Office for Windows and use Office for Mac to debug, if needed. We’ll continue to ensure compatibility of existing macros and make improvements to the IDE.

Documentation & GitHub

Our developer help for VBA has also undergone some changes. The first thing to highlight is that we’ve moved our content to an “evergreen” model. That means that starting with Office 2013, our help topics are no longer specific to a single version of Office, but instead are combined topics that span all the versions of Office to which they apply. You can still view topics from Office 2010 by clicking Other Versions right below the topic title.

In addition to the evergreen model, we’ve published the VBA documentation on GitHub. By doing so, it allows a much faster process to improve our documentation and a way for you in the community to engage and contribute to the content. At the top of each VBA topic in MSDN, you’ll see a contributors notice like this:

Documentation & GitHub

Simply click the suggest and submit changes link in the Contribute to this content section and you'll be taken to the same article on GitHub where you can propose changes. After you submit your changes, our team is notified immediately and will respond to your change request. You’ll receive notifications about your change request and status; our team may also notify you if we need more information about your change request.

For more details on how to submit changes, bugs, or issues, or to contribute to the content itself through GitHub, see this article.