VISUAL BASIC OLE DLL to Show, Hide, or Toggle Point Display


This example will help you create a Visual Basic project to make an OLE DLL which can be called by Visual CADD. Once this project is finished, you can use it to develop more of your own Visual CADD tools. There is no need to create a new project the next time -- new functions can be added to the DLL. With that in mind, we will use this same project for all of the tutorials.

The following steps will create the Visual Basic project for an OLE DLL:

Whenever you first open Visual Basic, it creates a default project with one blank form module. This first tutorial will not need a form module (usually just called a form), but it will need a standard module (usually just called a module) and a class module.

Forms are exactly what they sound like - a form or window which can be displayed on the user's screen. Forms are typically used when you need a user interface, either to get user input or to display output. This first example of the Visual CADD API will simply toggle the display of points on and off in Visual CADD, so there is no need to use a form.

Standard modules are used to hold executable code, such as functions and subroutines, which can be shared with other modules in the project. When building an OLE DLL, the Visual Basic project must have either a form or a standard module when it starts up. Because we will not use the form module, we must insert a standard module.

Class modules are used to create object classes and are used to hold the functions of an OLE DLL (among other uses). The class module will hold the functions which will be called by Visual CADD.

After creating the default new project, the next several steps remove the unneeded form and insert the standard and class modules.

The default form module is named Form1, and is removed first.

After inserting the standard module, it will have a default name of Module1. We will rename this module modVbVCadd, to indicate module for Visual Basic - Visual CADD (it is important to note that the name of a module -or any form-- can be different than the filename -it will become clear once you have worked with Visual Basic for a while).

After inserting the class module, it will have a default name of Class1. We will rename this class module General, to indicate that it will hold general purpose functions for Visual CADD. The class is made public, so that it will be available to programs outside the project, i.e., to Visual CADD. Lastly, the class must allow other applications to create objects from the class in order to call the class' functions (called methods in OLE parlance), so we set the instancing to 'creatable multiuse'. The reader should refer to their Visual Basic documentation for further information on these topics.

An OLE DLL is started by another application rather than starting itself as an EXE does. Certain project options must be set to facilitate this kind of behavior. In the project options, we need to specify the startup form as Sub Main, which is a subroutine we will later add to the standard module (the modVbVCadd module). When an OLE DLL is created by Visual Basic, its classes are automatically registered in the system registry so other programs can call the OLE DLL. The Project Name and Application Description are two of the things which are used to register the OLE classes. The name for our project is VbVCadd, for Visual Basic - Visual CADD, and the description is VBasic-VCADD OLE Server. Lastly, we must set the project option to tell Visual Basic that this project will start as an OLE Server. Again, the reader should refer to their Visual Basic documentation for further information on these topics.

Once created, the project must be saved. Following the recommendation in Are there ways to setup Visual Basic to efficiently manage Visual CADD API projects?, this example project will use the directory tree described there. The saved files should be saved into a folder named VBVCADD under the top level of your Visual Basic directory tree.

With the initial project setup complete, we are now ready to begin writing the code.

All Visual CADD API functions must be declared in Visual Basic before they can be used. The declaration tells Visual Basic about the parameters required by the routines and which DLL contains them. The declarations can be added to your project by adding the VCMAIN32.BAS file to the project (which is recommended) or by typing the declarations into your module's declaration section. The VCMAIN32.BAS file can be added to your project by selecting File, Add File from the Visual Basic menu, selecting the folder which contains VCMAIN32.BAS, then selecting the file itself.

The declarations in VCMAIN32.BAS include some Visual CADD API routines which use some user-defined data types which are declared in VCTYPE32.BAS. Even though these routines will not be needed in this example, if you add the VCMAIN32.BAS to your project, you must also add the VCTYPE32.BAS file to avoid errors. The VCTYPE32.BAS file can be added to your project in the same way as VCMAIN32.BAS.

For this first example, the declarations of the necessary Visual CADD API routines (which are already in VCMAIN32.BAS) are:
 

        Declare Function VCGetPointDisplay Lib "VCMAIN32.DLL" (iError As Integer) _
                As Integer
        Declare Sub VCSetPointDisplay Lib "VCMAIN32.DLL" (iError As Integer, _
                ByVal tf As Integer)
In Visual Basic, the underline ("_") at the end of a line of code signifies that the code continues to the next line in your text editor. It's good practice to type code all on one line, but if you need to break --to keep a particularly long code line all on your screen, for instance-- don't forget the underline!

These two Visual CADD API routines (in fact, almost all Visual CADD API routines) have a parameter called iError. This is an integer value which is returned from the routine to tell your application the success or failure of the routine when it is done. The value of iError will be 0 (zero) on success and 1 (one) on failure. Depending upon what task your application is performing, it may be very important to check iError to verify successful completion of the routine. Any errors should be handled by your application, as appropriate.

For setting the display of points, any errors are unlikely to be critical, so this example will choose to ignore iError.

However, because iError will be used by almost all of the Visual CADD API routines, it should be declared in the declarations section of the class module which will contain your functions, the GENERAL.CLS module, by adding:
 

    	Dim iError as Integer

OLE DLLs require a subroutine called Main when no form will be displayed by the OLE DLL. The purpose of the Main subroutine is to perform any initialization which may be required by the OLE DLL. This simple example requires no code to perform any initialization, but the Main subroutine is still required. So, we can simply add a Main subroutine with no additional code to the standard module, VBVCADD.BAS (the module named modVbVCadd).
 

        Sub Main()
        End Sub

Now, we can add the functions to control the display of points. In the class module, GENERAL.CLS, add the following: 

        Public Function VBHidePoints(dummy As String)
                Call VCSetPointDisplay(iError, 0)
        End Function

        Public Function VBShowPoints(dummy As String)
                Call VCSetPointDisplay(iError, 1)
        End Function

        Public Function VBTogglePoints(dummy As String)
                Call VCSetPointDisplay(iError, 1 - VCGetPointDisplay(iError))
        End Function

The Public declaration tells Visual Basic that these functions can be called from other programs, such as Visual CADD.

You will note that each of these functions takes a string parameter called dummy, but that the parameter is not used. A little background is required to explain that.

Visual CADD cannot directly run OLE DLLs from a script or the CMDEXT.DEF file. To run OLE DLLs, you must use the C++ DLL called OLEVCADD.DLL link instead. (See below for more details on how OLEVCADD.DLL is used to run your OLE DLL.) OLEVCADD.DLL will run only OLE DLLs which accept one string parameter, in order to be consistent with Visual CADD's designs for implementing OLE DLLs (refer to Visual CADD API Help file under VCGetOleDllFunctionCmdLine for more information).

Therefore, the functions in your OLE DLL must accept one string parameter, even if that parameter is not used. This example does this by including a string parameter named dummy.

You will also note these three function names all start with VB, for Visual Basic. This is done to distinguish them from the C++ tutorial using the same functions.

The Visual CADD API routine VCSetPointDisplay does nothing more than turn the display of points on and off. When passed a 0 (zero), it turns the display off. When passed a 1 (one), it turns the display on.

The Visual CADD API routine VCGetPointDisplay tells you whether the display of points is on or off. If it returns 0 (zero), it is off. If it returns 1 (one), it is on. If you subtract this value from 1 (one), you can toggle between 0 and 1. If it was 0 ,you get 1, and if it was 1, you get 0. The subtraction from 1 is a standard trick for toggling 0 and 1 and is what VBTogglePoint uses as a parameter in VCSetPointDisplay to turn on-to-off and off-to-on.

The final step is to create the OLE DLL using the File, Make OLE DLL File command in Visual Basic. Name your DLL VBVCADD.DLL, for Visual Basic - Visual CADD, and save it in your VBVCADD project folder. When the compile is completed successfully, your OLE class will be registered by Visual Basic in the system registry. The registered class name will consist of the project name followed by a period and the class name. In our example, the OLE class will be registered as VbVCadd.General. Calling your functions from Visual CADD using the OLEVCADD.DLL requires this class name in order to locate your OLE DLL and to run its functions, as illustrated below.

To run your OLE DLL, include the following in your CMDEXT.DEF (recommended) or Assign Script (AS), where the first line of each is omitted for scripts. As mentioned above, the OLEVCADD.DLL should be downloaded.
 

        HidePoints,HP, ,Hide Points,Hide Points,
                DllName;OLEVCADD.DLL;DllFunName;VBOleDll;
                DllCmdLine;VbVCadd.General|VBHidePoints|;DllRun;Regen;

        ShowPoints,OP, ,Show Points,Show Points,
                DllName;OLEVCADD.DLL;DllFunName;VBOleDll;
                DllCmdLine;VbVCadd.General|VBShowPoints|;DllRun;Regen;

        TogglePoints,GP, ,Toggle Points,Toggle Points,
                DllName;OLEVCADD.DLL;DllFunName;VBOleDll;
                DllCmdLine;VbVCadd.General|VBTogglePoints|;DllRun;Regen;

Now, from Visual CADD, HP will hide points, OP will show points, and GP will toggle points.

Suggested Additions to the Example DLLs The display of points is only one of several properties which cannot be controlled through scripts or two-letter alias commands defined in the CMDEXT.DEF. Others which may be included in a your OLE DLL are:


Programming Index | VB and VC++ Setup | Example 1 Overview | Next Tutorial