CTL3D.TXT - version 2.01
---------

Contents of this file:

What is CTL3D.PAS?
Limitations imposed by CTL3D.DLL
Using CTL3D in your applications
   A Note on Dialog Resources
   Using CTL3D for Windows 3.1 Only
   Using CTL3D for Windows 3.0
   Using CTL3D With DLLs
If You Have Problems

What is CTL3D.PAS?
------------------

This file gives guidance on how to use the CTL3D unit with Borland Pascal 7.0 (BP7)
together with Microsoft's CTL3D.DLL (vbersions 0.9 through 2.01) to equip applications
for using Microsoft-style 3D dialogs and message boxes.

The interface unit CTL3D.PAS takes care of all the interfacing needed with Microsoft's
CTL3D DLL, for both Windows 3.0 and Windows 3.1.  If your application is designed to
run only under Windows 3.1, changing it to use the 3D controls is as easy as including
CTL3D in the Uses clause and changing just a few lines of code. Due to the nature of
Microsoft's CTL3D.DLL, some more (fairly straightforward) work is required to use 3D
controls if your application is also designed to run under Windows 3.0.

When you use the CTL3D interface unit in your applications, they will automatically
detect the presence of CTL3D.DLL at run time, and provide 3D dialogs and message boxes
if it is found. If CTL3D.DLL is not found, your application will revert to using the 
standard look dialogs as defined in your resource files. If your application also
uses BWCC, the use of CTL3D will not interfere: it will provide the Microsoft 3D-look
for any common dialogs it uses, if you desire.

Limitations imposed by CTL3D.DLL
---------------------------------

While the CTL3D interface unit gives your applications access to all the facilities of
the CTL3D DLL, that DLL has some inherent limitations as documented by Microsoft.
Briefly, these are as follows:

(1) CTL3D.DLL will 'subclass' (that is, provide 3D appearance for) individual dialogs
    and message boxes only for VGA-resolution (640x480) displays or higher.
(2) CTL3D.DLL will allow an application to 'auto-subclass' (that is, automatically
    provide 3D appearance for ALL that application's dialogs and message boxes) only
    under Windows 3.1. It cannot do this when running under Windows 3.0.

Using CTL3D in your applications
--------------------------------

The work you have to do to convert your applications to use CTL3D is not difficult. Just
copy CTL3D.DLL to your windows/system directory and follow the instructions given below.

A Note on Dialog Resources
--------------------------

CTL3D works with 'standard' dialog resources created via Borland's Resource Workshop or
other resource editor, but not with BWCC dialogs (those using controls supported by
Borland's BWCC.DLL). It will work with these resources unchanged, but you may find you
need to 'tweak' some of them a little to compensate for the slightly changed control
sizes introduced by the CTL3D DLL.

Using CTL3D for Windows 3.1 Only
--------------------------------

If your application is designed for use only with Windows 3.1, you need only follow these
simple steps:

(1) Include CTL3D in the appropriate Uses clauses.

    CTL3D needs to be included in the Uses clause of those program units which use the
    TApplication object and the unit declaring your main TWindow or TMDIWindow object. Put
    CTL3D anywhere in the Uses clauses *AFTER* any BWCC.

(2) Replace any direct reference to the following objects with the replacement shown (the
    easiest way is to do a global replace on your source code):

      Replace                           With
      -------                           ----
      TApplication                      T3dApplication
      TWindow                           T3dWindow
      TMDIWindow                        T3dMDIWindow

(3) *** For users of previous versions of CTL3D.PAS only ***:

    In previous versions of this unit, you needed to add three parameters to your main
    application object's Init constructor. This is no longer necessary, and they should be
    removed.

(4) In your application object's InitInstance method (if you haven't defined one, then
    you must override the one inherited from TApplication), add a call to Register3dApp
    as follows:

    Register3dApp(Name,True,<Borders3D>,<CommDlgs3D>)

    where,
      <Borders3D> is TRUE if you want the 3D dialogs to have 3D borders,
                  or FALSE to use standard dialog borders;
      <CommDlgs3D> is TRUE if you want the Windows 3.1 common dialogs used by
                   the application to be made 3D, or FALSE otherwise.

(5) If your main window object processes the wm_SysColorChange message, ensure its method
    is named WMSysColorChange, and that it first calls its inherited method, thus:

    inherited WMSysColorChange(Msg);

    If your main window does not process the wm_SysColorChange message, you do *NOT* need
    to do this!

Now recompile your application, and you should have the 3D dialogs working properly. If you
experience problems, refer to the "If You Have Problems" topic at the end of this file.

Using CTL3D for Windows 3.0
---------------------------

If your application is designed to run under Windows 3.0 (whether or not it can run under
Windows 3.1 as well), you need to perform a little more work. The reason for this is that
CTL3D.DLL does not support the 'auto-subclassing' feature available under Windows 3.1 :-
this means that you have to 'sub-class' each individual dialog and common dialog.

To prepare your application for using CTL3D, perform the following steps:

(1) Include CTL3D in the appropriate Uses clauses.

    CTL3D needs to be included in the Uses clause (*AFTER* any BWCC) of those program units
    which declare any of the following:

    - the main Application object (derived from TApplication),
    - the main window object (derived from TWindow or TMDIWindow),
    - one or more dialog objects (derived from TDialog).

    Also, CTL3D needs to be included in the Uses clause of any program units which call any
    of the common dialog functions.

(2) Replace any direct reference to the following objects with the replacement shown (the
    easiest way is to do a global replace on your source code):

      Replace                           With
      -------                           ----
      TApplication                      T3dApplication
      TWindow                           T3dWindow
      TMDIWindow                        T3dMDIWindow
      TDialog                           T3dDialog

(3) *** For users of previous versions of CTL3D.PAS only ***:

    In previous versions of this unit, you needed to add three parameters to your main
    application object's Init constructor. This is no longer necessary, and they should be
    removed.

(4) In your application object's InitInstance method (if you haven't defined one, then
    you must override the one inherited from TApplication), add a call to Register3dApp
    as follows:

    Register3dApp(Name,False,<Borders3D>,<CommDlgs3D>)

    where,
      <Borders3D> is TRUE if you want the 3D dialogs to have 3D borders,
                  or FALSE to use standard dialog borders;
      <CommDlgs3D> is TRUE if you want to allow the Windows 3.1 common dialogs used by
                   the application to be 3D, or FALSE otherwise.

(5) If your main window object processes the wm_SysColorChange message, ensure its method
    is named WMSysColorChange, and that it first calls its inherited method, thus:

    inherited WMSysColorChange(Msg);

    If your main window does not process the wm_SysColorChange message, you do *NOT* need
    to do this!

(6) If any of your dialog objects process any of the following messages, you must ensure
    the methods first call their inherited ancestors, thus:

    Message            Method Identifier       Insert call
    -------            -----------------       -----------

    wm_DlgBorder       WMDlgBorder             inherited WMDlgBorder(Msg);
    wm_InitDialog      WMInitDialog            inherited WMInitDialog(Msg);


(7) If your application calls any of the common dialog functions listed below, and you wish
    to use their 3D equivalents, you should replace the function names by those shown (the
    names are all equivalent, except for the "3d" suffix. All parameters to the common
    dialog functions remain unchanged:

    Original Name            Change To
    -------------            ---------

    ChooseColor              ChooseColor3D
    ChooseFont               ChooseFont3D
    FindText                 FindText3D
    GetOpenFilename          GetOpenFilename3D
    GetSaveFilename          GetSaveFilename3D
    PrintDlg                 PrintDlg3D
    ReplaceText              ReplaceText3D

Now recompile your application, and you should have the 3D dialogs working properly. If you
experience problems, refer to the "If You Have Problems" topic below.

Using CTL3D With DLLs
---------------------

If you are using CTL3D from a DLL, you can use the auto-subclassing feature under Windows 3.1
to give the 3D look to the dialogs used by the DLL's calling application (and all of the
dialogs used by any DLL called by that application), as follows:

(1) Include CTL3D in the appropriate Uses clauses.

    CTL3D needs to be included in the Uses clause of the DLL main unit. Put
    CTL3D anywhere in the Uses clauses *AFTER* any BWCC.

(2) In your DLL's main initialisation code, add a call to Register3dDLL
    as follows:

    Register3dDLL(Name,True,<Borders3D>,<CommDlgs3D>)

    where,
      <Borders3D> is TRUE if you want the 3D dialogs to have 3D borders,
                  or FALSE to use standard dialog borders;
      <CommDlgs3D> is TRUE if you want the Windows 3.1 common dialogs used by
                   the application to be made 3D, or FALSE otherwise.

(3) In your DLL's exit procedure, add a call to Deregister3D (this procedure 
    takes no parameters).

    NB: If you do not already define your own Exit procedure for the DLL, it is
        recommended that you do define one and have it call Deregister3D. Refer to
        your BPW Language Guide for guidance on how to do this.

If You Have Problems
--------------------

If, when you run your modified application, none of your dialogs or message boxes appear 3D
it is likely that CTL3D could not be found. You should copy CTL3D to your windows\system
directory and then run your application again.

If your application is runnimg under Windows 3.0 and your dialogs are not all properly shown
in 3D, ensure your code does the following:

(a) Objects that were declared as ancestors of TDialog are now declared as ancestors of
    T3dDialog.
(b) Any dialog's methods that process the windows messages listed in (5) above call their
    inherited equivalent (NB: do not use explicit qualification such as "TDialog.WMSetText".
    You should use the  "inherited" keyword instead).
(c) Any common dialog function call now uses the replacement function listed in (6) above.

--------------------------------------
Steve Hamer-Moss,
CoCo Systems Ltd., UK.
August 1993.

EMail addresses:

Compuserve:  100034,1064
CIX:         shammoss

and via Internet:

100034.1064@compuserve.com      or
shammoss@cix.compulink.co.uk
