TweetFollow Us on Twitter

The REALbasic-Office secret decoder ring

Volume Number: 20 (2004)
Issue Number: 7
Column Tag: Programming

REALBasic Best Practice

by Guyren G Howe

The REALbasic-Office secret decoder ring

How to control Microsoft Office from REALbasic

Last time, I discussed some ways of "breaking out" of REALbasic, to call on external applications to supplement what your REALbasic application can do. I lamented that I was unable to explore controlling Microsoft Office from RB, because although it can do that really well, the documentation for this feature was both inadequate and horribly, egregiously wrong.

Since that time, things have gotten slightly better. There is now a web page (http://www.realsoftware.com/office2004mac/) from which you can download a small number of actual, correct, working examples. But, there is still no documentation to speak of, and what there is, it would lead you to believe that using Office from REALbasic is harder than it really is.

So in this article, I will present the apparently entirely undocumented, super-secret really easy way to control Office from RB.

But First...

Since I can't find anywhere else to put it, a quick aside: there were some errors in my article on REAL World. I had said I thought there were fifty attendees, but it turns out there were over a hundred. I also mistakenly wrote that there were three seminars per day, but what I meant to say was that there were three or four sessions at a time, and a bunch of sessions each day. It was quite a good seminar program.

Ta-Da! The Big Secret

Microsoft Office, on both Macintosh and Windows, incorporates a fairly sophisticated built-in scripting language called Visual Basic for Applications (VBA). The really super secret of controlling Microsoft Office from REALbasic -- the one I had to offer up my first-born and a handful of magic beans for -- is that REALbasic understands the entire VBA namespace. This means that essentially every term you can see in Word's object inspector (more on that in a moment) can be used in REALbasic. Classes from Word can be used in REALbasic just by sticking the letters Word in front of them (and similarly for Excel and PowerPoint), and method and function calls on those classes can (with one type of exception) be used unmodified. So, for example, you can fetch the text of the front most Word document with the following code:

GetTheFrontDocument()
A function that returns the text of the front most Word document
Sub GetTheFrontDocument() As String
dim w As New WordApplication
dim doc As WordDocument = w.ActiveDocument()
Return doc.Content().Text
End Sub

So the Word Document class becomes the WordDocument class in REALbasic. Also, the global methods and properties in VBA become method calls and properties on WordApplication, ExcelApplication, or PowerPointApplication in REALbasic.

There. The secret's out. Not much to it, really. Now I'll just fill in a few details, and explore some code examples.

Named Arguments

The only major difference between VBA and REALbasic is that VBA supports a nice feature called named arguments. This means that rather than having to remember, and write an ordered list of bare values for the arguments to a method call, you can provide them as assignment statements, like the last line of this code snippet (taken from the REALbasic built-in help for the Office class):

Example of Replace in VBA

Example Visual Basic for Applications code to perform a find and replace

Selection.Find.ClearFormatting
Selection.Find.Replacement.ClearFormatting
With Selection.Find
.Text = "find this"
.Replacement.Text = "replace with"
.Wrap = wdFindContinue
.Format = false
.MatchCase = false
.MatchWholeWord = false
.MatchWildcards = false
.MatchSoundsLike = false
.MatchAllWordForms = false
End With
Selection.Find.Execute Replace:=wdReplaceAll

This is great, but the translation into REALbasic, given in the built-in documentation, doesn't work. Here's how to actually do it:

The previous example, in REALbasic

Using the secret decoder ring, we translate the last example into REALbasic

Dim word as New WordApplication
Dim find As WordFind = word.ActiveDocument.Content.Find

find.ClearFormatting
find.Replacement.ClearFormatting
find.text = "find this"
find.Replacement.Text = "replace with"
find.Wrap = Office.wdFindContinue
find.Format = False
find.MatchCase = false
find.MatchWholeWord = false
find.MatchWildcards = false
find.MatchSoundsLike = false
find.MatchAllWordForms = false

// Now the fun stuff

Dim replaceParam as New OLEParameter
replaceParam.Value = Office.wdReplaceAll

// according to the docs on Find.Execute the Replace parameter is the 11th
replaceParam.Position = 11

find.Execute replaceParam

If you had more than one named parameter, you would use multiple OLEParameter objects, one for each named parameter, and you just pass them all, in any order, to the method call.

A Larger Example

I'm now going to go through a small, entirely artificial piece of code, intended to cram together a variety of techniques. This article is not remotely large enough to attempt even a quick survey of Office's impressive programming features, but I hope I've presented you with just enough to get you up, and going on your own.

The code will search through all the comments in the front most Word document. It will find all the comments that start with the word test followed by two numbers (all separated by spaces). Any such comment will be replaced by a table with the number of rows and columns given by the two numbers, and then the words "Hello, World" will be placed into the cell in the upper, left corner of the table. I'll go through not only the code, but more importantly how I worked out how to write it. I'll be working with Word X, not Word 2004. I don't consider the new version a worthwhile upgrade, so what you see will probably be slightly different in the newer version (although the code should still work the same).

Note that while the example, and my comments refer to Word, the same ideas apply to Excel and PowerPoint (except that, oddly enough, PowerPoint doesn't support macro recording).

Word's Macro Environment

Most of what you need to know, you can learn from within Word itself. In the Tools menu, you'll find a Macro submenu, which provides access to Word's programming features. In this menu, the REALbasic Editor command just launches REALbasic. The Record New Macro... command opens a dialog for you to name a new Macro, which is what Office calls a program written in VBA.


Figure SEQ Figure \* ARABIC 1: The Record Macro dialog

After you click OK in this dialog, you can execute a series of actions, and Word will translate those actions into a VBA program to do the same thing again. Note that you can't click to move the insertion point while you're recording a macro. There isn't any way for Word to turn that action, that only makes sense in that document (scrolling to that point, in a window of that size) into a set of actions repeatable anywhere.

While you're recording the macro, Word shows a tiny little window with stop and pause buttons:


Figure SEQ Figure \* ARABIC 2: The Macro recording palette

Now, just carry out the sorts of actions you want REALbasic to control, then hit the stop button in the little window. Next, go back to the Macro submenu and choose Macros.... You will then see a window showing the name of the macro you just recorded, along with any other macros you have previously written or recorded:


Figure SEQ Figure \* ARABIC 3: The Macros window

Click on the name of the macro you just recorded, then click Edit. Here is what I got when I recorded a macro in which I created a table along the lines of our little project:


Figure SEQ Figure \* ARABIC 4: The Word Macro editor

There are also other windows showing at this point, but describing this whole programming environment is outside the scope of this document, so I will stick to only what you need most for your REALbasic work.

The Object Browser

Recording a macro will generally give you a good idea of the kind of commands you need to execute to do something. You can also examine every available command, and class in Word by opening the Object Browser. You can do this by clicking a button on the toolbar you see in the macro editing environment:


Figure SEQ Figure \* ARABIC 5: The Object Browser button

Alternately, you can choose Object Browser from the View menu. Any of these will show Word's Object Browser:


Figure SEQ Figure \* ARABIC 6: The Word Object Browser

Note the search box in the middle, at the top (results appear in the blank area). The business part for our purposes is below the blank area. The list of Classes is comprehensive. <globals>, shown in the screen shot, are the methods, and properties available in the WordApplication class in REALbasic.

When you click on a class, the properties, methods, and constants are shown to the right of the class name. If you click on something shown there, its details are shown below, and it is all hyperlinked. This is actually how I developed the code for the example. Well, that, and examining the one working Word example that REAL Software has published.

There are some books on VBA (I understand the O'Reilly book -- ISBN 1-56592-358-8 -- is quite good), and a lot of material online. A bit of drill-down in the Object Browser, and some experimentation, gave me code to do my little example fairly easily.

The Example

To finish up, the example.

ReplaceCommentsWithTables

An example that finds comments in the front most Word document, replacing those that begin with the word table with a table whose dimensions depend on the rest of the comment

Sub ReplaceCommentsWithTables()
  Dim word as New WordApplication
  Dim c As WordComments
  c = word.ActiveDocument.Comments
  
  Dim counter As Integer
  Dim comment As WordComment
  Dim content() As String
  Dim width, height as Integer
  Dim location As WordRange
  if c.Count > 0 then
    counter = 1
    do
      comment = c.Item(counter)
      content = Split(comment.Range.Text(), " ")
      if content(0) = "table" then
        height = content(1).val
        width = content(2).val
        location = comment.Reference
        location.Tables.Add(comment.Reference, width, height)
        location.Tables.Item(1).Cell(1, 1).Range.Text = "hello, world"
      else
        counter = counter + 1
      end if
    loop until counter >= c.Count
  end if
End Sub

The only things that bear explaining here are that a Range in VBA is any point in the document, or any continuous section of text in the document. A Comment object has several Range properties. The one called Range is the actual content of the comment. The one called Reference is the location of the comment in the main text. Also, adding something (in this case, a table) to a range replaces the range's contents (in this case, the comment) with that table. Finally, collections of things in VBA will usually have an Item() function to fetch the collection's contents.

Apart from that, I hope you find that the mostly clear names for things in VBA, the ready availability of example code online, and the ability to record a macro if you want to know how to do something, will make this very useful feature of REALbasic surprisingly easy to use.

Brief aside: Just before I finished this, REAL Software announced a product called Office Power Pack, based on this feature in REALbasic. And Microsoft themselves have written some of the software that ships with Office (the installer and the query tool) in REALbasic. This is a practical feature indeed, and the market for Office add-ons or applications that can work with Office has to be substantial.

Finally, I will note that REALbasic's Office features are almost perfectly cross-platform, without modification other than to path strings and the like.


Guyren G Howe works in artificial intelligence research, after years of work as a technical write,r and developer. He is married with one child, is an Australian, and lives in Austin, Texas. Guyren has been working with REALbasic for several years. Most notably, he wrote the REALbasic Curriculum Project, an extensive computer science curriculum, for REAL Software (available from the REALbasic website). You can contact Mr. Howe at realbasic@mactech.com

 

Community Search:
MacTech Search:

Software Updates via MacUpdate

ExpanDrive 5.4.4 - Access cloud storage...
ExpanDrive builds cloud storage in every application, acts just like a USB drive plugged into your Mac. With ExpanDrive, you can securely access any remote file server directly from the Finder or... Read more
Dash 3.4.3 - Instant search and offline...
Dash is an API documentation browser and code snippet manager. Dash helps you store snippets of code, as well as instantly search and browse documentation for almost any API you might use (for a full... Read more
Civilization VI 1.0.2 - Next iteration o...
Sid Meier’s Civilization VI is the next entry in the popular Civilization franchise. Originally created by legendary game designer Sid Meier, Civilization is a strategy game in which you attempt to... Read more
TurboTax 2016 - Manage your 2016 U.S. ta...
TurboTax guides you through your tax return step by step, does all the calculations, and checks your return for errors and overlooked deductions. It lets you file your return electronically to get... Read more
Microsoft Office 2016 15.30 - Popular pr...
Microsoft Office 2016 - Unmistakably Office, designed for Mac. The new versions of Word, Excel, PowerPoint, Outlook and OneNote provide the best of both worlds for Mac users - the familiar Office... Read more
FotoMagico 5.3 - Powerful slideshow crea...
FotoMagico lets you create professional slideshows from your photos and music with just a few, simple mouse clicks. It sports a very clean and intuitive yet powerful user interface. High image... Read more
Acorn 5.6.1 - Bitmap image editor.
Acorn is a new image editor built with one goal in mind - simplicity. Fast, easy, and fluid, Acorn provides the options you'll need without any overhead. Acorn feels right, and won't drain your bank... Read more
iMazing 2.1.8 - Complete iOS device mana...
iMazing (was DiskAid) is the ultimate iOS device manager with capabilities far beyond what iTunes offers. With iMazing and your iOS device (iPhone, iPad, or iPod), you can: Copy music to and from... Read more
Logic Pro X 10.3 - Music creation and au...
Logic Pro X is the most advanced version of Logic ever. Sophisticated new tools for professional songwriting, editing, and mixing are built around a modern interface that's designed to get creative... Read more
Microsoft Remote Desktop 8.0.37 - Connec...
With Microsoft Remote Desktop, you can connect to a remote PC and your work resources from almost anywhere. Experience the power of Windows with RemoteFX in a Remote Desktop client designed to help... Read more

Red's Kingdom (Games)
Red's Kingdom 1.0 Device: iOS Universal Category: Games Price: $4.99, Version: 1.0 (iTunes) Description: Mad King Mac has kidnapped your father and stolen your golden nut! Solve puzzles and battle goons as you explore and battle your... | Read more »
Turbo League Guide: How to tame the cont...
| Read more »
Fire Emblem: Heroes coming to Google Pla...
Nintendo gave us our first look at Fire Emblem: Heroes, the upcoming mobile Fire Emblem game the company hinted at last year. Revealed at the Fire Emblem Direct event held today, the game will condense the series' tactical RPG combat into bite-... | Read more »
ReSlice (Music)
ReSlice 1.0 Device: iOS Universal Category: Music Price: $9.99, Version: 1.0 (iTunes) Description: Audio Slice Machine Slice your audio samples with ReSlice and create flexible musical atoms which can be triggered by MIDI notes or... | Read more »
Stickman Surfer rides in with the tide t...
Stickson is back and this time he's taken up yet another extreme sport - surfing. Stickman Surfer is out this Thursday on both iOS and Android, so if you've been following the other Stickman adventures, you might be interested in picking this one... | Read more »
Z-Exemplar (Games)
Z-Exemplar 1.4 Device: iOS Universal Category: Games Price: $3.99, Version: 1.4 (iTunes) Description: | Read more »
5 dastardly difficult roguelikes like th...
Edmund McMillen's popular roguelike creation The Binding of Isaac: Rebirth has finally crawled onto mobile devices. It's a grotesque dual-stick shooter that tosses you into an endless, procedurally generated basement as you, the pitiable Isaac,... | Read more »
Last week on PocketGamer
Welcome to a weekly feature looking back on the past seven days of coverage on our sister website, PocketGamer. It’s taken a while for 2017 to really get going, at least when it comes to the world of portable gaming. Thank goodness, then, for... | Read more »
ROME: Total War - Barbarian Invasion set...
To the delight of mobile strategy fans, Feral Interactive released ROME: Total War just a few months ago. Now the game's expansion, Barbarian Invasion is marching onto iPads as a standalone release. [Read more] | Read more »
Yuri (Games)
Yuri 1.0 Device: iOS iPhone Category: Games Price: $3.99, Version: 1.0 (iTunes) Description: It's night. Yuri opens his eyes. He wakes up in a strange forest.The small, courageous explorer rides on his bed on casters in this... | Read more »

Price Scanner via MacPrices.net

Laptop Market – Flight To Quality? – The ‘Boo...
Preliminary quarterly PC shipments data released by Gartner Inc. last week reveal an interesting disparity between sales performance of major name PC vendors as opposed to that of less well-known... Read more
IBM and Bell Transform Canadian Enterprise Mo...
IBM and Bell Canada have announced they are joining forces to offer IBM MobileFirst for iOS market-ready enterprise applications for iPad, iPhone or Apple Watch. Bell, Canada’s largest communications... Read more
Otter Products is Closing… For a Day of Givin...
On Thursday, Feb. 9, Otter Products is closing doors to open hearts. In partnership with the OtterCares Foundation, the company is pausing operations for a day so all employees can volunteer with... Read more
15-inch 2.2GHz Retina MacBook Pro on sale for...
Amazon has 2015 15″ 2.2GHz Retina MacBook Pros (MJLQ2LL/A) available for $1799.99 including free shipping. Apple charges $1999 for this model, so Amazon’s price is represents a $200 savings. Read more
Back in stock: Apple refurbished 13-inch Reti...
Apple has Certified Refurbished 2015 13″ Retina MacBook Pros available for up to $360 off original MSRP, starting at $1099. An Apple one-year warranty is included with each model, and shipping is... Read more
CalcTape for macOS 1.2 Adding Machine App for...
schoettler Software has announced CalcTape 1.2, an update to their desktop calculator for macOS. When it comes to adding long columns of numbers, doing complex calculations or playing around with... Read more
New MacBooks And MacBook Pros WIth Kaby Lake...
Digitimes’ Joseph Tsai cites a Chinese-language Economic Daily News (EDN) report that unnamed market watchers are predicting Apple MacBook shipments to grow 10 percent in 2017, and projecting 15... Read more
New 2016 13-inch MacBook Pros on sale for up...
B&H Photo has the new 2016 13″ MacBook Pros in stock today and on sale for up to $150 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 13″ 2.9GHz/512GB Touch Bar MacBook Pro... Read more
New 15-inch Touch Bar MacBook Pros in stock a...
B&H Photo has the new 2016 15″ Apple Touch Bar MacBook Pros in stock today and on sale for up to $150 off MSRP. Shipping is free, and B&H charges NY sales tax only: - 15″ 2.7GHz Touch Bar... Read more
Opera Announces Neon Concept Browser For Mac
Opera is inviting users to get a glimpse of what Opera for computers could become with its Opera Neon browser concept. Each Opera Neon feature is described as “an alternate reality” for the Opera... Read more

Jobs Board

*Apple* & PC Desktop Support Technician...
Apple & PC Desktop Support Technician job in Los Angeles, CA Introduction: We have immediate job openings for several Desktop Support Technicians with one of our Read more
*Apple* Retail - Multiple Positions - Apple,...
SalesSpecialist - Retail Customer Service and SalesTransform Apple Store visitors into loyal Apple customers. When customers enter the store, you're also the Read more
*Apple* Retail - Multiple Positions (Multi-L...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
*Apple* Retail - Multiple Positions - Apple,...
Job Description: Sales Specialist - Retail Customer Service and Sales Transform Apple Store visitors into loyal Apple customers. When customers enter the store, Read more
*Apple* & PC Desktop Support Technician...
Apple & PC Desktop Support Technician job in Stamford, CT We have immediate job openings for several Desktop Support Technicians with one of our most well-known Read more
All contents are Copyright 1984-2011 by Xplain Corporation. All rights reserved. Theme designed by Icreon.