Sourcefiles for DL4YHF's Pic Programmer for Windows
------------------------------------------------------

   Last updated: 2005-12-09 (ISO-format,YYYY-MM-DD)

   Authors: 
     - WinPic by Wolfgang Buescher (DL4YHF), Spenge, Germany .
     - PIC18F support by Martin van der Werff .
     - A part of the 16C84-programming algorithm was 'inspired' 
       by David Tait's PIC programmer for DOS .

   This software is provided 'as-is', without any express or implied
   warranty.  In no event will the authors be held liable for any damages
   arising from the use of this software.
   IN OTHER WORDS, THE ENTIRE RISK FOR ITS USE IS WITH YOU.
    
   Permission to use, copy, modify, and distribute this software and its 
   documentation for any purpose and without fee is hereby granted, 
   so long as it is not sold or exploited for profit, and provided 
   that the above copyright notice and disclaimer appear in all
   copies and supporting documentation.

  NOTE THAT THIS PROGRAMMER DOES NOT MEET MICROCHIP'S REQUIREMENTS FOR
       A "PRODUCTION GRADE" PROGRAMMER BECAUSE IT CANNOT VERIFY THE PIC
       AT DIFFERENT SUPPLY VOLTAGES.



Module overview
----------------------------------------------------
 
 The original location of the WinPic sources was
   C:\CBproj\WinPicPr , but usually the Borland IDE
   has no problem to compile the project in a 
   different directory. 
 The 'external' modules (listed in the next chapter)
  may also be copied into this directory, but I 
  prefer to have them in different folders.
 To compile the project, make sure the DIRECTORY
 STRUCTURE which you find in the zip file remains
 unchanged ! Borland C++ Builder should find all
 C and C++ modules and all include files without
 changing anything. 

 Project directory :
 \CBproj\WinPicPr\...
   WinPic.bpr, .cpp
      The project file for Borland C++ Builder V4.0 .
      I compiled it with BCB V6.0 ONCE also, but 
      there are some nasty bugs in BCB 6 (OnHelp etc),
      so I stick to BCB V4.0 !

   AboutU.cpp, .h, .dfm
      The inevitable "about"-screen for the program.
      The *.dfm is Borland's 'form' file, it contains
      all visible windows controls.
     
   Appl.h
      Some "C" prototypes for routines in the application.
      Included by some modules which do *NOT* use 
      Borland's VCL stuff. 
      Implementation somewhere in the main program.

   Config.cpp, .h
      Small wrapper which deals with ancient INI files.
      Saves some parameters in between WinPic sessions.

   Devices.cpp, .h
      A quite large table with the built-in PIC device 
      info, and some routines to load PIC device def's
      from an INI file (namely "devices.ini") .
      NOTE: DEVICES.INI is not contained in the sourcecode
            archive - copy it from the archvice with the
            executable file !

   HelpIDs.cpp, .h
      A table of text markers (anchors) in the help system.
      
   PIC_HEX.cpp, .h
      Reads and writes HEX files (specialized for PICs).

   PIC_HW.cpp, .h
      Low-level hardware access routines .
      Does the COM- and LPT- port I/O using SMPORT .

   SMPORT.sys, .vxd
      SmallPort access driver by A. Weitzmann .
      Does some nasty I/O access which would otherwise
      be impossible. Even works under Win XP (unlike some
      of the other port access drivers out there !)
      Must be located in the same directory as the
      executable, otherwise the simple installation method
      of "copy everything into a folder and start it"
      would not work. See comments on TSMPort.cpp below !
      Note: for legal reasons, I canot add all sourcecodes
      in "my" archive. See notes on "PortTalk" further down.

   WinPicPr.cpp, .dfm, .h
      The "main form" (MS would call it "document").
      Utterly overcrowded as WinPic grew over the years.
      Contains the user interface but no really interesting
      stuff from a system programmer's point of view.

   ToolWin1.cpp, .dfm, .h
      The small 'Tool' window with the "Reload & Program"
      button, which may placed in front of other windows.

   \18F\PIC18F_PRG.cpp, .h
      PIC programming routines for the newer PIC18F devices.
      Written and tested by Martin van der Werff .
      See Copyright note and terms of use in the sourcefile !


Some notes on PortTalk vs SmallPort 
---------------------------------------
Since November 2005, I use an optional driver to access the
I/O ports called "PortTalk" (read more on that, and why 
PortTalk is often faster than SmallPort in the manual).
To compile WinPic *with* the option to talk to the ports
   using PortTalk, you will have to find PortTalk yourself
   on the web, due to this statement in one of the PortTalk
   sourcecode modules which I used in WinPic :
   > Permission is herby granted to modify or enhance 
   > this sample code to produce a derivative program which
   > may only be distributed in compiled object form .
Ok.. if you don't need the speed of PortTalk (because you only
use PICs with less than a few ten kBytes), you can build WinPic
without the optional PortTalk support as explained below:
 - remove the macro definition USE_PORTTALK (in "Compiler Options")
 - remove the following files from the BCB project :
     - AllowIoWrapper.c
     - inoutport.obj
 - rebuild the complete project, the linker should be happy now

If you are curious about the differences between SmallPort and 
PortTalk, look into the sourcefile TSmPort.cpp, and read the note
in the revision history dated 2005-11-05 !
( I actually modified TSmPort.cpp so it can use the SmallPort driver
  as well as the PortTalk driver; TSmPort's method "OpenDriver()"
  now tells it which driver to use *during runtime* ).


Other (external) modules ... 
---------------------------------------
 which are not located in the WinPic directory
 but are needed to COMPILE everything.
 Should be copied to the 'External' directory
 which may be included in the source file archive,
 but the project file uses the 'Original' files
 for several reasons (the single source principle 
 is one of them). The path specifications below
 are relative to the location of the project file.
   
   ..\SMPORT\TSmPort.cpp, .h
       DL4YHF's implementation of the TSmPort class
       in C++. 
       This was once a fancy DELPHI component(!)
       but is now a clean C++ class which does not
       require any of Borland's VCL stuff.
       (But still you need the VCL to compile 
        WinPic's user interface !)

   ..\YHF_Tools\YHF_Help.cpp, .h
       DL4YHF's simple HTML-based help system.
       Use your HTML editor to produce help files,
       and forget about the utterly complicated
       "help compiler" from Microsoft.
       (Has nothing got to do with the 
        HTML HELP system by MS - no special DLL's
        required to use this !)
       Located in CBproj\YHF_tools  on the author's
       PC. Used by numerous other applications !
      NOTE: THERE IS AN UGLY BUG 
            IN BORLAND C++BUILDER V6,
            related to the "OnHelp" event.
            There is also an UGLY fix for this bug,
            search the net for "Delphi 6 OnHelp Bug".
            The file D6OnHelpFix.pas must be linked
            into your project, if you use BCB V6 .

    
   ..\YHF_Tools\YHF_MultiLang.cpp, .h
       DL4YHF's helper for multi-language support.
       Contains routines like YHF_TranslateAllForms()
       and YHF_SetLanguage() .
       The prefix "YHF" was chosen aritrarily ;-)
       to avoid name conflicts with other modules.
    
 NOTE: To *RUN* WinPic, also copy the supplementary
       files (DEVICES.INI, the various interface
       definition files, and the help system)
       from the archive with the executable file 
       (winpicpr.zip) !
       To avoid duplicating these files, they are
       *NOT* contained in the sourcecode archive .




Revision history
----------------------------------------------------
Not here, but in README.TXT in the same directory


    --... ...--   .-.-.   ...-.-
