GENERAL IMPRESSIONS

• It's doable, but takes alot of work if you want to clean up the code, especially for such a huge macro as Enveloper.
• The Visual Basic Editor's MDI interface sucks. It wastes alot of precious screen real estate. At least some of the windows can now float outside the MDI parent, but I sure wish the Object Browser could also float outside.
• The resulting files are huge. Enveloper comes in at 1.8MB, even after removing alot of code and consolidation. The original is 445KB!
• The auto-conversion does an OK job. Most the problems that remain can be fixed by running "Debug", "Compile" to find all the syntax errors.
• Use the <Ctrl>J, <Ctrl>I, <Ctrl><Shift>J, <Ctrl><Shift>I, <Ctrl><Space>, <TAB>, etc. key combinations to get as much help completing commands as VBA will give you. It'll even list user Function/Subs. (Look in the Edit menu for these short-cut keys)
• Also make use of the Object Browser (<F2>) to get a quick summary of available objects/properties/methods. Use the Tools, Reference menu of the Visual Basic Editor to add references so they appear in the Object Browser.
• You don't have to use Forms (new name for dialogs) off the bat. The old WordBasic custom dialogs still work. I don't know what the performance hit or memory usage are. Enveloper right now is still using the old dialog boxes.
• Use Debug, Compile from the Visual Basic Editor menu to compile your code without running to find problems before you start.
• Export your code often to make backups. The exported files are Text format.

  Woody and I also have a macro to export all macros at once.

SPECIFIC HINTS

• Per Lee's suggestion, rename your Project name immediately to something other than "TemplateProject"
• The ByVal and ByRef distinction for procedure (Function or Sub) parameters are VERY important for Declare statements. You can easily crash the system if they are done incorrectly. (If you don't use the keyword, ByRef is assumed.)

• You can place all your Declares in a single module, preceded by Public, then they'll be available in all other modules. Note that you can use/access Public variables/constants/procedures directly without having to precede their names with the module name (unless there's a name conflict).

• Use Const whenever possible. I have a single module called "Declarations" that contains only constants and Declare statements. Variables such as AppName$, AppVer$, are now declared as:

  	Public Const AppName$ = "Enveloper"
  	Public Const AppVer$ = "97"
  

  This way, I no longer have to use an InitApp procedure in every macro just to set these variables on a per module basis.

• If you have ANY procedures that need to be used from more than one module, consider placing them in a separate "Utils" module as Public to be shared amongst all modules.

  The venerable Swap$() is a good example.

• Having Public procedures is great, but YOU CAN'T GIVE THEM DESCRIPTIONS! When you go to Tools, Customize to add a Public Sub to a menu or toolbutton, you can list the names of the Public Subs, but their Descriptions will be blank. Not very friendly at all.
• As you've seen in the migration article, global variable retain their values until the template is unloaded, or an error occurs. That means you have to explicitly set global variables to 0 or "" (empty string) if you depend on that.

  The converter automatically does that for you in MAIN, but you may not always access a module via MAIN (Enveloper uses multiple entry points per macro).

  Since I had a InitGlobals() procedure for all significant macros, I can move those initialization statements there from MAIN.

• If you use ReDim to change the dimension an array, you can no longer provide it with an explicit size using a Dim statement in the declaration section. That is, if your old code had:

  	Dim myarray(5)
  	Sub MAIN
  		...
  		ReDim myarray(10)
  		...
  	End Sub
  

  That is now converted to:

  	Dim myarray()
  	Sub MAIN
  	ReDim myarray(5)
  		...
  		ReDim myarray(10)
  		...
  	End Sub
  

• The problem is, the converter inserts the ReDim statements into the FIRST procedure to initialize the sizes of arrays. THIS IS A BUG, since the first procedure may NOT be MAIN. Ooops. This is fixed in the Gold version.
• Supposedly, it's better to use '&' instead of '+' to build strings, so you should do an Edit/Replace on the entire project for:

• In WordBasic, the variable, foo, is DIFFERENT than foo$. Not so in VBA. That '$' is only shorthand to say that foo is a String. Thus if you have:

  	Dim foo$
  

  Then

  	foo = "Ha"
  

  and

  	foo$ = "Ha"
  

  are equivalent.

• Use built-in constants whenever possible. For instance:

  vbNewLine instead of Chr$(13)

  vbYesNo (for MsgBox) instead of.....4?

• You no longer need IsMacro(). It's NEVER true anymore.
• If you have macros that modify other macros, you'll have to rewrite them. You have to access them through the Application.VBE object, a member of the VBIDE object library (Microsoft Visual Basic for Applications Extensibility library). Its methods are weak for editing macros. E.g., its find/replace and selection process is very weird. You can only find/replace a line at a time....
• When comparing objects, use the "Is" operator, not "=" or "<>". (Hint from Smitch)
• If you want to unprotect a document, use the Unprotect method. You cannot use:

  	ActiveDocument.Protect wdNoProtection
  

  even though that's how you check the protection status. That is inconsistent, in my view.

• Protected forms are a pain to work with using Word/VBA, because Microsoft decided to disallow many commands. For instance, getting the contents of bookmarked text in a protected form should work like this using the old WordBasic command:

  	MsgBox WordBasic.[GetBookmark$]("Date")
  

  But the following VBA is not allowed because the document is protected:

  	MsgBox ActiveDocument.Bookmarks("Date").Range.Text
  

  To do it via VBA, you have to first unprotect the form, run the above command, then protect the form again. What a pain.

• As long as we're on Forms. There's a new "Calculate on Exit" attribute for Form Fields that if enabled, will cause all auto-calculated fields in the form to update when you exit the field. I'm not sure what the performance will be if you have alot of fields that need to be updated.

  To do the update manually, you'll have to resort to the WordBasic command:

  	WordBasic.SetFormResult "myCalcField"
  

  to update the "myCalcField". There is NO Word/VBA equivalent.

• In my code after formatting a picture via "WordBasic.FormatPicture", I now need an extra "CharLeft 1, 1" to reselect the picture. This was not the case in previous versions of Word.
• Be careful with On Error handling! In WordBasic, the On Error only applied to a procedure, and was cleared once you exit the procedure. VBA treats them differently. That may be why all your On Errors got converted to:

  	On Error GoTo -1 : On Error GoTo YourLabel
  

• Use of "Exit Sub", "Exit Function", "Exit Property" may be preferable to using "GoTo Bye" that is prevalent in WOPR code, but they don't work well when you want to have clean-up code for the procedure.
• If you have two templates open that contain toolbars:

  1. DocA.doc has a toolbar named "Foo"

  2. DocB.doc has a toolbar named "Bar"

  From DocB.doc, try to change "Bar" to "Foo", you'll get the error message that "Foo" already exists and Word won't let me change it.

  This is a BUG. Since "Foo" is not accessible to DocB.doc, it should not be an error. If you close DocA.doc, then you can rename "Bar" to "Foo"

• If you use the "WordBasic.MsgBox" call, and an Office Assistant is active, then your messages will come from the Office Assistant! If you just use "MsgBox", you just get the regular old message box. Jim and Lee found out, though, the WB MsgBox command's parameter order is different from the VBA order so one can't simply remove the "WordBasic." prefix globally and be rid of the Office Assistant form of the messaging, you would also have to move the WB buttons param left one slot. Otherwise VBA just swallows (no error) the MsgBox command. Tedious and error-prone.

  ' WB: prompt, title, buttons
  ' VBA: prompt, buttons, title

• If you need the document that owns the active project (the one that has focus), try (a tip from Smitch):

  	szFile = VBE.ActiveVBProject.VBComponents(1).Properties("Name")
  

  In Word the "ThisDocument" VBComponent should always be at index 1. Note: VBComponent.Properties("Name") returns the pointer to the Name method. VBComponent.Properties("Name").Value returns the default return value of the method.

SPECIFIC ISSUES

• I have a lot of code like:

  	Declare Function foo Lib "MyLib" Alias "fooA"(\
  		myarg As Long) As Long
  

  The macro converter fails, because it doesn't stick a space in from of the resulting line-continuation character. Woody and I have a macro that will fix this, but it's a pain.

• You can no longer Declare the same Function or Sub more than once in a module.
• In previous versions of Word, I can get the value of the FormatDefineStyleFont (using GetCurValues) and pass it directly to FormatFont, since they had the same fields. No more. I had to manually copy all the fields into a new variable before calling FormatFont. I have to do the equivalent of:

  	Dim fdsf As FormatDefineStyleFont
  	GetCurValues fdsf
  	Dim ff As FormatFont
  	ff.Font = fdsf.Font
  	ff.Points = fdsf.Points
  	....
  	FormatFont ff
  

• There's a problem converting menus. Enveloper had two menu entries in the Tools menu that got converted, but the locations were wrong. I went to change the locations using the new Tools, Customize dialogs. I also wanted to add an icon to the entries. No matter what I did, once I close the document template, the changes were lost.

  Not until I REMOVED the menu entries altogether and added new ones from scratch did the changes hold.

• Word's FileOpen dialog box has a limit on how many files you can open. The limit is not the number of files, but the number of characters (255). That is, the files specified by the file names that fit into the first 255 characters are opened.
• Do you want to know what's available for built-in dialogs? Look in the help file for the topic, "built-in dialog/argument lists". Don't expect to be able to access all elements in a built-in dialog via code. Rats.
• In previous versions of Word, it was relatively simple to tell what would happen if you have more than one macro with the same name. The one in the active template (or the attached template of the active document) takes precedence, then it's the global Add-Ins in alphabetical order, then NORMAL.DOT, then built-ins. Well, things are different now, even when using the WordBasic.Call syntax that is supposed to implement the old WordBasic behavior.
• Things are complicated by the ability to attach Public Subs to the "ThisDocument" object of a document or template and even the ability to add code modules to documents. Moreover, the order of precedence changes when you use the VBA Application.Run call.
• There are three ways to create a "Hello" macro for each document or template:
  • "Public Sub Hello()" in "ThisDocument"
  • "Public Sub Hello()" in a code module (we'll use "Module1" in the following examples)
  • A module named "Hello" with a "Public Sub MAIN()"
• Let's create four sets of these:
  • In a document called "ActiveDocument.doc" that is attached to "AttachedTemplate.dot"
  • In the "AttachedTemplate.dot"
  • In an Add-In template called "Addin.dot"
  • In NORMAL.DOT
• The table below shows the precedence order when using WordBasic.Call and Application.Run.

• If you try to replace a built-in command, such as "ViewHeader", the order of precedence follows that of Application.Run, except that the built-in command comes last. If you have additional Add-ins, they would be ordered alphabetically.
• What's important to notice here?
  • There's a bug in WordBasic.Call for ActiveDocument.ThisDocument.Hello. It should have come first.
  • Normal.dot is no longer last!!!! If a user has defined her own functions, there's no way an Add-in can override it. That is, if the user created her own FileNew, then our WOPR FileNew won't have any effect.

  Copyright © 1997 Vincent Chen.

   

  *This creates an error if ActiveDocument.ThisDocument.Hello and AttachedTemplate.ThisDocument.Hello both exist. This means that you cannot have Public Subs in the ThisDocument object of a template and be able to use Application.Run, since every time you create a document based on that template, those subs will be duplicated in the document. Then any attempt to run those Subs via Applica-tion.Run will generate an error. You can, however, call Application.Run "AttachedTemplate.ThisDocument.Hello" to reach the one in the underlying template.

This file is also available for download as a zipped Word95 document.

Migrating to Office97

---

Woody Leonhard