When you start writing a Visual CADD API application, should you create a standalone executable program (an EXE) or a dynamic-link library (a DLL)?
If you are new to programming, this may sound like an imponderable question.
Here
are a few guidelines.
If your application will be executed in Visual CADD, from a script or with a two-letter alias defined in the CMDEXT.DEF file, and will use the Visual CADD user interface,
either a DLL or EXE is OK.
If
your application will have its own user interface and will be started standalone (without Visual CADD running), then you probably need an EXE. The beginning programmer should be warned, however, that creating your own user interface using the Visual CADD API for the first time can
be quite a challenge. Thus, a beginning programmer may want to stick with the Visual CADD user interface, at least until you're comfortable with the basics.
Execution time can be an important consideration.
An EXE file loads from your hard drive into memory the first time you use it, executes, and then is removed from memory. This process repeats each time you call it up.
A DLL also loads from your hard drive into memory the first time you call it. But unlike an EXE, it stays in memory until the program which executed it (in this case Visual CADD) is closed. It's a big time saver.
So, the decision comes down to this - will you execute your application once or just a few times during a Visual CADD session, or will you use
it often? If it will be often, choose a DLL, otherwise an EXE is OK.
A DLL offers one more major advantage. It is always possible to add additional routines to an existing project for a DLL. In contrast, depending upon how the EXE is designed, it may not be practical to add new functionality to an existing project for an EXE. An EXE is usually designed to perform a complete task, whereas a DLL is a collection of routines which perform parts of larger
tasks. The new functionality added to an EXE may not fit well within the existing complete task, thus requiring a new project.
So, unless you have a compelling reason not to, you should choose a DLL.
The particular software you use to write your applications will impact whether you use an EXE or DLL. In Visual Basic version 4, the Standard version does not allow OLE DLL's (described further on), so you MUST create an EXE. If you have the Professional version -which costs several hundred dollars more-OLE DLL's will work.
With Microsoft Visual C++ version 4, either the Standard, Professional or Enterprise versions will allow you to write DLL's.
Should you use the Microsoft Foundation Classes (MFC) in Visual C++ when programming the Visual CADD API? If you are new to Visual C++, just a couple of quick words about the MFC.
The MFC contains basic building blocks for writing powerful Visual C++ programs using object-oriented programming techniques. They can do some of the "drudgery" work for a programmer.
For example, if a dialog box is needed for some user interface which is not already provided by the Visual CADD API, the MFC provides a framework for the dialog. You only need to add the functionality you need (i.e.; code) and attach variables to the dialog for passing the user input.
Many programming tasks require user input in the form of text, numbers, selection of options, etc., and Visual CADD API programming is no exception. The Visual CADD user interface handles much user input, but there may be occasions when you need to create a custom dialog box to get special input. Dialog boxes are only a small part of the MFC, but they would probably be the first thing to cause someone writing a Visual CADD API application to use the MFC. (Dialog boxes can be added to non-MFC projects, but most programmers find the MFC-based dialog boxes much easier, due to the built-in framework for dialog boxes.)
When you create a new project in Visual C++, the AppWizard will help you setup your application. So, you need to decide very early in a project whether you will use MFC or not.
One advantage of choosing to create an MFC application is that you can still use standard non-MFC programming and mix it with MFC programming. So, choosing to go with MFC from the beginning is really quite flexible and will not limit what you do later. If you start with a non-MFC project and later want to add MFC code, you can move your code, but it requires several steps and can be time consuming.
If your Visual CADD API application will exclusively use the Visual CADD user interface, you probably will not need the MFC to create a user interface, dialogs or drawing windows.
If you think you will be creating any of your own dialogs, even if you rely mostly on the existing Visual CADD user interface, you may want to go with the MFC right away. Although it is not possible to say with certainty, if you will do much Visual CADD API programming, you will probably eventually want to use the power of the MFC, whether for dialogs or other uses.
So why wouldn't you want to use the MFC? Some programmers will argue that by allowing MFC to do your "overhead", especially as a beginner, you'll never learn all the fundamentals of C or C++ programming. It is arguably a valid point if you really intend to embrace programming and write other Windows applications. If you plan only to do simple customizing of Visual CADD thru the API, it's probably not a concern.
One disadvantage to using an MFC project when only standard non-MFC programming is being used is that MFC projects will compile and link to larger sized EXE or DLL files. The larger size is due to the basic MFC functionality which is automatically included in MFC executable files. When using only non-MFC programming, this extra size is completely wasted overhead. However, it should be emphasized that the additional size is negligible and should not be a deciding factor in most cases.
So, unless you are very confident you will never need the MFC, a beginner can safely start with an MFC project for Visual CADD API programming in Visual C++.
Can you use Visual Basic OLE DLLs for Visual CADD API applications? Visual Basic can create an EXE or something called an OLE DLL, not an ordinary DLL. The OLE means object linking and embedding and is based on object-oriented programming.
An OLE DLL runs a bit differently than a DLL.
Until recently, Visual CADD was not capable of running an OLE DLL from a script or the CMDEXT.DEF. But, now you can download an OLEVCADD.DLL file from this website which will allow Visual CADD to run OLE DLLs. It is very simple to download, install, and use.
So, there is no real impediment to using Visual Basic to create your Visual CADD API DLLs (actually OLE DLLs).
What are all those Visual CADD API routines with the BP on the end of their names?
When data is passed back and forth between programs, functions, and subroutines, they can be passed either by passing the actual value of the data or by passing the memory address where the data is located (when you need the value, you just get it out of memory).
Passing the value is called just that, 'passing by value.' Passing a memory address is called 'passing by pointer' or 'passing by reference.'
C++, Visual Basic, and Delphi all allow the user to create special kinds of data. These special kinds of data are called structures, user-defined data, and records, respectively, in these three languages. In the Visual CADD API, 2-dimensional points are a kind of user-defined data called Point2D.
Visual Basic and Delphi can only pass user-defined data (such as Point2D) by pointer, not by value. C++ can do either.
Many of the Visual CADD API routines pass Point2D data by value, making it impossible for Visual Basic or Delphi to use them. So, the Visual CADD API provides an equivalent routine, with a BP at the end of the name, for Visual Basic and Delphi to use. The BP at the end means 'by pointer,' which is what these two languages require for passing user-defined data.
Why do some Visual CADD API routines have BP on the end of their names, but do not involve Point2D? The Visual CADD API Help file (up to and including v2.0.4) says that returning double-precision real numbers (called Double in C++, Visual Basic, and Delphi) from functions is a special case not possible in Visual Basic and Delphi, and that these must be handled like user-defined data.
That is to say, the Visual CADD Help file asserts that Double data must be passed by pointer in Visual Basic and Delphi and require the BP-equivalent routines. This is not true, at least in Visual Basic v4.0.
In Visual Basic v4.0, Double data can be passed by value and can be returned from functions. All the BP-equivalent Visual CADD API routines involving Double data are unnecessary in Visual Basic v4.0. To say they are unnecessary does not mean they do not work - they do work. It is just that the ordinary, non-BP functions with Double data will also work.
For example,
Declare Sub VCGetFilletRadBP Lib "VCMAIN32.DLL" (iError As Integer, dRet As Double) Declare Function VCGetFilletRad Lib "VCMAIN32.DLL" (iError As Integer) As Doubleboth work for getting the fillet radius, but only the first declaration is in VCMAIN32.BAS or is documented in the Visual CADD API Help file for Visual Basic. The second declaration is documented for C++ and it is easy to see how the function needs to be declared in Visual Basic. If you wanted, you could add the latter to your VCMAIN32.BAS declaration module and use it.
There are many programming cases where a function is better to use than a subroutine. If you are using any BP-equivalent routine for Double data, you should consider whether the non-BP function is better and add it to your VCMAIN32.BAS declaration module.
Why do some Visual CADD API routines not have BP on the end of their names, but they do involve Point2D? Some of these Visual CADD API routines already pass the Point2D data by pointer and will work in Visual Basic and Delphi. So, they do not require the additional BP-equivalent routines. One example, among very many, is VCAddLeaderEntity.
Others are oversights (or errors) in the Visual CADD API. As of Visual CADD API v2.0.4, the following are known to involve passing Point2D data by value but do not have the necessary BP-equivalent routine.
- VCCreateSymbolFromSelection
- VCDigPoint (this is also undocumented in the Visual CADD API Help file)
- VCGetDatumBasePt
- VCMouseMoveWorldPoint
- VCSetDatumBasePt
- VCSetScaleXY
- VCSetSymScale
This means that you cannot use these Visual CADD API routines in Visual Basic or Delphi, only in C++. One fix is to write C++ DLL routines which accept the Point2D data by pointer and call the corresponding Visual CADD API routines
with the Point2D values. These can then be called by Visual Basic or Delphi.
In the case of VCSetScaleXY, you can also use VCSetScaleX and VCSetScaleY to set the x and y scales separately. And, for VCSetSymScale, you can use VCSetSymScaleX and VCSetSymScaleY to set the x and y symbol scales separately.
Can you use Visual Basic for Applications to program the Visual CADD API? Visual Basic for Applications (VBA), which is part of Microsoft Excel and Access, is capable of creating and running Visual CADD API applications. You cannot create DLLs with VBA and your applications will run like EXE's (but without compiling). If you have VBA, it may not be a bad place to experiment with Visual CADD API programming and it will be effective for certain kinds of applications. If you want to create complex routines that will be used all the time --several times an hour or even a day-- you likely will need the flexibility and speed of execution offered by creating DLLs and/or compiled EXEs, so VBA may not be a long-term solution. But if you have it on your machine already, it's a good way to get your feet wet without spending money on programming software.
Are there ways to setup Visual Basic to efficiently manage Visual CADD API projects? Using the Visual CADD API routines in Visual Basic requires that they first be declared. You can declare each routine as needed or you can use the declaration modules available from this website.
You should download these modules, as they are a big time saver and avoid potential typographic errors when you enter them yourself. The five declaration modules (VCMAIN32.BAS, VCDLG32.BAS, VCTOOL32.BAS, VCTRAN32.BAS, and VCTYPE32.BAS) should be placed in a folder with your Visual Basic projects, so they can be shared among all your projects.
It is also recommended that you create a module, perhaps called VCUTILS.BAS, to hold various Visual CADD API utility functions you may create, so that they may also be shared among all your projects. For example, one useful function is to make a Point2D from x and y coordinates:
' make a Point2D from x, y
'
Public Function MakePoint2D(dX As Double, dY As Double) As Point2D
MakePoint2D.x = dX
MakePoint2D.y = dY
End Function
See the discussion under the C++ Setup section later on for more information on this function. If you're just starting out, you might want to try a tutorial or two before typing this code and creating the .BAS module. At any rate, put VCUTILS.BAS in it's own folder, as shown below.Something like the following folder tree works effectively to organize your projects:
The top level of the tree (suggested here as VBasic4) is arbitrary
and is up to the user. For example, Visual Basic would normally default to C:\Program Files\Microsoft Visual Basic instead of VBasic4. The essential feature of the suggested tree is that the project subdirectories (Project1, Project2, …) are at the same level as the VCDeclares and VCUtils subdirectories.
If you choose for the top level directory to be other than C:\Program Files\Microsoft Visual Basic, then it is very useful to change the "Start in" directory
on the Shortcut
tab of the Visual Basic shortcut Properties
to be the same as the top level directory you have chosen.
This arrangement makes the VCDeclares and VCUtils subdirectories easily accessible from within a project when using the menu command File, Add File to add the shared files to the project.
How should Visual Basic projects be setup to make EXEs for Visual CADD API?
If you have the Standard version of Visual Basic 4, which cannot create OLE DLL's, you have no choice but to use EXEs for your Visual CADD projects. Although much of the information in our tutorials on OLE DLL's can be used with an EXE, there are certain modifications you must make. Follow this link to our Visual Basic EXE page to discover the differences.
How should Visual Basic projects be setup to make OLE DLLs for Visual CADD API? Nothing special is required when starting a new Visual CADD API project from Visual Basic.
However, for OLE DLLs in general, project options need to be set. From the Tool, Options, Project tab, (1) set Startup Form to Sub Main, (2) enter the Project Name (we'll use VBVCADD in our tutorials) which will be the beginning of the fully qualified class name registered by the OLE DLL, (3) check StartMode as OLE Server, and (4) enter a descriptive name or phrase in Application Description. The first tutorial has step by step instructions on creating a project, including these options, so beginners don't need to worry too much about them now.
OLE DLLs require class modules. Each class defined will be registered by Visual Basic in the system registry when you make the OLE DLL file. The fully qualified class name, which gets registered, is the Project Name (mentioned above) followed by the class name, separated by a period. You, or the end-user of the OLE DLL, will need to know this fully qualified name in order to execute the routines you place in the OLE DLL.
The routines you write using the Visual CADD API will be placed in the class modules. These routines are the ones that will ultimately be run from Visual CADD. When creating a class which will be used to hold functions which can be called by other programs, Visual Basic requires that the Instancing property of the class module be set to 2 - Creatable MultiUse and the Public property be set to True. These tell Visual Basic to create the class as needed and to allow other programs to use it.
As mentioned elsewhere, OLE DLLs must be run from Visual CADD with a special DLL named OLEVCADD.DLL. You can download OLEVCADD.DLL here on our website.
Are there ways to setup Visual C++ to efficiently manage Visual CADD API projects? Using the Visual CADD API routines in Visual C++ requires that they first be declared. Declaring routines means that you include code in your program to tell the Visual C++ compiler the kinds of parameters the routines take and the values returned by the routines. In C++, declarations are commonly placed in a separate file called a header file with an extension of .H. You can declare each routine as needed or you can use the declaration headers available for download from this website.
It is recommended that you download the declaration headers, as they are a big time saver and avoid potential typographic errors when you enter them yourself. The five declaration headers (VCMAIN32.H, VCDLG32.H, VCTOOL32.H, VCTRAN32.H, and VCTYPE32.H)
should be placed in a folder with your Visual C++ projects, so they can be shared among all your projects.
When C++ projects are compiled to access the Visual CADD API, the library VCLINK32.LIB and dynamic-link library VCLINK32.DLL are required. These files are also available for download. The VCLINK32.LIB should also be placed in a folder, so it can be shared among all your projects. The VCLINK32.DLL should be placed in the Visual CADD folder, so it is available at execution time (it may already be there, but you should check).
It is also recommended that you create a couple of source files, perhaps called VCUTILS.CPP and VCUTILS.H, to hold various Visual CADD API utility functions you may create, so that they may also be shared among all your projects. For example, one useful function is to make a Point2D from x and y coordinates.
Include in VCUTILS.CPP:
// make Point2D from two doubles
//
Point2D WINAPI MakePoint2D(double d1, double d2)
{
Point2D pt;
pt.x = d1;
pt.y = d2;
return pt;
}
And, include in VCUTILS.H the function declaration:
// make Point2D from two doubles
//
Point2D WINAPI MakePoint2D(double d1, double d2);
This particular function is not used in any of the following tutorials, but is included strictly as a programming tip and for something to put into the VCUTILS.CPP and .H files. If you write many Visual CADD API programs, you will find that you will often need to convert (x,y)-coordinates into a Point2D for use by the API, hence the reason to share it among all your projects.
Of course, the most effective way to share routines is to compile a DLL. But, you may find that you add to your shared routines so frequently as you write the main program code, that it is easier to share source code instead, especially as Visual C++ is smart about not recompiling unchanged code.
If you're just starting out, you may want to go through one or more of the tutorials so that you're familiar with writing code, then come back and add the above example.
Something like the following folder tree works effectively to organize your projects:
The top level of the tree (suggested here as VC++4) is arbitrary and is up to the user. For example, Visual C++ would normally make the top level C:\MSDEV\Projects instead of VC++4. The essential feature of the suggested tree is that the project subdirectories (Project1, Project2, …) are at the same level as the VCInclude, VCLib, and VCUtils subdirectories. This arrangement makes the latter subdirectories easily referenced from within a project by using "..\" for the parent directory. For example, to include a header file in a C++ source file in any project subdirectory, one would use:
#include "..\VCInclude\VCMAIN32.H"and these files will then look for the folder one level up (i.e.; your project folder).
How should Visual C++ projects be setup to make Win32 API (non-MFC) DLLs for Visual CADD API? You can use the Visual C++ New, Project Workspace AppWizard to create a Dynamic-Link Library (DLL) project.
In the Build, Settings, Link tab, you need to add the VCLINK32.LIB to the Object/Libraries Modules under either the General or Input categories (see screenshot below). You need to add your source files (.CPP and .H) to the project, including the necessary Visual CADD API declaration headers, and module-definition file (.DEF). The names of the functions to be exported are included in the EXPORTS section of the module-definition file.
How should Visual C++ projects be setup to make MFC DLLs for Visual CADD API? You can use the Visual C++ New, Project Workspace AppWizard to create an MFC AppWizard (DLL) project. After entering the project name and clicking Create, choose Regular DLL with MFC Statically Linked. (Regular DLL with MFC Dynamically Linked should work, but has occasionally experienced some unresolved problems working with Visual CADD API. MFC Statically Linked has proven to be more reliable.)
Note: If you have the Standard or Learning Editions of Visual C++, you don't have the option of choosing 'Regular DLL with MFC Statically Linked'. A DLL 'dynamically linked to MFC' will work exactly the same, except that the end-user must also have the MFC DLLs on his machine. With 'static link to MFC', the user does not need the MFC DLLs. The moral: if you're planning on distributing your program(s), you should probably invest in the Pro Edition.
In the Build, Settings, Link tab, you need to add the VCLINK32.LIB to the Object/Libraries Modules under either the General or Input categories.
You then need to add your source files (.CPP and .H) to the project, including the necessary Visual CADD API declaration headers, or add code to those created by the AppWizard. The names of the functions to be exported are included in the EXPORTS section of the module-definition file. For the beginner, all of this is explained in step by step detail in the first tutorial, which uses the MFC DLL.
Once you have a DLL or EXE built and ready to go, how do make it work in Visual CADD? Your API applications are typically run either from a script or by adding a custom command to the CMDEXT.DEF file.
To run your applications, you would assign examples like the following to a function key using Assign Script (AS) or add to the CMDEXT.DEF file, illustrated here with example DLL names and function names:
for a DLL function HidePoints in the MFCVCADD.DLL -
DllName;C:\VC++4\MFCVCADD\RELEASE\MFCVCADD.DLL;
DllFunName;HidePoints;DllRun;
for a VB OLE DLL function VBShowLayer in the VbVCadd.General class with a parameter of 1 -
DllName;OLEVCADD.DLL;DllFunName;VBOleDll;
DllCmdLine;VbVCadd.General|VBShowLayer|1;DllRun;
for an EXE named KeyStoke with a parameter equal to DXy -
ExeName;C:\VBASIC4\KEYSTOKE\KEYSTOKE.EXE DXy;Run;
In the first example, the file name following DllName tells the script which DLL contains the function. The name following DllFunName tells the script which function to run. And, DllRun
tells the script to run the specified DLL function.
The second example is similar, except that Visual CADD cannot run VB OLE DLLs directly from a script. Therefore, the OLEVCADD.DLL and its function VBOleDll (discussed in Can you use Visual Basic OLE DLLs for Visual CADD API applications?) must be used to call a VB OLE DLL.
The parameters following DllCmdLine tell the function VBOleDll to run another function from the registered class VbVCadd.General, that the name of the other function to run is VBShowLayer, and that a string parameter of "1" is to be passed to the VB OLE DLL function. The use of OLEVCADD.DLL and VBOleDll is documented in the file available for download by clicking on the link.
In the third example, the file name following ExeName tells the script which EXE to run. A string parameter "DXy", which appears in the command line of the EXE, is to be passed to the EXE. And, ExeRun tells the script to run the specified EXE.
Once added to the CMDEXT.DEF, you can use its native and alias commands from the Visual CADD command-line or add them to the MAINSBAR.CST or TOOLPAL.CST files. If you're not familiar with these topics, there is an article here on the website from a past NUG Nation newsletter that describes how to do each.