Tools for WriteLog contest module development
C++ C JavaScript CSS HTML
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.

README.md

WriteLogWizards

Tools for WriteLog contest module development This repo contains:

  1. Source code for Visual Studio 2008 wizards that create WriteLog contest module implementations.
  2. The same for Visual Studio 2013
  3. The necessary header files and import libraries to build WriteLog contest modules.

Developing in VS 2008 can target both WriteLog versions 11 and 12. Developing in VS 2013 targets only WriteLog version 12. (The VS2013 C++ runtime is not installed by the WL11 installer. Modules developed with VS 2013 happen to work on WL11 if that runtime happens to be already installed.)

The Directory Structure

The wizards generate code that assumes the relative file paths set up in this repo:

Projects/
Is not part of this repo, but is in .gitignore. It is where you should have the VS File/New-project wizard place any newly created WL module development projects.

WL11ModuleWizard/
contains the source of the VS2008 module create wizard. Do not open any vcproj/sln/vcxproj here or in any of the next three Wizard source code folders with Visual Studio unless your intent is to upgrade the wizard itself (as opposed to develop a WriteLog contest module.) The source in this repo is sufficient to use the wizards as-is.

WL11ProjectWizard/
contains the source of the VS2008 project create wizard.

WL12ModuleWizard/
contains the source of the VS2013 module create wizard.

WL12ProjectWizard/
contains the source of the VS2013 project create wizard.

WriteLog/
contains the source of the various headers and import libraries required by the generated project. These headers and libraries suffice for both WL11 and WL12 (and VS2008 and VS2013). You do not edit anything here, with one exception:

WriteLog/include/
is where it is suggested you put your own common headers you want available across multiple modules. The wizards arrange for this directory to be in the include path for both C++ and .rc compiles, so this is a good place to put, for example, source code for any copyright or version information you want in common across your modules.

WriteLog/generated/
WriteLog/MmdCom/
WriteLog/wlogtools/

Don't touch these. It is also recommended that you not use any headers you find in there for your development because much of it is archaic. The reason the archaic stuff remains is to enable source-code compatible development of module developed using the old Visual Studio 6 wizard last updated in 2008 (and most of which dates from 2000--or earlier.)

The wizards

You must already have VS 2008 and/or VS 2013 installed. The Express versions are not supported for WriteLog module development. It takes two wizard operations to create a WriteLog contest module:
  1. The WL11ProjectWizard (or WL12ProjectWizard) creates a skeleton project from the VS File/New-Project menu.
  2. The WL11ModuleWizard (or WL12ModuleWizard) adds skeleton header/cpp/wxs files to such a project for a contest.

Deploying the wizards

There are a total of four wizards: two each for VS 2008 and VS 2013. The instructions for deployment are almost identical for the two versions. There is more than one way to accomplish deployment, but here is one that works and is minimally intrusive on your system.

For all four wizards is is not necessary to use Visual Studio to File/Open-Project of any of the .sln/.vcproj/.vcxproj files in the repo Wizard/ folders. Doing so MIGHT cause VS to auto-magically deploy the wizard in your <MyDocuments> folder, which might or might not conflict with the instructions below. Of course, if you don't like the way the wizards work, you are welcome to change them to suit yourself.

Deploy the Project Wizard

Visual Studio should have already created the directory <MyDocuments>\Visual Studio 2008\. Create a subfolder named Wizards and copy these 3 files from the WL11ProjectWizard repo folder into <MyDocuments>\Visual Studio 2008\Wizards:
  • WL11ProjectWizard.ico
  • WL11ProjectWizard.vsdir
  • WL11ProjectWizard.vsz
Edit that last file, the .vsz file, to correct the absolute path. Make it point to the corresponding directory in your fetched version of this git repo:
Param="ABSOLUTE_PATH = c:\wherever\WriteLogWizards\WL11ProjectWizard"
There is no need to copy the files out of your git work area.

Now File/New Project in Visual Studio 2008 should show this entry that wasn't there before:

ProjectNew2008.png

In order for the directory structure to match that assumed by the module wizard, when creating a new project, browse to the Projects directory in this repo (create it, if necessary), and turn off that Create Directory for solution check box.

The deployment of the WL12 wizard is the same, except substitute to WL12 for WL11, and substitute 2013 for 2008.

Techinical note: Using the WLnnProjectWizard is not strictly necessary because the next wizard, the WLnnModuleWizard can successfully add a contest implementation to a correctly-configured ATL DLL constructed using Visual Studio's built-in ATL wizards. The built-in wizard adds a lot of stuff that WriteLog doesn't need or use, which can be confusing if you're not already an expert in ATL development.

Deploy the ModuleWizard

Getting a new item into the Visual Studio Add/New-Item menu apparently cannot be done in My Documents like a project wizard. Its deployment requires administrator privilege. You must create files in the Visual Studio installation directory. The directory to find is:
C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\vcprojectitems
In that vcprojectitems directory, you need two things:
  • Create a folder named LocalItems.
  • Into that same vcprojectitems folder, copy the file (unchanged) from this repo: WL11ModuleWizard/Deploy/LocalItems/LocalItems.vsdir.
And then into that newly created LocalItems folder, copy these three files:
  1. WL11ModuleWizard.ico
  2. WL11ModuleWizard.vsdir
  3. WL11ModuleWizard.vsz
That .vsz file must be edited to correct the ABSOLUTE_PATH. Again, there is no need to copy files out of the git work area: just point that vsz file to the appropriate subdirectory in your fetched copy of this git repo. Once installed, and in Visual Studio with a WL project open, a right mouse click on the project looks like this:

AddNewItem.png

AddContest.png

The Add New Item may be repeated in order to support more than one contest from a single .DLL. For the WL12 wizard, use the files in WL12ModuleWizard and use the Visual Studio 2013 installation directory, but otherwise all is the same. The module wizard presents these options.

WLModuleWizard.png

  • Rtty Support adds the interfaces that the RttyRite window needs to fully support highlighting and clicking into WriteLog's Entry Window.
  • Cabrillo Support adds enough cabrillo support for basic export.
  • NR in exchange instructs the wizard to add an NR column to the log.
  • Pts Column adds a column to the log to display the points claimed for each QSO.
  • RST in exchange adds sent/received RST columns to the log.
  • Mode support selects among 3 choices.
    1. compiled-in The modes (CW/SSB/RTTY) are decided at compile time. Many RTTY contests are examples.
    2. ask at startup For a given weekend, only one mode (or set of modes) is allowed, but you need to ask the user which. Think ARRL SS CW versus SSB.
    3. multi-mode means that the contest rules are that on a given frequency band, contestants can make separate QSOs for credit on multiple modes. Think IARU HF.
  • DXCC means the contest counts DXCC countries as multipliers, and the wizard generates code for the case of countries as mults once per contest, or once per band.
  • Zones means the contest counts zones as multipliers. The wizard generates support for zones 1 - 40 (per CQ zones) but you can change this to use ITU zones instead.
  • Mults as you go means that every unique string logged for a field is a separate multiplier, but you don't know when the contest starts what they're going to be. This can be used for logging those contests where the "headquarters stations" are their own multipliers. WPX also works this way.
  • Named Mults means there is a list of strings (like state names, or whatever) that are the multipliers for the contest. You will need to create (and distribute) an INI file that has the multipliers in it along with any ALIAS names you want to all refer to the same multiplier
  • Contest Display Name is what the user will see in the WriteLog Select Contest list.
  • Class Name is the name of the C++ class to be generated. The wizard has to generate a name for the corresponding COM coclass which it does this way: if you start the name of the class with a "C" (capital C) then the coclass is the name of the C++ class with no leading C. Otherwise, the name of the coclass is the name of the C++ class with CoClass appended

Installer support

The wizards described above generate code for a WIX installation using the kits available at http://wixtoolset.org/. Installing the WIX tool set after Visual Studio will result in Visual Studio support for WIX installer projects. While the dll's created by the wizard support self-registration, that is not a recommended means for registration when deployed on customer machines (but its fine for use in development.) For customer depoloyment, use the .wxs files generated by the WriteLog wizards to create an msi installer for your module.

Generating the installer is not fully automated by these wizards. The Project wizard generates a product.wxs suitable to be added to a "Windows Installer XML" Setup project. And the Module wizard generates a .wxs suitable to be added to that same Windows Installer project. But these .wxs files are just "loose" in the dll's project--they are not referenced by or needed by the dll project. This readme does not attempt to document how to use the Visual Studio support for the Wix installer. This is just enough information to get you started.

Create the installer project after you have done a successfull Release build of with all the contest modules you want in your project dll. The relative include paths in the generated .wxs files assume this new installer project is placed in the same Projects/ folder as the module projects. Use Visual Studio File/New-Project and choose "Windows Installer XML" and "Setup Project".

The Visual Studio wizard generated a file named product.wxs that you discard. Replace it with the product.wxs moved from where WriteLog Product wizard generated it. At the same time, move the .wxs files that the WriteLog Module wizard generated.

With the installer project open in Visual Studio, do a right mouse click on the install project and Add/Existing-item and add the .wxs file. The project also needs a Reference to WixUIExtension that comes with WIX.

Edit the various TODO's in the two wxs files. (Or more wxs files if you put support more than one contest in your project).

Source code changes required for older modules

There are a handful of bugs in the header files generated using the old Visual Studio 6 WriteLog contest wizard. It is recommended that any new work on those old modules be done using the software development environment published here, and with Visual Studio 2008 (or VS 2013 if WL12 and later support is all that is desired.) Start by placing the old module's source code in its own new folder under Projects in the directory tree created by this repo. You do not run any of the wizards in order to rebuild an old project. This exercise is just to use the latest versions of the header files, which have some templates and preprocessor directives that have been improved since the VS 6 wizard was deployed.

There are a couple of source code changes required in old modules to make them compile in this updated environment:

  1. Place the old source code directory in the new Projects folder here.
  2. The include path structure has changed. The easiest way to deal with this is to edit only the .vcproj as text.
    • Replace this: ..\..\Wlogtool with ..\..\WriteLog\Wlogtool.
    • Similarly, replace ..\..\include with ..\..\WriteLog\include.
    • This one is slightly different: ..\mmdcom becomes ..\..\WriteLog\mmdcom.
    • Finally, to the include file paths, add this directory which did not appear in the old wizard: ..\..\WriteLog\generated
  3. The clsid.c file won't compile anymore. Because it references headers that now only work in C++. Using the VS Solution explorer, rename it to clsid.cpp.
  4. clsid.cpp still might not compile if the <projectname>mm.h file won't compile stand-alone. One simple way to fix this is to split out from <projectname>mm.h the bit that clsid.cpp needs into a separate file.
    • Create a new header file named, say, <projectname>guid.h.
    • Cut from <projectname>mm.h all the lines that look like this:
      DEFINE_GUID(CLSID_EuRttyMmd, 0xC7212160, 0x7716, 0x101A, 0xAA, 0x54, 0x00, 0x60, 0x8C, 0x61, 0xD0, 0xB1); /* C7212160-7716-101A-AA54-00608C61D0B1 */
    • and paste those lines into <projectname>guid.h
    • Update <projectname>mm.h to #include the new guid.h
    • Change clsid.cpp to #include the new guid.h instead of mm.h.