VrmlPad add-ins are in-process ActiveX components (DLLs) that you write in C++, Delphi or Visual Basic. With add-ins, you can automate tasks in VrmlPad by adding commands to perform these tasks, by adding toolbar buttons and keyboard shortcuts to carry out these commands.

VrmlPad macros are procedures you write in the Visual Basic Scripting Edition language or the JavaScript (JScript) language. With VBScript and JavaScript macros, you can simplify your work in VrmlPad. For example, in a macro you can combine several commands, speed up routine editing, or automate a complex series of tasks.

VBScript and JavaScript macros differ from VrmlPad add-ins. The primary difference is that macros are procedures written in a scripting language, whereas add-ins are in-process ActiveX components (DLLs) written in C++, Pascal or Visual Basic.

You can create a macro more quickly and easily than you can an add-in. To create a macro, you simply write some code in a text editor, save text to a file and then run the macro. To create an add-in, however, you must write it in a language such as Visual C++, compile it into a DLL, and then run its commands.

VBScript and JavaScript macros are not as versatile as add-ins. In macros, you can only use the scripting language, and you can only access the VrmlPad object model. In add-ins, however, you can use a language of your choice, and you can access not only the object model but the resources of the entire computer system.

The following table summarizes the differences between macros and add-ins.

VBScript and JavaScript macros	VrmlPad add-ins
Are interpreted	Are compiled
Are easy to create	Are more difficult to create
Can only be written in VBScript or JavaScript	Can be written in different languages, such as C++, Pascal and Visual Basic
Can only access the VrmlPad object model	Can access local computer resources as well as the VrmlPad object model
Can only use dialog boxes created by the VBScript InputBox and MsgBox commands	Can use arbitrary modal dialog boxes
Cannot directly read from or write to files on disk	Can directly read from or write to files on disk, using the Win32 API
Cannot access the Win32 API	Can access the Win32 API
Cannot use early binding	Can use early binding for better run-time performance
Cannot control another application	Can control another application

Writing and executing scripts

With VBScript and JavaScript macros you can automate routine VrmlPad tasks. For example, you can check document nodes for an invalid values, add fields with the default values to a current node, insert nodes or prototypes with a predefined structure, and so on.

A macro is a procedure that contains VBScript or JavaScript commands and takes no parameters. A VBScript macro begins with a Sub statement, continues with VBScript commands that represent tasks you want to accomplish, and ends with an End Sub statement. A JavaScript macro begins with a function statement, continues with JavaScript commands, enclosed within a braces.

You create a macro by writing it manually in any text editor. When you complete a macro, store it in a text file known as a macro file. A macro file should be placed in the AddIns subdirectory of the VrmlPad directory and can contain one or more macros. The number of macros is up to you.

The program determines which language engine to use based on the extension of the script file. If the file extension is .bas, .vb or .vbs, then the VBScript engine is used to execute the script. If the file extension is .js, it is assumed that the file contains JavaScript source.

The scripting feature requires Microsoft's ActiveScripting engine v3.1 or later, which is not installed by VrmlPad. If you have Microsoft Internet Explorer 4.0 or later on your system, then you already have the correct ActiveScripting engine installed. Otherwise, you'll need to download it from http://www.microsoft.com/msdownload/scripting.htm.

Assigning macros to menu items, toolbar buttons or key sequences

Assigning macro to a menu item By default, VrmlPad automatically adds menu items to the Tools menu for each VBScript macro with the same name as the macro procedure has. For example, the following VBScript macro adds Count Shapes menu item to the Tools menu. Sub Count_Shapes   MsgBox StdProtos("Shape").Instances.Count End Sub To change the name of the menu item, add a BindCommand statement to the macro file outside a procedures. The syntax for the BindCommand method is: BindCommand ( entryName, [description], [menuitem], [hotkey], [icon] ) The entryName part specifies a name of the macro procedure. The description (optional) part specifies a short description of the command, that is available on the status bar of VrmlPad. The menuitem (optional) part specifies a string for a menu item to be added. If the string contains & (ampersand) character before a letter, this letter will be underscored in the menu item for quick access to the command. A ¦ (broken bar) characters in the string divide hierarchical menu subitems. The following VBScript statement assigns a Count Shapes... menu item to the macro from the previous example. BindCommand "Count_Shapes", "Counts all shape nodes in the scene", "Count S&hapes..." The following example does the same task using JavaScript. BindCommand("Count_Shapes", "Counts all shape nodes in the scene", "Count S&hapes...");

Assigning macro to a key sequence The hotkey (optional) part of the BindCommand method points to a String specifying the keystrokes needed to execute the command. This string has the format Ctrl+Alt+Shift+A, where Ctrl, Alt, and Shift are optional. The following VBScript example assigns a macro to a Ctrl+F12 key sequence. BindCommand "Count_Shapes", , ,"Ctrl+F12" Sub Count_Shapes   MsgBox StdProtos("Shape").Instances.Count End Sub

Assigning macro to a toolbar button The icon (optional) part of the BindCommand method points to a String specifying the name of an icon file (.ICO), executable file (.EXE), DLL, or icon file library (.ICL) and an index of the icon to retrieve. If the string specifies a path but the file does not exist in the specified directory, the function fails. When no path is specified, the method searches for the file in the following sequence: The directory from which VrmlPad loaded. The directory from which the macro loaded. The Windows system directory. The Windows directory. The directories that are listed in the PATH environment variable. To specify the location of an icon in the executable file or library, the string may be ended with #a_nnn, where nnn is a zero-based index of the icon to retrieve. The following VBScript example assigns a macro to a toolbar button with an icon from the system library. BindCommand "Count_Shapes", , , ,"shell32.dll#24" Sub Count_Shapes   MsgBox StdProtos("Shape").Instances.Count End Sub

Assigning macro to a popup menu item To append a macro command to the context-sensitive pull-down menu, available via right-click both in Editor Window and Scene Tree, add a BindPopup statement to the macro file outside a procedures. The syntax for the BindPopup method is: BindPopup ( entryName, [menuitem], [rules] ) The entryName part specifies a name of the macro procedure. The menuitem (optional) part specifies a string for a menu item to be added. If the string contains & (ampersand) character before a letter, this letter will be underscored in the menu item for quick access to the command. The rules (optional) part specifies a set of rules to be applied, separated by commas ( , ). The current node, field or PROTO declaration at the caret position in Editor window or the selected item in Scene Tree pane must meet one of the rules to include the menu item to the pull-down menu. For example, you can specify a rule to insert the menu item only if the pull-down menu is opened under a Shape node. Each rule has one of the following formats: Rule Condition N The current entity must be a node with the N typename, or any node if asterisk ( * ) is specified. N.F The current entity must be a field with the name F of a node with the N typename. N.* The current entity must be a field of a node with the N typename. *.F The current entity must be a field with the name F of any node. *.{T} The current entity must be a field of the type T. #P The current entity must be a prototype declaration with the name P, or any name if asterisk ( * ) is specified. #P.F The current entity must be an interface field with the name F of a prototype declaration with the name P. #P.* The current entity must be an interface field of a prototype declaration with the name P. The following VBScript example assigns a macro to a pull-down menu item, if the menu is opened under appearance field of a Shape node, or Appearance node, or one of the fields of the Appearance node. BindPopup "EditAppearance", "Edit &Appearance...", "Shape.appearance,Appearance,Appearance.*" Sub EditAppearance ... End Sub See also: CurrentEntity property.

Creating add-ins

To create an add-in, you can use Visual C++ or Visual Basic. Before you create an add-in, you should consider the following design issues:

What tasks will the add-in perform?

Could you use a VBScript macro to perform these tasks? You can write a macro more quickly and easily than you can write an add-in. Before you begin, carefully consider the differences between macros and add-ins.

What commands will the add-in use to perform its tasks?

Which VrmlPad objects will you reference in the add-in's commands?

Which VrmlPad methods and properties will you use in the add-in's commands?

How many add-ins will you need? If you need several, you can combine them in the same DLL.

Will the add-in display windows or dialog boxes? An add-in can display modal windows or dialog boxes; however, it cannot display modeless windows or dialog boxes. For details, see the EnableModeless method.

Will the add-in control another application? An add-in can control another executable file (.EXE) by serving as an out-of-process controller for the other application.

Will the add-in have more than one thread? If you create a multithreaded add-in, the results are unpredictable. An add-in can have multiple threads if none of them has a message pump and only one thread accesses the VrmlPad object model.

Will the add-in carry out another add-in's commands?

Will the add-in have a Help file? VrmlPad cannot display a Help file created for an add-in. The add-in must expose a dedicated command to display a Help file.

VrmlPad add-in is an ActiveX in-process server, that implements one or more commands as a public procedures (in Visual Basic) or methods in the default IDispatch-based interface (in C++). Each of this methods specify what the command does and get argument of the type Document to the active document object. You must write the code for the method and use the BindCommand method to carry out the command.

Following is a summary of the process for creating an add-in.

Decide which language to use You can use Visual C++ 5.0 or 6.0, or Visual Basic versions 4.0, 5.0 or later. If you use Visual C++, you should download the Interface Definition Language (IDL) file or the header files to access the VrmlPad object model. If you use Visual Basic, you must use the VrmlPad type library to access the VrmlPad object model. To do this, from the Project menu choose References and select the VrmlPad Application Library checkbox.

Create a project for the add-in The easiest way to create an add-in with Visual C++ or Visual Basic is to start with the sample project provided. The following table includes the sample names. To copy a sample to your computer, click the sample name, save the file to disk, and unzip it to a folder. Name Description VB5AddIn This illustrates an add-in created with Visual Basic version 5.0. VB6AddIn This illustrates an add-in created with Visual Basic version 6.0. VC5AddInATL The sample ATL project for Visual C++ version 5.0. VC5AddInMFC The sample MFC project for Visual C++ version 5.0. If you create a Visual C++ add-in manually, create an ATL COM project or MFC DLL project with support of ActiveX. Add the downloaded IDL file to the project and set custom build command for the file as following: midl /Oicf /h "__vp.h" /iid "__vp_i.c" "VrmlPad.idl" Add the following strings to the Output files box: .\__vp.h .\__vp_i.c Then include __vp.h header file in your StdAfx.h file and __vp_i.c source file in StdAfx.cpp file. If you create a Visual Basic add-in manually, start a new ActiveX DLL project and reference the VrmlPad type library.

Write additional code for the add-in. If you use the Visual Basic or Visual C++ samples, most of the code is already written — including the code that adds a command to VrmlPad. To load an add-in, VrmlPad calls the add-in's OnAddCommands method, that assigns add-in commands to a menu items, toolbar buttons or key sequences. In a Visual Basic add-in you should declare a public procedure with the name OnAddCommands. In a C++ add-in you should include method with the same name to the main IDispatch-based interface. The syntax for the OnAddCommands method is: Public Sub OnAddCommands ( cmds As CmdBinder ) The method provides information about add-in commands by calling the BindCommand method of the cmds object. The syntax for the BindCommand method is: BindCommand ( entryName, [description], [menuitem], [hotkey], [icon] ) The entryName part specifies the name of a Visual Basic procedure or COM method of the main IDispatch-based interface. The description (optional) part specifies a short description of the command, that is available on the status bar of VrmlPad. The menuitem (optional) part specifies a string for a menu item to be added. If the string contains & (ampersand) character before a letter, this letter will be underscored in the menu item for quick access to the command. A ¦ (broken bar) characters in the string divide hierarchical menu subitems. You can also add a menu item to the pull-down menu. The hotkey (optional) part of the BindCommand method points to a String specifying the keystrokes needed to execute the command. This string has the format Ctrl+Alt+Shift+A, where Ctrl, Alt, and Shift are optional. The icon (optional) part of the BindCommand method points to a Long that is a resource ID for the small (16x16) command bar icon.   To create an image for a toolbar button in Visual C++ In ResourceView, expand the project's resources, and then expand Icon. Insert a new icon, open it, and from the Image menu choose New Device Image to add a new small (16x16) device image. Use the Image editor to draw the icon. Specify a resource ID number of the newly created icon in the BindCommand method. Also, the icon part of the method can be a String specifying the name of an icon file (.ICO), executable file (.EXE), DLL, or icon file library (.ICL). To specify the location of an icon in the executable file or library, the string may be ended with #nnn, where nnn is a zero-based index of the icon to retrieve. The following Visual Basic example assigns a command to a menu item, keyboard shortcut and toolbar button. Public Sub OnAddCommands(cmd As CmdBinder)   cmd.BindCommand "Count_Shapes", "Counts all shape nodes in the scene", "Count S&hapes...", "Ctrl+F12", 1 End Sub Sub Count_Shapes(doc As Document)   MsgBox doc.StdProtos("Shape").Instances.Count End Sub The following example is a C++ code snippet you can insert into an add-in. *.idl [   odl,   uuid(...),   dual,   nonextensible,   oleautomation ] interface IMyAddin : IDispatch {   [id(1)]   HRESULT OnAddCommands([in] IDispatch *cmds);   [id(2)]   HRESULT MyCommand([in] IDispatch *doc); ... *.h public:   // IMyAddin   STDMETHOD(OnAddCommands)(/*[in]*/ IDispatch *cmds);   STDMETHOD(MyCommand)(/*[in]*/ IDispatch *doc); ... *.cpp STDMETHODIMP CHandler::OnAddCommands (IDispatch *cmds) {   return static_cast<CmdBinder*>(cmds)->BindCommand(     CComBSTR(L"MyCommand"),            // name of the method to bind     &CComVariant(L"Does nothing yet."),// short description     &CComVariant(L"Sample Add-in"),    // menu string     &CComVariant(L"Ctrl+F12"),         // keyboard shortcut     &CComVariant(IDI_ICON1)            // resource icon ID   ); } STDMETHODIMP CHandler::MyCommand (IDispatch *doc) {   CComPtr<Window> wnd;   if (SUCCEEDED(static_cast<_Document*>(doc)->get_Window(&wnd))) {     HWND hWnd = NULL;     if (SUCCEEDED(wnd->get_hWnd(reinterpret_cast<long*>(&hWnd))))       MessageBox(hWnd, "Hello world !", "My Sample Addin", MB_OK);   }   return S_OK; }

Build the DLL from the source files. To build the DLL from Visual Basic, on the File menu, click Make ...dll. To connect an add-in to VrmlPad, put the DLL in the AddIns subdirectory of the VrmlPad directory. If necessary, VrmlPad registers it for you. Remember that you can combine several add-ins into one DLL. Tip  Always unregister an add-in before changing it. For example, if you want to move an add-in to a new directory on your computer, or if you want to change its programmatic identifier (progID), unregister it beforehand. To unregister an add-in, go to the command line, go to the directory containing the add-in, and then type the command regsvr32 /u myAddIn.dll, where myAddIn is the name of the add-in.