Return to readme.txt CVS log

Up to [WindowsNT SDKs] / mstools / mfc / samples

Annotation of mstools/mfc/samples/readme.txt, revision 1.1

1.1     ! root        1: ========================================================================
        !             2:       MICROSOFT FOUNDATION CLASS LIBRARY : EXAMPLE CODE
        !             3: ========================================================================
        !             4: 
        !             5: I. Introduction
        !             6: 
        !             7: This directory contains all of the Microsoft Foundation Class (MFC)
        !             8: library example programs, which highlight many object-oriented
        !             9: Windows programming techniques and class library features.  Each 
        !            10: example is a complete and functional program that explores
        !            11: different aspects of the library.
        !            12: 
        !            13: These programs are useful as learning tools, when used in conjunction
        !            14: with the MFC reference documentation.  You can take the code provided
        !            15: and experiment with it.  One group of sample programs, in the TUTORIAL
        !            16: subdirectory, supplements the MFC Tutorial and should be studied in
        !            17: conjunction with that document.
        !            18: 
        !            19: Each subdirectory has both PWB-compatible and NMAKE-compatible makefiles.
        !            20: The PWB makefiles can be identified by the .MAK file extension.  NMAKE
        !            21: makefiles are called 'makefile', with the exception of the TUTORIAL
        !            22: subdirectory (the difference is explained in TUTORIAL\README.TXT).
        !            23: 
        !            24: -----------------------------------------------------------------------
        !            25: Windows and C runtime libraries referenced by the makefiles should
        !            26: be installed as part of the NT setup.  These libraries can be found
        !            27: in \NT\MSTOOLS\LIB.
        !            28: -------------------------------------------------------------------------
        !            29: 
        !            30: II. Compiling sample programs with Microsoft NMAKE
        !            31: 
        !            32: To compile a sample program with NMAKE:
        !            33: 
        !            34: 1. Ensure you have the appropriate C runtime and Foundation
        !            35: runtime librarie   All MFC library variants necessary to build
        !            36: the samples are provided in binary form in MFC\LIB.
        !            37: 
        !            38: 
        !            39: 2. Ensure you have set up your LIB, INCLUDE, and PATH environment variables
        !            40: appropriately.  For example:
        !            41: 
        !            42:    set LIB=C:\NT\MSTOOLS\LIB
        !            43:    set INCLUDE=C:\NT\MSTOOLS\MFC\INCLUDE;C:\NT\MSTOOLS\H
        !            44:    set PATH=C:\NT\MSTOOLS\BIN;%PATH%
        !            45: 
        !            46: Remember you must put the MFC\LIB and MFC\INCLUDE directories in
        !            47: your LIB and INCLUDE paths, respectively, if you wish to compile
        !            48: Foundation applications.
        !            49: 
        !            50: Note: the NT linker does not interpret the LIB environment variable
        !            51: in the same way as other Microsoft linkers.  You should not specify a
        !            52: set of LIB directories -- only one directory.  The makefile interprets
        !            53: LIB, not the linker.  LIB should be set to point to one and only one
        !            54: directory -- the one containing the C runtime libraries and Windows
        !            55: import libraries.  The MFC library locations are specified by relative
        !            56: paths in MFC\SAMPLES\NTSAMPLE.MAK.
        !            57: 
        !            58: 
        !            59: 3. Change your working directory to the appropriate sample file 
        !            60: directory and invoke NMAKE.  
        !            61: 
        !            62: In most cases, invoking NMAKE with no arguments will compile and 
        !            63: link the retail version of that directory's sample application.  
        !            64: If you wish to build the debug version, specify 'DEBUG=1' on the 
        !            65: NMAKE command line.  If you want to remove object, compiled resource, 
        !            66: and executable files, specify the 'clean' target.  For example:
        !            67: 
        !            68:   cd \nt\mstools\mfc\samples\about2
        !            69:   nmake NTMFC=1                      ' creates retail version of about2.exe
        !            70:   nmake clean                 ' removes about2.exe/.obj/.res
        !            71:   nmake NTMFC=1 DEBUG=0              ' creates retail version of about2.exe
        !            72:   nmake clean                 ' removes about2.exe/.obj/.res
        !            73:   nmake NTMFC=1 DEBUG=1              ' creates debug version of about2.exe
        !            74: 
        !            75: You can also 'SET NTMFC=1' before running any of the nmakes.
        !            76: Object and resource files are created in the current directory.
        !            77: 
        !            78: Compilation procedures for the tutorial subdirectory are slightly
        !            79: different than is documented here.  See MFC\SAMPLES\TUTORIAL\README.TXT
        !            80: for more information.
        !            81: 
        !            82: NOTE: See technical note MFC\DOC\TN007.TXT for special information
        !            83: on setting up your Windows environment to handle Foundation library
        !            84: debugging output.
        !            85: 
        !            86: 
        !            87: -----------------------------------------------------------------------
        !            88: 
        !            89: III. Samples
        !            90: 
        !            91: Here is a list of the sample directories and an overview of their
        !            92: content.  See below for more detailed explanations
        !            93: 
        !            94:        ABOUT2      simple dialog box example.
        !            95:        CHART       a simple bar/line charting application.
        !            96:        CTRLTEST    a control test driver showing custom controls.
        !            97:        FILEVIEW    a simple text file viewer.
        !            98:        HELLO       basic application described in the MFC Tutorial.
        !            99:        HELLOAPP    an extremely simple MFC application.
        !           100:        MDI         demonstrates how to program to the MFC MDI interface.
        !           101:        MINMDI      a bare-bones MDI application.
        !           102:        MINSVR      a minimal OLE server application.
        !           103:        MINSVRMI    a minimal OLE server application with multiple inheritance.
        !           104:        MULTIPAD    an MDI NOTEPAD application.
        !           105:        OCLIENT     an example of an Object Linking and Embedding (OLE) client.
        !           106:        OSERVER     a simple OLE server application (called BIBREF)
        !           107:        RESTOOL     a simple non-Windows tool for Windows resources.
        !           108:        SHOWFONT    a font attribute viewer.
        !           109:        TEMPLDEF    a non-Windows tool for expanding C++ templates.
        !           110:        TRACER      a Windows utility to view and set diagnostic trace options.
        !           111:        TUTORIAL    source for tutorial examples.
        !           112: 
        !           113: -------------------------------------------------------------------------
        !           114: 
        !           115: ABOUT2\ABOUT2.EXE
        !           116: 
        !           117: This program is a re-implementation of the ABOUT program found in
        !           118: Charles Petzold's book, "Programming Windows"; it has been written
        !           119: using C++ and the Foundation classes.  ABOUT2 allows you to draw
        !           120: either a rectangle or an ellipse in one of several colors in the
        !           121: client area of a application main window.  The source code
        !           122: illustrates the following concepts:
        !           123: 
        !           124:     - Simple Foundation application structuring.
        !           125:     - Simple dialog box initialization and management.
        !           126:     - Graphics Device Interface (GDI) wrapper classes.
        !           127: 
        !           128: -------------------------------------------------------------------------
        !           129: 
        !           130: CHART\CHART.EXE
        !           131: 
        !           132: This program implements a simple bar/line charting application.
        !           133: You can enter a data set (list of integers), display the data in
        !           134: bar or line chart form, print the chart, save the data to disk, 
        !           135: and read in previously saved data.  The source code illustrates
        !           136: the following concepts:
        !           137: 
        !           138:     - Dialog box management.
        !           139:     - Document state management (dirty, clean).
        !           140:     - Using GDI calls to draw a graph to a device context.
        !           141:     - Using Foundation CFile and CArchive classes to save and
        !           142:       restore user data.
        !           143:     - Printing.
        !           144: 
        !           145: -------------------------------------------------------------------------
        !           146: 
        !           147: CTRLTEST\CTRLTEST.EXE
        !           148: 
        !           149: The main application (in DCONTROL.H, DCONTROL.CPP and DCONTROL.RC)
        !           150: provides a simple frame window with a single menu to drive the tests.
        !           151: This can be easily extended to drive additional tests.
        !           152: 
        !           153: All the examples are based off a the class CParsedEdit which
        !           154: is derived from the standard Windows CEdit class.  CParsedEdit
        !           155: provides a simple keyboard input filter to only allow numbers,
        !           156: letters, control characters, combinations of the above or any
        !           157: characters.
        !           158: 
        !           159: This sample also includes MUSCROLL.DLL, the "micro scrolling"
        !           160: custom control provided in the Windows 3.1 SDK, as well as tests
        !           161: for Pen Windows edit items (requires Windows for Pen).
        !           162: 
        !           163: The source code illustrates the following concepts:
        !           164: 
        !           165:        - example parsed edit control (CParsedEdit) derived from
        !           166:                the standard Windows CEdit class.
        !           167:        - bitmap buttons
        !           168:        - owner draw/self draw controls
        !           169:        - owner draw/self draw menus
        !           170:        - using C++ to create controls for a dialog using Create
        !           171:                member functions for the controls (not recommended,     
        !           172:                DERTEST.CPP, DERTEST.DLG)
        !           173:        - exporting custom controls and registering a new WndClass
        !           174:                so the controls can be used by the dialog manager
        !           175:                (the "PAREDIT" control class used in WCLSTEST.CPP
        !           176:                and WCLSTEST.DLG).  These controls can be edited with the
        !           177:                SDK dialog editor (DLGEDIT.EXE) as custom controls
        !           178:                by typing in the class name "PAREDIT" and the
        !           179:                hex representation of the PES_ styles.
        !           180:        - using SubclassWindow/SubclassDlgItem to dynamically
        !           181:                subclass a dialog control to add specialized behaviour
        !           182:                (SUBTEST.CPP, SUBTEST.DLG).
        !           183:        - example of an external control packed as a DLL (MUSCROLL.DLL)
        !           184:                being used by C++ code with a special C++ wrapper class.
        !           185:        - an example of a spin button using the external MUSCROLL.DLL.
        !           186:        - examples of Windows for Pen special edit controls
        !           187: 
        !           188:        more advanced topics:
        !           189:        - ON_CONTROL handler (in WCLSTEST.CPP responding to new
        !           190:                        control notification PEN_INVALIDCHAR).
        !           191:        - example of how style bits (PES_ style bits for the parsed
        !           192:                edit) can be stripped off before the normal CEdit
        !           193:                control is created.
        !           194: 
        !           195: The source code to this application should be read along with
        !           196: Foundation technical note 14 (MFC\DOC\TN014.TXT) describing
        !           197: custom controls and other topics.
        !           198: 
        !           199: 
        !           200: -------------------------------------------------------------------------
        !           201: 
        !           202: FILEVIEW\FILEVIEW.EXE
        !           203: 
        !           204: This program implements a simple text file viewer.  Unlike 
        !           205: Windows NotePad, this program places no limit on the size 
        !           206: of the text file that may be viewed.  This program is for
        !           207: viewing text files only, and not editing them.  The source code
        !           208: illustrates the following concepts:
        !           209: 
        !           210:     - Foundation application structuring.
        !           211:     - Use of the Foundation file classes as base
        !           212:       classes for derivation and specialization.
        !           213:     - Use of the GDI classes for graphical output.
        !           214:     - Use of Message Maps for handling window scrolling.
        !           215: 
        !           216: 
        !           217: -------------------------------------------------------------------------
        !           218: 
        !           219: HELLO\HELLO.EXE
        !           220: 
        !           221: Described in the MFC Tutorial, this application shows the basics of
        !           222: using the Microsoft Foundation Class Library to write applications
        !           223: for the Microsoft Windows environment.  This application creates and
        !           224: displays a fully-functional frame window, which in turn displays a
        !           225: text string in its center.  The source code illustrates the following
        !           226: concepts:
        !           227: 
        !           228:     - Simple Foundation application structuring.
        !           229:     - Integrating Windows resources with your application.
        !           230: 
        !           231: -------------------------------------------------------------------------
        !           232: 
        !           233: HELLOAPP\HELLOAPP.EXE
        !           234: 
        !           235: This is an extremely simple MFC application that simply creates a
        !           236: main frame window with the caption 'Hello World!'.  It is compiled
        !           237: using retail libraries only.
        !           238: 
        !           239: -------------------------------------------------------------------------
        !           240: 
        !           241: MDI\MDI.EXE
        !           242: 
        !           243: The MDI application demonstrates how to program to the MFC wrapper of 
        !           244: the Windows Multiple Document Interface (MDI) wrapper.  When started,
        !           245: the MDI application provides an MDI frame window, and two kinds of MDI
        !           246: child windows that you may open within the frame.  One child window
        !           247: is similar to the HELLO example program (it displays "Hello World"
        !           248: in its client area).  The other kind of child window contains a 
        !           249: bouncing ball.  The source code illustrates the following concepts:
        !           250: 
        !           251:     - Foundation MDI application structuring.
        !           252:     - Coordinating MDI frame and child classes.
        !           253:     - Using Windows timers.
        !           254:     - Using the CBitmap class for constructing and drawing a
        !           255:       bit pattern into a device context.
        !           256: 
        !           257: -------------------------------------------------------------------------
        !           258: 
        !           259: MINMDI\MINMDI.EXE
        !           260: 
        !           261: This is a bare-bones MDI application that concentrates on showing the
        !           262: minimum work needed to set up and maintain MDI child windows within
        !           263: an MDI frame window.  You can use this application as a starting point
        !           264: for your own experimentation with the MDI interface.  The source code
        !           265: illustrates the following concepts:
        !           266: 
        !           267:     - Foundation MDI application structuring.
        !           268:     - Coordinating MDI frame and child classes.
        !           269: 
        !           270: -------------------------------------------------------------------------
        !           271: 
        !           272: MINSVR\MINSVR.EXE
        !           273: 
        !           274: MINSVR is a minimal OLE server application that implements
        !           275: a graphical ellipse drawing.  When running MINSVR *directly* (from
        !           276: the program manager, file manager, or an icon), MINSVR is registered
        !           277: with the registration data base.  YOU MUST RUN MINSVR DIRECTLY before
        !           278: you can use it with other OLE programs.  Once you have run MINSVR
        !           279: directly, you can use it with OLE Clients where it provides basic
        !           280: embeddable object services.
        !           281: 
        !           282: The source code illustrates the following concepts:
        !           283: 
        !           284:     - Constructing a minimal OLE server
        !           285:     - Programming with the MFC OLE classes
        !           286:     - Supporting embedded objects
        !           287: 
        !           288: It is highly recommended that you read Foundation technical notes 8, 9,
        !           289: and 10 (MFC\DOC\TN008.TXT, etc.) for more information on the MFC OLE
        !           290: classes and constructing OLE clients and servers using MFC.
        !           291: 
        !           292: 
        !           293: -------------------------------------------------------------------------
        !           294: 
        !           295: MINSVRMI\MINSVRMI.EXE
        !           296: 
        !           297: MINSVRMI is a simple OLE server application that implements a
        !           298: graphical elliptical drawing.  It is the same program as MINSVR
        !           299: except it is implemented using multiple inheritance.  When MINSVRMI is
        !           300: *directly* run, it registers itself with the registration database. 
        !           301: YOU MUST RUN MINSVRMI directly before using it with other OLE
        !           302: programs.  When run from an OLE client, MINSVRMI allows you to embed
        !           303: objects in the client application's document.
        !           304: 
        !           305: The source code illustrates the following concepts:
        !           306: 
        !           307:     - Constructing a minimal OLE server
        !           308:     - Programming with the MFC OLE classes
        !           309:     - Using multiple inheritance with MFC and MFC OLE classes
        !           310:     - Supporting embedded objects
        !           311: 
        !           312: It is highly recommended that you read Foundation technical notes 8, 9,
        !           313: and 10 (MFC\DOC\TN008.TXT, etc.) for more information on the MFC OLE
        !           314: classes and constructing OLE clients and servers using MFC.
        !           315: 
        !           316: You should also read Foundation technical note 16 (MFC\DOC\TN016.TXT)
        !           317: for more information on MFC and multiple inheritance.
        !           318: 
        !           319: -------------------------------------------------------------------------
        !           320: 
        !           321: MULTIPAD\MULTIPAD.EXE
        !           322: 
        !           323: Microsoft Windows provides a simple application called NOTEPAD.  The
        !           324: MFC library adaptation of this program uses the MDI paradigm to allow
        !           325: the user to manipulate any number of concurrently open text files. 
        !           326: MULTIPAD is fully functional and includes printing support as well as
        !           327: other features usually found only in commercial Windows applications:
        !           328: a status bar at the bottom of the window, and a cache of
        !           329: most-recently-used filenames (saved between program invocations) so
        !           330: that users may quickly access recently used documents.  The source
        !           331: code illustrates the following concepts:
        !           332: 
        !           333:     - Non-trivial MDI application structuring.
        !           334:     - Menu command dispatching.
        !           335:     - Dialog box initialization and management.
        !           336:     - Printing.
        !           337:     - Porting existing Windows code for use with MFC.
        !           338:     - Swap tuning an application for Windows for maximum efficiency.
        !           339: 
        !           340: 
        !           341: -------------------------------------------------------------------------
        !           342: 
        !           343: OCLIENT\OCLIENT.EXE
        !           344: 
        !           345: OCLIENT is an example of an Object Linking and Embedding (OLE) client
        !           346: application.  It uses the Foundation OLE classes.  This program is a port
        !           347: of the OLEDEMOC program which is shipped by the Microsoft OLE Software
        !           348: Development Kit.  The program allows you to insert both embedded and
        !           349: linked objects into a document.  OCLIENT also allows you to perform both
        !           350: file and clipboard operations on the objects as well as activate the
        !           351: servers to which the objects belong. The source code illustrates the
        !           352: following concepts:
        !           353: 
        !           354:     - OLE client programming using MFC
        !           355:     - Inserting embedded objects into a client
        !           356:     - Pasting linked and embedded objects into a client
        !           357:     - Copying objects to the clipboard
        !           358:     - Loading and saving objects to and from disk
        !           359: 
        !           360: It is highly recommended that you read Foundation technical notes 8, 9,
        !           361: and 10 (MFC\DOC\TN008.TXT, etc.) for more information on the MFC OLE
        !           362: classes and constructing OLE clients and servers using MFC.
        !           363: 
        !           364: -------------------------------------------------------------------------
        !           365: 
        !           366: OSERVER\BIBREF.EXE
        !           367: 
        !           368: BIBREF is a simple OLE server application that implements
        !           369: bibliographical references.  When BIBREF is *directly* run, it
        !           370: registers itself with the registraton database and allows you to add,
        !           371: modify, and delete bibliographical references from a list maintained
        !           372: by the application.  YOU MUST RUN BIBREF DIRECTLY before using it
        !           373: with other OLE programs.  When run from an OLE client, BIBREF allows
        !           374: you to embed objects containing these references in the client
        !           375: application's document.
        !           376: 
        !           377: The source code illustrates the following concepts:
        !           378: 
        !           379:     - Constructing an OLE server
        !           380:     - Programming with the MFC OLE classes
        !           381:     - Supporting embedded objects
        !           382: 
        !           383: It is highly recommended that you read Foundation technical notes 8, 9,
        !           384: and 10 (MFC\DOC\TN008.TXT, etc.) for more information on the MFC OLE
        !           385: classes and constructing OLE clients and servers using MFC.
        !           386: 
        !           387: 
        !           388: -------------------------------------------------------------------------
        !           389: 
        !           390: RESTOOL\RESTOOL.EXE
        !           391: 
        !           392: RESTOOL is a simple non-Windows application that reads a Microsoft
        !           393: Windows compiled resource (.RES) file and generates C++ class
        !           394: declarations for any dialog boxes found in the resource file.
        !           395: This allows you to quickly put together MFC CDialog-derived classes
        !           396: that manipulate dialog boxes you already use in existing applications.
        !           397: 
        !           398: RESTOOL's output must be reviewed before using (RESTOOL uses some
        !           399: heuristics that are not universally applicable) and you must put the 
        !           400: generated code into a proper C++ header file.  The source code
        !           401: illustrates the following concepts:
        !           402: 
        !           403:     - Using MFC libraries to write a non-Windows application.
        !           404:     - Microsoft Windows resource file format.
        !           405: 
        !           406: 
        !           407: -------------------------------------------------------------------------
        !           408: 
        !           409: SHOWFONT\SHOWFONT.EXE
        !           410: 
        !           411: This program is a C++/Foundation adaptation of a sample application
        !           412: provided in the Microsoft Windows 3.0 Software Development Kit (SDK).
        !           413: SHOWFONT is a font attribute viewer.  It allows you to quickly
        !           414: determine the visual and logical characteristics of Windows GDI FONT
        !           415: resources.  The source code illustrates the following concepts:
        !           416: 
        !           417:     - Modal and modeless dialog box management.
        !           418:     - CFont attribute manipulation.
        !           419:     - Menu command dispatching.
        !           420: 
        !           421: 
        !           422: -------------------------------------------------------------------------
        !           423: 
        !           424: TEMPLDEF\TEMPLDEF.EXE
        !           425: 
        !           426: TEMPLDEF is a non-Windows tool that helps you write and use 
        !           427: template-like classes.  Templates are a proposed (but not established)
        !           428: C++ language feature that are very useful for industrial-strength
        !           429: programming.  The MFC library's collection classes use template
        !           430: classes (and the tool provided in this directory) to create specific
        !           431: collection types from general collection types.
        !           432: 
        !           433: The C++ language will someday support such features, but this tool
        !           434: makes some of these proposed advantages available now.  TEMPLDEF
        !           435: reads a "template" file, and writes a new C++ class which is
        !           436: type-safe.
        !           437: 
        !           438: After you have built the templdef tool, you can use the MKCOLL.BAT
        !           439: batch file and the array, list, and map template files (all in the
        !           440: TEMPLDEF subdirectory) to generate your own versions of arrays,
        !           441: lists, and maps.
        !           442: 
        !           443: For more information on the templdef tool, see MFC Technical Note #4,
        !           444: "Template Classes and AFX" (located in MFC\DOC\TN004.TXT).  For more
        !           445: information on proposed C++ templates, see Chapter 14 of "The Annotated
        !           446: C++ Reference Manual," by Ellis and Stroustrup.
        !           447: 
        !           448: 
        !           449: 
        !           450: -------------------------------------------------------------------------
        !           451: 
        !           452: TRACER\TRACER.EXE
        !           453: 
        !           454: TRACER is a tiny Windows utility that allows you to view and set the 
        !           455: Foundation Windows diagnostic trace option flags described in 
        !           456: MFC\DOC\TN007.TXT.  The source code illustrates the following concepts:
        !           457: 
        !           458:     - Reading and writing Windows profile strings
        !           459:     - Writing a Foundation application that uses a modal dialog
        !           460:       box but does not use the regular Windows/MFC message pump.
        !           461: 
        !           462: 
        !           463: -------------------------------------------------------------------------
        !           464: 
        !           465: TUTORIAL\PHBOOK.EXE
        !           466: 
        !           467: PHBOOK is a phone list maintenance application, and is the subject
        !           468: of the MFC tutorial.  PHBOOK allows you to create, edit, print and
        !           469: save lists of people's names and their telephone numbers.  In addition
        !           470: to MFC application programming techniques, this application demonstrates 
        !           471: the development of an abstract data model and the coupling of that
        !           472: data model to a graphical user interface implemented with MFC.  See
        !           473: TUTORIAL\README.TXT for more information on building this application.
        !           474: The source code illustrates the following concepts:
        !           475: 
        !           476:     - MFC Application organization.
        !           477:     - Printing.
        !           478:     - Dialog box management.
        !           479:     - Coupling an abstract data model to a user interface.
        !           480:     - Using MFC object serialization (CArchive class) to save
        !           481:       and load user data.
        !           482: 
        !           483: -------------------------------------------------------------------------

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.