This article contains an overview of building a DWinLib program either using libraries or not using libraries. It may be helpful for beginner programmers who would like a better understanding of building programs in Visual Studio, even if you are not in interested in DWinLib.
Introduction
This article outlines the steps needed to start building a DWinLib program. If you haven't messed around with creating projects and solutions in Visual Studio, you might find some useful information in here.
To begin, extract the following DWinLib and examples zip file to a convenient location on a hard drive. I would make a "D:\Programs" directory and place them there. My reasons for that location are outlined in my DWinLib 6: Pretty WinAPI Incorporation article.
There are two ways to make a DWinLib program. You may pull all of the files into a project from scratch, or you may use DWinLib libraries. Both methods will be outlined here.
Building a DWinLib Program from Scratch
Of the two methods, building a DWinLib program from scratch is the easiest. To start, you need to know what type of project you want to create, and where you want to create it at.
These examples assume the zip file is extracted to "D:\Programs". For this case, I will not-so-randomly chose to recreate the MdiDwlDockWork example. The new project will be located in "D:\Programs\MyProgs\AwesomeProg," so create that directory and copy all of the files from "D:\Programs\MyProgs\DWinLibExamples\MdiDwlDockWork" (WITHOUT THE "VS_FILES" SUBDIRECTORY) to the new "AwesomeProg" directory.
Open Visual Studio and create a new completely empty C++ project. Place it at "D:\Programs\MyProgs\AwesomeProg", and give it the name "AwesomeProg". Check the box to place the solution and project in the same directory, and make sure the dropdown item of "Create new solution" is selected. Press the 'Create' button.
After some processing, Visual Studio will display a blank screen and, if it is displayed by default, the Solution Explorer. If it isn't, display it via the 'View' menu, or "Ctrl + Alt + L".
You can organize the files into the Solution Explorer's filters however you wish, but for this example, I will delete the "Header Files" filter, rename the "Resource Files" filter to "DWinLib", and leave the "Source Files" filter as-is.
Then, in Windows Explorer, drag all of the files (and NONE of the subdirectories) from "D:\Programs\MyProgs\AwesomeProg" onto the "Source Files" filter. Then, in Windows Explorer, navigate to "D:\Programs\LibsAndUtils\DWinLib" and drag all of the files (and again, not the directory in it) onto the "DWinLib" filter.
We now have all of the files into Visual Studio, but we have some more work to do. If you press the "Local Windows Debugger" button and then press "Ctrl + Break" after errors begin appearing in the output, you will see that Visual Studio is complaining about:
"Cannot open include file: 'PrecompiledHeaders.h': No such file or directory"
To fix that, right-click on the "AwesomeProg" project in the Solution Explorer, select "Properties" from the bottom of the menu, and then navigate to Configuration Properties -> C/C++ -> Precompiled Headers and change the "Precompiled Header" line to "Use (/Yu)", and change the file name from "stdafx.h" to "PrecompiledHeaders.h" on the "Precompiled Header File" line. Make certain "All Configurations" is selected in the upper-left Configuration dropdown and press "OK".
Afterwards, right-click on the "PrecompiledHeaders.cpp" file in the Solution Explorer and select "Create (/Yc)" on the "Precompiled Header" line.
Try building the program again, and you will get:
- ...Cannot open include file: 'DwlTypedefs.h'...
This is because even though Visual Studio knows where the files we added to it are placed, it needs us to explicity specify those locations for its compilation and linking steps. So right-click on the "AwesomeProg" project in the Solution Explorer, select "Properties" at the bottom, and maneuver to the Configuration Properties -> C/C++ -> General location. Make certain "All Configurations" is selected in the top left dropdown, and then add the DWinLib directory and the program directory to the "Additional Include Directories" line. Assuming your setup is the same as mine, they are:
- D:\Programs\LibsAndUtils\DWinLib
- D:\Programs\MyProgs\AwesomeProg
Doing so, the "Additional Include Directories" line will become "D:\Programs\MyProgs\AwesomeProg;D:\Programs\LibsAndUtils\DWinLib;%(AdditionalIncludeDirectories)", which you can paste into it instead of going through the dropdown addition.
Press "OK", and then try re-running the program again. You will get a bunch of errors. After compilation is finished (if you wait that long), the top 'Red X' in the error list will be "Error C2440 'initializing': cannot convert from 'const wchar_t [17]' to 'TCHAR *'".
When DWinLib was initially created, it used Windows 'TCHAR' macro to allow easy use of UNICODE or Multi-Byte Character Sets. That, combined with stricter default Visual Studio settings, results in this error which isn't really an error. To get around it, go back to Configuration Properties -> C/C++ -> Language and change "Conformance mode" to "No."
Rebuild, and Visual Studio will spit out an error "'clientWindowC': undeclared identifier". For this error, we simply need to tell DWinLib that we are building an MDI application. To do so, go to Configuration Properties -> C/C++ -> Preprocessor and add "DWL_MDI_APP" to the "Preprocessor Definitions".
When the solution is rebuilt again, you will receive a new error: "LNK2019 unresolved external symbol _main..." When we created the Visual Studio project as a blank C++ project, it defaulted to a console application. To change this, the fix is in Configuration Properties -> C/C++ -> Linker, where the SubSystem needs to be changed to Windows. With that in place, the program will finally appear when the Local Windows Debug button is pressed.
Congratulations! You can begin adding the added functionality you want! Here is a working zip file of the project if you need something to compare your work to. It is set up to use the "D:\..." subdirectories outlined in this article, so it isn't friendly for simultaneously comparing two projects against each other. (To do so, you will need to create a version in a subdirectory other than "D:\Programs\MyProgs\AwesomeProg".)
Building a DWinLib Program Using DWinLib's Library
The second way to build a DWinLib program is to use DWinLib as a library. To use a library, you must tell Visual Studio about it like we told Visual Studio about all of the files and settings to use up above.
To begin, let us recreate the MdiDwlPwcStudio project. So make a directory at "D:\Programs\MyProgs\DwlPwcStudio". Copy the files from "D:\Programs\MyProgs\DWinLibExamples\MdiDwlPwcStudio" into it, excluding the subdirectory it contains. Then create a new blank C++ project in Visual Studio at "D:\Programs\MyProgs\DwlPwcStudio", with the name "DwlPwcStudio", and drag the files from the new DwlPwcStudio folder into the Solution Explorer "Source Files" filter. (You can delete the other filters if you want.)
This time, we don't have to drag the DWinLib files into the project. Instead, we must go to Configuration Properties -> Linker -> General and add the library location. We will use the MDI library, and two versions of it exist: one for debug and one for release. These libraries are not 'built' in the zip files, so you must open up the .sln in Visual Studio and create both if you haven't done so. (Some of the example projects have the library as a project in the solution, and will build them automatically during compilation.)
Once they are built, come back to this project. We are in the Configuration Properties -> Linker -> General page, and in the upper-left corner change the dropdown to 'Debug'. Add "D:\Programs\LibsAndUtils\DWinLibLibrary\MDI_Unicode\Debug" to the "Additional Library Directories". Press 'Apply,' then change to 'Release' and add "D:\Programs\LibsAndUtils\DWinLibLibrary\MDI_Unicode\Release" to it. Press "Apply" again, and switch back to "All Configurations" in the Configuration dropdown.
You must also add the name of the library to the Configuration Properties -> Linker -> Input -> Additional Dependencies line. That library is "DWL_MDI_Unicode.lib". Release and Debug versions have the same name, so you don't have to mess with independent settings.
At this point, you can do like before and try to execute the program, and fix each error as it comes up. Or you can just go through the previous writing and make the same changes. They are:
Congratulations! The program will execute at this point, but there is one problem. If you compare the output to the example program, there aren't any dockers visible in it! There is just a weird screen artifact.
The reason for this is DWinLib uses a macro definition for docker addition compilation. So add "DWL_USE_DOCKERS" to the Configuration Properties -> C/C++ -> Preprocessor -> Preprocessor Definitions for All Configurations. Recompile and everything works correctly!
I hope this overview helps newcomers grasp the basics to using projects and solutions in Visual Studio. I also hope that it is useful for anyone who plays with DWinLib.
As before, here is a zip of the completed project that cannot directly be compared to the above because it is made in the same subdirectory:
Happy coding!
- 16th January, 2021 - Rewrote article for
DWinLib 6.04 and deleted all prior history because it was worthless in this context. And notice there is no future history, either! Just more pro-activism on my part!
