Depending on your level of HTML expertise, it may interest you to know that you can type scripts directly into your HTML files (rather than having them in their own .js files). These scripts, when embedded in an HTML file, can call into the wizard engine just as the your default.js script file and other .js files can. However, when the script is inside an HTML file, instead of using the object name wizard, as you do in .js files, you use the object name window.external. You can also create symbols in the scripts within your HTML files, by calling the same AddSymbol method; and, as usual, instead of the name wizard, you use the name window.external, as in the following line: window.external.AddSymbol(“HTML_VIEW”, true); In the previous list I also mentioned default symbols. The wizard engine provides many default symbols that your scripts can access. For these symbols’ names, you do not need to call AddSymbol. Here are some of the more common predefined symbols: HTML_PATH. This is the path where the HTML files reside. Normally, it will be the wizard’s path, followed by the directory name HTML, followed by the locale (such as 1033, which is the default). IMAGES_PATH. This is the path where the image files reside. It will typically be the wizard’s path, then the directory name Images. PRODUCT_INSTALLATION_DIR. This is the root of the particular product for which the wizard works, such as C++. For example, the default product installa- tion for C++ is c:\Program Files\Microsoft Visual Studio .NET\Vc7\. PROJECT_NAME. This is the name of the project, the name the IDE user typed into the New Project dialog box. PROJECT_PATH. This is the path to the project, the project path the IDE user typed into the New Project dialog box, followed by the project name. Remember that this symbol contains both the path and filename, not just the path. SCRIPT_PATH. This is the path to the directory containing the scripts. Normally, it will be the wizard’s path, followed by the directory name Scripts, followed by the local, which is 1033 by default. START_PATH. This is the wizard’s path, the path of the base directory contain- ing the HTML, Scripts, Images, and Templates directory. It will be under the main Wizards directory; for example, for the MFC Application Wizard it will be c:\Program Files\Microsoft Visual Studio .NET\Vc7\VCWizards\mfcappwiz. TEMPLATES_PATH. This is the path where you can find the template files. Nor- mally, it will be the wizard’s path, followed by the name Templates, followed by the locale, which, again, is 1033 by default. WIZARD_NAME. This is the name of the wizard, such as mfcappwiz. 262 Chapter 12 To see the full list of predefined symbols, open the Visual Studio .NET online help. Go to the Contents and drill down to Visual Studio .NET➪Visual C++➪Creating and Managing Visual C++ Projects➪Designing a Wizard➪Files Created For Your Project➪The .vsz File➪Custom Parameters in the Wizard .vsz File. You can control the values of the predefined symbols from with your .vsz file. (Remember, the .vsz file is the file in the projects directory that provides information to Visual Studio .NET about the wizard.) For example, if you add the line: Param=”IMAGES_PATH = c:\MyImages” to your file, the IMAGES_PATH symbol will get set to “c:\MyImages”. Make sure, however, that you follow the format precisely: Start with the word Param with no space after it, then an equal sign with no space after it, followed by a string in double quotes. The format of this string in double quotes must also be exact. Start with the name of the symbol, then a space, which is mandatory; next put an equal sign, followed by another mandatory space; finally, put the value for the symbol, without its own double quotes around it. (The final double quotes are for the string itself.) You can also create your own symbols that you can pass into the scripts, as in this line from a .vsz file. Param=”MYSYMBOL = SOMENAME” With this line in your .vsz file, the scripts will now be aware of the symbol MYSYM- BOL, and the symbol’s value will be SOMENAME. When you create a wizard, you may have multiple HTML pages, and if you give your users the option to go to the various pages and make selections, they may choose to skip some of the pages. For the selections on those pages, then, you’ll want to pro- vide defaults for the symbols your HTML files set. The one HTML file that always opens when the wizard runs is called default.htm; therefore, put the defaults in default.htm. The defaults go in the <HEAD> section, and they look like this: <HEAD> <SYMBOL NAME=”APP_BASE_CLASS” TYPE=”text” VALUE=”CWinApp”></SYMBOL> <SYMBOL NAME=”ATTRIBUTED” TYPE=”checkbox” VALUE=”true”></SYMBOL> </HEAD> These two SYMBOL lines provide default values for the APP_BASE_CLASS and ATTRIBUTED symbols. For the former, which is a text box, the default is the string “CWinApp”. For the latter, which is a checkbox, the default is the value true. (A checkbox has only two values, true and false.) Rendering the Template Files When you copy the files from the templates directory to the project directory, you use a process called rendering. The wizard engine can render files by scanning through the Creating Project Wizards 263 text in the files, replacing various strings with other strings, and then copying the resulting file into the project directory. Or, in the case of binary files, you can optionally copy files directly without attempting to process them as text. As an example of this process, open the following file in the text editor of your choice: C:\Program Files\Microsoft Visual Studio .NET\ Vb7\VBWizards\ComClass\Templates\1033\ComClass.vb This is the template file that gets translated into the ComClass.vb file when you cre- ate a new COM class in your VB.NET project. You can see this process at work if you right-click a VB.NET project in the Solution Explorer, choose Add➪Add New Item, scroll down, and choose COM Class. (Although this is for an item template rather than a project template, the concept is the same, and this ComClass.vb file is a good exam- ple.) Here’s one line from the template file: Public Const ClassId As String = “[!output GUID_COCLASS]” This line gets translated into a line such as the following: Public Const ClassId As String = “543E3E5D-40DA-4AAC-8C17-1481B30B693E” However, when you create a COM class, you will see a different GUID appear on this line. In order to render the Connect.vb file, the wizard engine replaces the text [!output GUID_COCLASS] with the GUID 543E3E5D-40DA-4AAC-8C17-1481B30B693E. Where did this GUID come from? From the script. The script called a function to obtain a unique GUID and stored it in the symbol called GUID_COCLASS. Then, when the wizard engine renders the ComClass.vb file, the engine sees the symbol GUID_COCLASS, preceded by the characters [!output, and followed by the character ]; the engine replaces the entire string with the value stored in the symbol. (If the script engine only sees GUID_COCLASS without the preceding and following characters, the engine will not replace the string.) Now open the script file C:\Program Files\Microsoft Visual Studio .NET\Vb7\ VBWizards\ComClass\Scripts\1033\default.js. Here are the two lines of code from the script that generate the GUID and store it in the GUID_COCLASS symbol: var strRawGuid = wizard.CreateGuid(); wizard.AddSymbol(“GUID_COCLASS”, wizard.FormatGuid(strRawGuid, 0)); The first line generates a GUID and stores it in the strRawGuid variable. The sec- ond line takes the strRawGuid variable and writes it to the symbol called GUID_COCLASS, which is the symbol in the ComClass.vb template file. Thus, each time the wizard runs, a new GUID ends up in the project’s ComClass.vb file. Now take a look at the template file C:\Program Files\Microsoft Visual Studio .NET\Vc7\VCWizards\mfcappwiz\templates\1033\childfrm.cpp. This file is part of the MFC Application Wizard, and this wizard is for a project not a project item. (To see the MFC Application Wizard, choose File➪New➪Project; in the New Project dialog box on the left side, choose Visual C++ Projects, and on the right side, choose MFC Application.) 264 Chapter 12 TEAMFLY Team-Fly ® The childfrm.cpp template file contains several symbol replacements as you saw in the ComClass.vb template file. However, this file also contains some if-statements. Here’s one if-block: [!if PROJECT_STYLE_EXPLORER] #include “[!output TREE_VIEW_HEADER]” #include “[!output VIEW_HEADER]” [!endif] The if lines go inside brackets; the left bracket is followed by an exclamation point and then the word if. This time the symbol in question, PROJECT_STYLE_EXPLORER, is not set by the script file but by an HTML file. The symbol is initialized by the default.htm file found in the directory C:\Program Files\Microsoft Visual Studio .NET\Vc7\VCWiz- ards\mfcappwiz\html\1033. Here’s the line from the default.htm file: <SYMBOL NAME=”PROJECT_STYLE_EXPLORER” TYPE=”radio” VALUE=”false”></SYMBOL> The symbol is then set by this line from the AppType.htm file, found in the same directory (I’ve broken the line up into four lines so it fits on the page): <INPUT TYPE=”radio” CLASS=”Radio” ACCESSKEY=”x” TITLE=”Select browser-style user interface.” NAME=”projtype” VALUE=”radiobutton” ID=”PROJECT_STYLE_EXPLORER” onClick=”OnProjectStyle();”> When the user of the HTML page (that is, the user of the wizard) checks or unchecks the radio button, the PROJECT_STYLE_EXPLORER symbol gets set to true or false, respectively. (The user unchecks the radio button implicitly by checking another radio button in the group.) When the user checks the radio button, the OnProjectStyle function runs. This function is found in the same AppType.htm file, and you’re wel- come to take a look at it if you want; it sets other symbols based on the project type that you select. To compare two symbols, you can use two comparison operators that have the same syntax as their C++ equivalents: == and !=. You can also use + and - and to combine two numeric symbols. And you can embed if-statements, like so: [!if PROJECT_STYLE_EXPLORER] [!if LIST_VIEW] and then, later, end the inner if-statement: [!endif] and later still, to end the outer if-statement: [!endif] Creating Project Wizards 265 You can also use AND and OR relationships using the standard C++ like && for AND and || for OR, as in the following two lines: [!if APP_TYPE_MDI && SPLITTER] and [!if HTML_VIEW || HTML_EDITVIEW] Here’s an example of a logical NOT operator, shown by an exclamation point imme- diately before the symbol name: [!if !DOCVIEW] You can use an else-block in your if-statement: [!if MYSYMBOL] and [ !else ] and [!endif] You also can use a limited for loop. One way is to specify an exact count, as here: [!loop = 5] [!endloop] This loops five times. Another way is to use a symbol that contains a numeric value: [!loop = MYCOUNT] [!endloop] Reading a template file can be a bit confusing at times. Take a look at this line from the childfrm.cpp template file: [!output CHILD_FRAME_CLASS]::~[!output CHILD_FRAME_CLASS]() This generates a destructor header line as in: MyChildFrm::~MyChildFrm() 266 Chapter 12 To recap what is happening with these symbols, when you render a template file, the wizard engine replaces the symbols and processes the if-statements to generate a final file. The wizard engine then copies the final file into the project directory. Here, then, is a sample line from a script file that renders a template file: wizard.RenderTemplate(strTemplate, strTarget, bCopyOnly, true); The RenderTemplate function copies a template file (whose path and filename is given by the first parameter, strTemplate) to a final file (given by the second param- eter, strTarget). The third parameter specifies whether to render the file or to just copy it without processing the text. Pass true if you want to copy the file without pro- cessing the text (as in the case of a binary file) or false if you do want to process the file. For the final parameter, pass true if you want to overwrite any preexisting file during the copy process. (The third and fourth parameters are optional; the defaults are both false, meaning the RenderTemplate function will process the text file and will not overwrite an existing file.) Be careful if you choose false for the fourth parameter of RenderTemplate (or if you simply take the default), because, here, the opposite of overwrite is append. Thus, if you choose false for the final parameter, instead of overwriting, each time your wiz- ard runs, the target file will be appended to the end of the existing target file. If you’re working with project or source files, this is probably not what you want. In most cases, then, you will want to pass true for the final parameter. If you look at the default.js file for the MFC Application Wizard, you will see it contains no calls to RenderTemplate. The reason is that the file instead calls the AddFilesToProject function, which is in a common JScript file called common.js. I discuss this file in more detail in “The common.js File” section later in this chapter. Wizard Properties When you interact with the wizard engine from within a script, you use the object called wizard, as in the following line of code: var strProjectName = wizard.FindSymbol(“PROJECT_NAME”); This line of code calls the wizard object’s FindSymbol method. The wizard object is an instance of the VCWizCtl class, which implements the COM interface IVCWiz- CtrlUI. This is not the same interface that a wizard normally implements, the IDTWizard interface. That’s because the wizard engine actually implements both interfaces, and your script interacts with the engine through the IVCWizCtrlUI inter- face by using the VCWizCtl object called wizard. Creating Project Wizards 267 The VCWizCtl object has numerous members; you can see the whole list by looking up VCWizCtl in online help index. Here are some of the more important members that you will be using. First, two properties: ActiveXControls. You use this object to obtain a reference to an ActiveX object. For example, the line: fso = new ActiveXObject(“Scripting.FileSystemObject”); will store a reference to the FileSystemObject in the fso variable. You can then use the fso to access the file system. (To see the properties and methods for the FileSystemObject, look up FileSystemObject in the online help index.) dte. This is a reference to the main DTE object that you can use just as you would in macros and add-ins. Now here are a few of the many member functions. AddSymbol. Call this function to add a symbol to the symbol namespace. Pass the symbol name as the first parameter, and the symbol value as the second parameter. For the second parameter you can pass any type. CreateGuid. This function returns a GUID in the form of a string. The string is surrounded by curly braces and includes the hyphens in the GUID. DoesFileExist. Pass a single string to this function. The string contains a path and filename. The function returns a Boolean value indicating whether the file exists. FindSymbol. Call this function to retrieve a value from the symbol namespace. Pass the name of the symbol. If the symbol is not present, the function returns a 0, meaning you can call the function, like so: if (!window.external.FindSymbol(“MY_SYMBOL”)) { window.external.AddSymbol(“MY_SYMBOL”, “Hello”); } GetSystemLCID. This function returns the identifier for the current locale. By default, the identifier is 1033. Navigate. Call this function to open up an external browser window. Pass the URL (such as www.wiley.com) for the first parameter, and the number 1 or 0 for the second parameter. The second parameter is an enumerator specifying whether to open the URL in an external window. The function is borrowed from the ItemOperations object, and that object allows you to pass 0, meaning the current window. However, in this context, the Navigate function always opens in an external window, so it does not matter if you pass 0 or 1. OKCancelAlert. Call this function to display a message box to the IDE user, along with an OK button and a Cancel button. Pass a string containing the mes- sage to display. The function returns true if the user clicks OK and false if the user clicks Cancel. RemoveSymbol. Call this function to remove a symbol from the symbol name- space. Pass the symbol name. 268 Chapter 12 RenderTemplate. Call this function to render a file from the templates directory. RenderTemplateToString. Call this function to render a file to a string. When you do so, the entire contents of the file will be returned by this function in the form of a string. Here’s an example: str1 = wizard.RenderTemplateToString(“myfile.txt”); YesNoAlert. This function displays a message box to the user, along with Yes and No buttons. Pass the message as a string. The function returns true if the user clicks Yes and false if the user clicks No. Regarding the type you can pass to AddSymbol, look closely at this code from a default.js script: var x = 10; x = x + 1; wizard.AddSymbol(“NUMBER”, x); var y = wizard.FindSymbol(“NUMBER”); y = y + 1; wizard.OKCancelAlert(y); The first line declares a variable called x and stores the number 10 in it. The next line adds 1 to x. The third line adds a symbol called NUMBER, and stores the value of x in it, which is 11. The next line creates a new variable called y, and retrieves the value of the symbol called NUMBER. The next line adds 1 to the value. The final line displays the value of y. Since the symbols can hold any type, not just strings, this piece of code func- tions correctly. (If the symbols could only hold strings, it would probably throw an exception.) A Script Wizard Tutorial Using the information in the preceding sections, you are now ready to build a wizard script. To begin, use a text editor of your choice and create the following text file, which you will save as testwiz1.vsz in the C:\Program Files\Microsoft Visual Studio .NET\ Vc7\vcprojects directory: VSWIZARD 7.0 Wizard=VsWizard.VsWizardEngine Param=”WIZARD_NAME = testwiz1” Param=”WIZARD_UI = TRUE” This will tell the Visual Studio .NET about your wizard, including the location. Remember, the IDE obtains the location of the wizard based on the following: ■■ The wizard directory for the current product. ■■ The name of the wizard. This comes from the WIZARD_NAME line in the .vsz file. The IDE combines these two items to get the directory for your wizard. In this case, that will be C:\Program Files\Microsoft Visual Studio .NET\Vc7\VCWizards\testwiz1. Creating Project Wizards 269 In addition to the .vsz file, you can also have an icon file representing the icon that will be displayed in the New Project dialog box. For this example, I chose to simply copy another icon, rather than create my own. You can pick any of the .ico files in one of the project directories and copy it to the same directory as the .vsz file and call it testwiz1.ico. (Its name must match the name of the .vsz file, but it will have the .ico extension.) The one I copied was C:\Program Files\Microsoft Visual Studio .NET\ Common7\IDE\Extensibility Projects\Visual Studio Add-in.ico. (If you create your own icon, make sure the icon is 32 by 32 pixels in size and 16 colors.) Now you have the information the IDE needs for displaying the icon in the New Pro- jects dialog box, and for the IDE to find the wizard. Next you need to create the wizard. The first thing you need to do is create the proper directory structure for the wizard. Here are the directories you will need to create for this example: ■■ C:\Program Files\Microsoft Visual Studio .NET\Vc7\VCWizards\testwiz1 ■■ C:\Program Files\Microsoft Visual Studio .NET\Vc7\VCWizards\testwiz1\html ■■ C:\Program Files\Microsoft Visual Studio .NET\Vc7\VCWizards\testwiz1\ html\1033 ■■ C:\Program Files\Microsoft Visual Studio .NET\Vc7\VCWizards\testwiz1\ scripts ■■ C:\Program Files\Microsoft Visual Studio .NET\Vc7\VCWizards\testwiz1\ scripts\1033 ■■ C:\Program Files\Microsoft Visual Studio .NET\Vc7\VCWizards\testwiz1\ templates ■■ C:\Program Files\Microsoft Visual Studio .NET\Vc7\VCWizards\testwiz1\ templates\1033 These directories comprise the root directory, the HTML and its 1033 directory, the scripts and their 1033 directory, and the templates and their 1033 directory. Remember, your files will go inside the 1033 directories. If your computer is set up for a different culture, you can change the 1033 to your own culture if you want. That way the IDE will be able to locate the files for your specific culture. However, 1033 is the default, and so if you use 1033, you will still be able to use the script. (If you want to see an example of different locales in action, take a look at C:\Program Files\Microsoft Visual Studio .NET\Vc7\VCWizards\mfcappwiz\templates. This directory has several locales under it.) Now comes the fun part, where you will create the files. Remember, the files will sit inside the 1033 directories. There are three such directories, and you will create one file in each directory except for the templates\1033 directory, where you will create two files. You will create a script file, which will perform the project creation. You will cre- ate an HTML file, which will provide the user interface for the wizard. You will also create .cpp and .h files in the templates\1033 directory, which will be rendered into the final project. These two template files will contain various symbols that the wizard engine will replace with strings based on the user’s selections in the user interface. 270 Chapter 12 The format of the HTML file is somewhat complex. For our purposes, here, however, I’ll be keeping it simple; later in this chapter, in the section called “Viewing Your HTML files,” I’ll give you more information about style sheets and other aspects that can give your HTML files a common look and feel. Here, then, is the HTML file. Save this in the HTML\1033 subdirectory and call it default.htm: <HTML DIR=”LTR”> <HEAD> <TITLE>Wizard</TITLE> <STYLE TYPE=”text/css”>@@import url();</STYLE> <SCRIPT> try { var strURL = “ / / /”; strURL += window.external.GetHostLocale(); strURL += “/NewStyles.css”; document.styleSheets(0).imports(0).href = strURL; } catch (e) { var strURL = “C:/Program Files/Microsoft Visual Studio .NET” + “/Vc7/VCWizards/1033/NewStyles.css”; document.styleSheets(0).imports(0).href = strURL; } </SCRIPT> </HEAD> <BODY BGCOLOR=”BUTTONFACE” TOPMARGIN=”0” LEFTMARGIN=”0” RIGHTMARGIN=”0” BOTTOMMARGIN=”0” > &nbsp;<p> <SPAN CLASS=”itemText” TITLE=”Popup message over label.” ID=”isapi_vroot”> <LABEL CLASS=”INDENT” FOR=”CLASS_NAME” ID=”CLASS_NAME_LABEL”><U>C</U>lass name:</LABEL> <BR> <INPUT CLASS=”sideBtnIndent” ID=”CLASS_NAME” ACCESSKEY=”c” > </SPAN> <p> &nbsp;&nbsp;&nbsp; <INPUT CLASS=”CheckBox” TYPE=”checkbox” ID=”INCLUDE_CONST” ACCESSKEY=”d”> <LABEL FOR=”INCLUDE_CONST” ID=”INCLUDE_CONST_LABEL”> &nbsp;&nbsp;&nbsp;&nbsp;<U>I</U>nclude Constructor</LABEL> </DIV> Creating Project Wizards 271 [...]... create add-ins for Microsoft Office products Introducing Office Add-ins It’s important to remember that the Visual Studio NET IDE is not itself really a NET program, and its add-ins are not assemblies; they’re COM objects You could, in fact, write a Visual Studio NET add-in using Visual Studio 6.0 without using any NET features But when you use C# or VB.NET or C+ +.NET to develop an add-in, you’re developing. .. find the COM Add-ins command (On my computer it’s the first in the list.) Click it and drag it to the menu bar I dragged my COM Add-ins command to the Tools menu and put it toward the bottom In Microsoft Word, I put it immediately under Templates and Add-ins, as that seemed like a more-or-less logical place for it In Microsoft Excel, I put it under Add-ins 287 288 Chapter 13 (Remember, the Add-ins menu... support the older add-ins, along with the newer COM add-ins, and the products have two separate dialog boxes for the two kinds of add-ins Normally, the user interfaces distinguish between Add-ins (the older style add-ins) and COM Add-ins (the newer COM style) Today, Microsoft encourages us to create the newer COM add-ins Therefore, I discuss only the COM add-ins in this book Writing Add-ins for Other... debug, and, if so, which debugger Depending on which version of Visual Studio you have installed, you may be given the choice of several different debuggers You can choose whichever you want and then click Yes (I use the Visual Interdev, which shipped with Visual Studio 6.0, for the sole reason that it loads faster than Visual Studio NET.) An instance of your chosen debugger will then start and you... applicationObject; // CommandBars bars = WordApp.CommandBars; // which is handy because the IDE pops up the // members of WordApp, showing CommandBars as // a member CommandBars bars = (CommandBars)applicationObject GetType().InvokeMember(“CommandBars”, System.Reflection.BindingFlags.GetProperty, null, applicationObject, null); CommandBar bar; CommandBarButton button; bar = bars[“Standard”]; try { // Look... easily create your own scripts and HTML files that work together to create a wizard that maintains the same look and feel as the other wizards In the next chapter, “Writing NET Add-ins for Microsoft Office,” which begins Part III, I show you how you can take the same concepts on writing add-ins and use them to build add-ins for other Microsoft products 281 PA R T Three VS.NET and Other Products AM FL Y... NET Add-ins for Microsoft Office If you’ve been reading this book straight through, by now you’re well aware of how to create add-ins for Visual Studio NET using the IDTExtensibility2 interface This interface was developed by Microsoft before Visual Studio NET came out; it was originally created for the Office 2000 line of software In other words, now that you know how to create add-ins for Visual Studio. .. in both—say, Microsoft Word and the Visual Studio NET Macros IDE—although I’m sure there are examples, such as those dealing with version control and event logging.) After you choose your application hosts, click Next The Name and Description screen comes up next, as shown in Figure 13.3 Here you give a friendly name and a description for your add-in After entering a name and description, click Next... component for the Office product your add-in is supporting (You will be removing this reference shortly.) 2 From the Windows Start Menu, choose Programs➪Microsoft Visual Studio NET➪ Visual Studio NET Tools Visual Studio NET Command Prompt 3 Inside the Command Prompt, “cd” to the output directory for your project (That’s the bin directory, possibly followed by a configuration name such as debug.) In this directory... Visual Studio NET lets you develop add-ins: ■ ■ Word ■ ■ Visio ■ ■ Project ■ ■ PowerPoint ■ ■ Microsoft Outlook ■ ■ FrontPage ■ ■ Excel ■ ■ Access Be careful if you’re developing add-ins for Visio Visio 2000, although part of the Office 2000 product line, does not support add-ins This has been a source of a great deal of confusion among developers: If you start Visio 2000 and choose Tools➪Options and . list of predefined symbols, open the Visual Studio .NET online help. Go to the Contents and drill down to Visual Studio .NET Visual C++➪Creating and Managing Visual C++ Projects➪Designing a Wizard➪Files Created. FilesMicrosoft Visual Studio .NET Vc7VCWizards estwiz1 ■■ C:Program FilesMicrosoft Visual Studio .NET Vc7VCWizards estwiz1html ■■ C:Program FilesMicrosoft Visual Studio .NET Vc7VCWizards estwiz1 html1033 ■■ C:Program. FilesMicrosoft Visual Studio .NET Vc7VCWizards estwiz1 scripts ■■ C:Program FilesMicrosoft Visual Studio .NET Vc7VCWizards estwiz1 scripts1033 ■■ C:Program FilesMicrosoft Visual Studio .NET Vc7VCWizards estwiz1 templates ■■ C:Program