Copyright Notice

Information in this online document is subject to change without notice and does not represent a commitment on the part of Microsoft Corporation. The software, including any databases and online documents, described in this document are furnished under a license agreement or nondisclosure agreement. The software, including any databases and online documents, may be used or copied only in accordance with the terms of the agreement. It is against the law to copy the software on any medium except as specifically allowed in the license or nondisclosure agreement. The purchaser may make one copy of the software for backup purposes. No part of this online document and/or databases may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying, recording, or information storage and retrieval systems, for any purpose other than the purchaser's personal use, without the express written permission of Microsoft Corporation.

© 1993 Microsoft Corporation. All rights reserved.

Microsoft, MS, MS-DOS, and CodeView are registered trademarks and Visual Basic, Visual C++, and Windows are trademarks of Microsoft Corporation.


Main Index Screen
 Microsoft Foundation Classes Library Samples

Information about the MFC source code samples is organized according to the following categories:

  Building the Samples

  Alphabetical List of MFC Samples

  Cross-Reference to Samples by Subject (programming technique)


AFX is the name of the product group at Microsoft that provides object-oriented solutions to help you to write Windows applications in C++. AFX products include App Studio, AppWizard, ClassWizard and MFC.


Building the Microsoft Foundation Classes Samples
Building the Microsoft Foundation Class Library Samples

You can build all of the Microsoft Foundation Class Library samples by:

building all the samples in one step, or

building the samples individually.

Both methods are described below.

Building All the Samples in One Step

The easiest way to build all of the samples is to build them all at once.  Run the batch file MKSAMPLE.BAT from the \MSVCNT\MFC\SAMPLES root directory, using one of the following command line options:

mksample debug

This option builds executables with symbolic information, diagnostics, and no optimizations (larger and slower).

mksample retail

This option builds release versions of executables that are fully optimized (smaller and faster).

mksample clean

The above option removes all compiler generated files (object files, executables, etc.).  Use this to build the debug version after having previously built the retail version, or to go from retail builds to debug builds.

MKSAMPLE.BAT builds all of the samples except:  DLLTRACE, MAKEHM, and TEMPLDEF.  Build instructions for these particular samples are provided in their respective sample descriptions.

Building the Samples Individually

You can build most of the Microsoft Foundation Class Library samples in either of two ways:

build the samples from the Visual C++ Workbench; or

build the samples from the command line.

To build a sample from the Visual C++ Workbench, use the Project Open command, change the directory to that of the sample, and select the sample's .MAK file.   If during the installation of Visual C++ you chose the default directories, the sample directory will be a subdirectory of \MSVCNT\MFC\SAMPLES.

We encourage you to use the source browsing capability of Visual C++ with the samples.  To create a browser database for a sample, follow these steps:

1.	Select the Options command from the Workbench.

2.	Choose Compiler from Customize Build Options in the Project Options dialog.

3.	Choose Listing Files from the Category in the C/C++ Compiler Options.

4.	Choose Browser Information from Category Settings for Listing Files.

For more details, see the Visual Workbench User's Guide.

You can build a sample from the command line by running NMAKE, using either the Visual C++ .MAK file for the sample or a makefile with the default MAKEFILE name.  If you use the .MAK file, then you must specify with the NMAKE -f option, as in:

nmake -f hello.mak

By default, NMAKE uses the makefile named MAKEFILE, and it builds a DEBUG medium model application.  The sample MAKEFILE includes a SAMPLE_.MAK file from the samples root directory, \MSVCNT\MFC\SAMPLES.  The optional NMAKE command line parameters, which are interpreted by SAMPLE_.MAK, are:

nmake DEBUG=0

which uses the retail version of the MFC library; the default option is to use the debug version of the library, and

nmake BROWSE=1

which builds the sample with source browser information and creates a .BSC file; the default option does not build source browser information.

All combinations of the above NMAKE options are supported by versions of the MFC and C runtime libraries that the Visual C++ setup program installs by default.

The following samples require additional libraries:

The DLLTRACE sample requires the version of the Microsoft Foundation Class Library that is statically linked to a Windows DLL:  NAFXDW.LIB (retail) or NAFXDWD.LIB (debug).

The MAKEHM and TEMPLDEF samples are console applications and require the console version of the Microsoft Foundation Class Library [image] NAFXCR.LIB (retail) or NAFXCRD.LIB (debug).

For instructions in building the additional versions of the MFC library required by DLLTRACE, MAKEHM, and TEMPLDEF, see Appendix B of the Class Library User's Guide.

To obtain the additional versions of the C runtime libraries, if you have not already installed them, requires that you run the Visual C++ setup program again to select these versions.  Note, you can do this without having to reinstall the rest of Visual C++.


Alphabetical List of Samples

Sample	Illustrations
APSTUDIO	Clip art that can be added to an application using App Studio.
CHKBOOK	Record-based (non-serialized) document.
CTRLBARS	Custom toolbar and status bar, dialog bar, and floating palette.
CTRLTEST	Owner-draw listbox and menu, custom control, bitmap button, spin control.
DIBLOOK	Device-independent bitmap and color palette.
DLLHUSK	Dynamically linking the DLL version of the MFC library.
DLLTRACE	Statically linking the MFC library to a user DLL.
HELLO	Simple application with frame window but no document or view.
HELLOAPP	Minimal "Hello World" application.
HIERSVR	"Full server" type of OLE server.
MAKEHM	Console utility for associating resources with help contexts.
MDI	MDI application that does not use documents and views.
MINSVR	"Mini server" type of OLE server.
MULTIPAD	Simple use of MDI, using CEditView.
OCLIENT	OLE client.
SCRIBBLE	Class Library User's Guide tutorial example.
SPEAKN	Pen for Windows and multimedia sound, using user-defined resources.
SUPERPAD	Full featured MDI application that uses CEditView.
TEMPLDEF	Tool that expands C++ templates.
TRACER	Tool that sets the MFC application trace flags kept in AFX.INI.
VBCHART	Advanced use of VBX controls, using the Grid VBX control.
VBCIRCLE	Simple use of VBX controls in a dialog and in a frame window.
VIEWEX	Multiple views, scroll view, splitter windows.


Cross-Reference to Samples by Subject

To find a source code sample that illustrates a Microsoft Foundation Class Library feature or programming technique, select one of the following areas:

application object	window objects
documents	graphical display classes
views	dialogs and controls
toolbars	VBX controls
splitter window	DLLs
printing/preview	resources
OLE	context-sensitive help
Also, you can use Help Search to locate illustrations of specific programming techniques.  If the illustration you are looking for does not fit in one of the above categories, for example "collections," try using Help Search.


Application Object

Every MFC Windows application must implement a CWinApp-derived class and create exactly one object of that class.  See the SCRIBBLE tutorial sample and the Class Library User's Guide for an introduction to the concept of an application object, and for an illustration of an application that relies on document template (CDocTemplate) objects to manage the creation of frame windows, document objects, and view objects.

Note  For examples of console applications that use the Microsoft Foundation Class and do not have a CWinApp-derived class, see MAKEHM and TEMPLDEF.

Some of the main roles of CWinApp are to provide the WinMain function required by Windows, to implement the main message loop, and to coordinate the creation of frame windows, documents, and views via document template objects.  CWinApp also provides secondary functionality at the high application level.  The following samples illustrate some of these secondary CWinApp features:

Using a wait cursor during long operations is illustrated by SUPERPAD.

Using a private .INI file via member functions provided by CWinApp is illustrated in SUPERPAD and CHKBOOK.

Registering an application's document type with the Window File Manager is illustrated by HIERSVR.

Overriding CWinApp::OnIdle is illustrated by SUPERPAD and CTRLBARS.

If your application does not lend itself to a document/view architecture, you do not have to use document templates, documents, and views.  This is illustrated in the following samples:

HELLOAPP ilustrates the minimal MFC application.

HELLO illustrates an application that has a single application window, without documents and views.  HELLO is slightly more complicated than the minimal HELLOAPP sample.

TRACER and SPEAKN are examples of an application whose user interface is nothing more than a single dialog box.

The MDI sample illustrates an application that has a multiple document interface (MDI) application without documents and views.


Documents

The SCRIBBLE sample, presented in the Class Library User's Guide, provides a simple illustration of implementing a CDocument-derived class.  SCRIBBLE serves as a good model for any application that can rely on the framework's standard user interface for file handing (eg, File New, Open, Close, and Save) and the framework's automatic serialization of documents.

The following samples illustrate cases where you may need to override the framework's standard document behavior:

A record-based document is illustrated by CHKBOOK.  The default implementation of the framework expects the document to serialize itself to and from disk.  The CHKBOOK document, in contrast, is updated each time the user adds or modifies a record.

A document with an external file format is illustrated by DIBLOOK, which uses the Windows device-independent bitmap file format.

A document that delegates memory management of its data to a view is illustrated by MULTIPAD and VBCHART.  The MULTIPAD document, a text file, is held by a CEditView object.  The VBCHART data is held by a VBX Grid control, which is owned by a view.


Views

The SCRIBBLE tutorial sample, presented in the Class Library User's Guide, provides a simple illustration of coordinating a single CView-derived class with a single CDocument-derived class.  Many of the other samples use CView-derived classes in the course of illustrating other programming techniques.

The following samples illustrate specific techniques related to views, as well as reusable CView-derived classes:

Use of CDocument::UpdateAllViews and hint mechanism to inform multiple view objects about changes to a document is illustrated in SCRIBBLE, CHKBOOK, and OCLIENT.

Scrolling view (CScrollView) is illustrated by SCRIBBLE and CHKBOOK.

Form view (CFormView), which is a view layed out by a dialog template resource, is illustrated by VIEWEX and CHKBOOK.  VIEWEX illustrates printing a form view, and synchronizing a form view with other views.

Edit view (CEditView) is illustrated by MULTIPAD and SUPERPAD.  The SUPERPAD illustration is more advanced.

A static splitter window, where each pane is assigned to a different CView-derived class, is illustrated by VIEWEX and VBCHART.

Multiple views on the same document, where each view is of a different CView-derived class, and where each view is framed by a distinct MDI child window, is illustrated by CHKBOOK.


Toolbars, Status Bars, Dialog Bars, and Floating Palettes

The Microsoft Foundation Class Library provides classes for common kinds of accessory windows that are typically located along the borders of frame windows:  CToolBar, CStatusBar, and CDialogBar, all which are derived from CControlBar.  If you choose the AppWizard Initial Toolbar option, your application will have a standard toolbar and status bar.

Most of the interesting control bar illustrations are provided by CTRLBARS.

Adding buttons to a toolbar is illustrated by SCRIBBLE.

Advanced customization of toolbars and status bars is illustrated by CTRLBARS.  VBCHART also illustrates a dropdown listbox in a toolbar.

A floating tool palette is illustrated  by CTRLBARS.

A dialog bar, which is a control bar whose layout is defined by a dialog template resource, is illustrated by CTRLBARS.


Splitter Windows

Class CSplitterWnd provides support for splitter windows with multiple panes, where each pane is typically a view on the same document.  The following samples illustrate use of splitter windows:

In a dynamic splitter window, panes are created and destroyed as the user splits new views and removes splits, as illustrated by SCRIBBLE.  As in most dynamic splitter windows, the panes represent views of the same CView-derived class in SCRIBBLE.

In a  in a static splitter window, the order and number of panes never changes, as illustrated by VIEWEX and VBCHART.  As in most static splitter windows, the panes represent views of different CView-derivec classes in these samples.


Printing and Print Preview

The SCRIBBLE sample, presented in the Class Library User's Guide, illustrates the basics of framework's printing and print preview support.  The following samples illustrate some very common printing tasks not covered by the SCRIBBLE sample:

Implementing page breaks during printing is illustrated by CHKBOOK and SUPERPAD.

Adding page headers and footers during printing is illustrated by SUPERPAD as well as SCRIBBLE.

Starting print preview at the current selection in the document is illustrated by SUPERPAD.

Returning from print preview to the same position in the document as last previewed is illustrated by SUPERPAD.

Printing a form view (CFormView) is illustrated by VIEWEX.


OLE
Object Linking and Embedding

By chosing the AppWizard OLE Client option, you can enable your application with the basic functionality of an OLE client through derivation from MFC OLE classes.  AppWizard does not provide an option for OLE servers; but you can borrow from one of two OLE server sample applications listed below.  Also, some of the standard OLE user interfaces are not implemented in the MFC OLE classes; but you can borrow implementations from the following samples:

Class support for OLE client applications, and additional OLE client user interfaces, are illustrated in OCLIENT.

A "mini" OLE server is illustrated by MINSVR.  As a mini OLE server, MINSVR only edits embedded objects on behalf of an OLE client; it does not support linked objects.  MINSVR does not directly open or save files.  The MINSVR object is simply a string, which is drawn as text centered in a shaded ellipse.

A "full" OLE server is illustrated by HIERSVR.  As a full OLE server, HIERSVR supports  linked objects as well as embedded objects.  HIERSVR can directly open and save files. The HIERSVR object is a multiple-level hierarchy diagram, where each node in the hierarchy consists of text surrounded by a rectangle or other shapes.


Context-Sensitive Help

Step 6 of the SCRIBBLE tutorial sample, presented in Chapter 10 of the Class Library User's Guide, provides an illustration of implementing context-sensitive help in an application.  The easiest way to get a quick illustration of the framework's context-sensitive help support is to run AppWizard with the help option, build the skeleton application, and then run it, trying out F1 and SHIFT-F1 on various user interface items such as menus and toolbar buttons.

MAKEHM ("Make Help Map") is a console tool which produces a mapping between resource identifications and help contexts.  This tool is invoked by the MAKEHELP.BAT file produced by AppWizard if you choose the Context Sensitive Help Option.

The MAKEHM.EXE is included in \MSVCNT\BIN, so it is not necessary for you to build it from the sources in the MAKEHM sample directory.  We provide the sources as an illustration of a console application that uses the Microsoft Foundation Class Library, and to enable you to modify the tool if desired.


Dynamic Link Libraries

For information about dynamic link library support, you are strongly recommended to read Technical Note 11 and Technical Note 33.  DLL support is illustrated in the following samples:

A DLL that is statically linked to the Microsoft Foundation Class Library is illustrated by DLLTRACE.

An application that is dynamically linked to the DLL version of the Microsoft Foundation Class Library is illustrated by DLLHUSK.

A user DLL which is itself dynamically linked to the DLL version of the Microsoft Foundation CLass Library is also illustrated by DLLHUSK.  Such a user DLL is called an "MFC Extension DLL".

Note:

The DLL version of the Microsoft Foundation Class Library and the DLLHUSK sample are not supported in Visual C++ 1.0 for Windows NT.


Window Objects

CWnd is the base class for all framework window classes, including view classes and frame window classes.  CWnd offers member functions for almost all of the Windows HWND-based functions and WM_ messages.  These CWnd functions and message handlers are illustrated in almost all of the samples.

The following samples illustrate some special techniques for using window objects that are specific to using the Microsoft Foundation Classes, or are which are not covered in general Windows programming literature:

Subclassing a window, to associate a CWnd-derived class with an HWND window, is illustrated by CTRLTEST and SUPERPAD.

Changing the default cursor or icon of a window, by calling AfxRegisterWndClass and passing the WNDCLASS name to CWnd::Create, is illustrated by MDI.

Implementing persistent window placement, by storing window position information in an private .INI file, is illustrated by SUPERPAD.

Implementing a  thin title bar, such as is used for dragging a tool palette, is illustrated by CTRLBARS.


graphical display objects
Graphical Display Classes

Most of the samples illustrate use of GDI classes: CDC and CDC-derived classes, and GDI object classes (CPen, CBrush, etc.).  The following samples illustrate some special GDI techniques using the Microsoft Foundation Class Library:

Use of device-independent bitmaps (DIBs) and color palettes is illustrated by DIBLOOK.

Use of a memory display context to hold a bitmap, and BitBlt'ing the bitmap to a window's client display context, is illustrated by MDI.


Dialogs and Controls

Many of the samples use dialogs, and controls, and the framework's dialog data exchange (DDX) support.  The following samples illustrate special common diaog (COMMDLG.DLL supported) classes and control classes, and some special techniques for using dialogs and controls:

An application whose user interface is nothing more than a single dialog box is illustrated by TRACER and SPEAKN.

Simple use of dialog data exchange is illustrated by SCRIBBLE and TRACER.

Writing custom data exchange (DDX) functions is illustrated by CHKBOOK.

An About dialog showing system resource usage is illustrated in SUPERPAD.

The COMMDLG color dialog is illustrated by MDI.

The COMMDLG font dialog is illustrated by SUPERPAD.

VB controls are illustrated by VBCIRCLE and  VBCHART.

Using a bitmap button is ilustrated by CTRLTEST and SPEAKN.

Using a pen control is illlustrated by CTRLTEST.

A spin control class is implemented in CTRLTEST.

Implementing and using custom controls, and subclassing a control, is illustrated by CTRLTEST and VBCHART.

Owner drawing of menus and listboxes is illustrated by CTRLTEST.

Performing character-by-character validation of a dialog control is illustrated by CHKBOOK.


VB controls
VBX Controls

Two samples illustrate the use of VBX controls.  VBCIRCLE is a tutorial-like sample that uses a simple VB control (circ3.vbx).  VBCHART is a more sophisticated sample that uses a spreadsheet-like grid control (grid.vbx) that you might want to use in your own application.

Note:

VBX controls, and the VBCIRCLE and VBCHART samples are not supported in Visual C++ for Windows NT.


Resources

Most of the samples use resources that are edited using App Studio.  The following samples illustrate resources that are not directly edited by App Studio:

A human-readable .RC file, with user-defined symbols that cannot be maintained as such by App Studio, is illustrated by CTRLTEST.

User-defined resources that should not be restructured or reformatted into hexidecimal data by App Studio is illustrated by SPEAKN.

The APSTUDIO sample directory contains two categories of resources that you can add to your application using App Studio:

Clip-art resources.   These are common appearance icons, bitmaps and cursors that the framework does not depend on but which you might want to add to your application's user interface.

Standard framework resources.  These are resources have AFX-defined IDs that the framework depends on for internal implementations.  You will rarely need to change these AFX-defined resources.

Both kinds of resources reside in various files in the APSTUDIO sample directory.  For more information, see Technical Note 23.  We especially advise you to read this technical note if you wish to customize the standard framework resources.


CHKBOOK
CHKBOOK Sample

The CHKBOOK sample illustrates implementing a record-based document, where the data file is written to on a per record basis rather than on a load/save basis.  Although CHKBOOK's document is a disk file with a CHKBOOK-specific file format, the framework override techniques CHKBOOK employs apply also to documents whose persistent data is maintained in a true database.

CHKBOOK also illustrates multiple views of a document, where (1) each view is of a different CView-derived class, and (2) each view is in a separate MDI child window.

Secondarily, CHKBOOK further illustrates:  scroll view, form view, CView::OnUpdate hint, page breaking during printing, CFile, and custom data exchange (DDX) routine.

Running the Sample

The first time you run CHKBOOK, use File New to create a new CHKBOOK file.  The next time you run CHKBOOK, it will automatically open the file that was last opened, by retrieving the filename from CHKBOOK.INI.

To create or open a second CHKBOOK file, close the first, and then use File New, File Open; or select a file from the MRU list at the bottom of the File menu.  CHKBOOK keeps only one file open at a time.

Enter data for a check using the Check view.  The dollar field is validated for each character you type.  The date field is not validated.  The CHKBOOK file is not updated until you use the Commit Check command of the Edit menu, or the toolbar button that looks like a checkmark.

Use the New Check command of the Edit menu to add a new check; or use the toolbar button which looks like a check form.

The Book view allows you to scroll through all of the checks.  Select a check in the Book view by clicking it with the mouse, or by using the UP, DOWN, PAGEUP, PAGEDN, HOME, or END keys.  The check shown in the Check view always reflects the current selection in the Book view.

You can update the data in the currently selected check via the Check view.  This simple application, however, does not let you delete or void a check.

If one or the other of the Check or Book view is already closed, and you attempt to close the other, then the file will be closed altogether.

Illustration:  Record-based Document

A record-based document is one whose persistent data is updated each time the user add, deletes, or modifies some portion of its data.  This requires overriding the framework's default implementation for file-based documents that are read the entirely into memory upon File Open and written entirely back to disk upon File Close.

Although CHKBOOK's document is a disk file, the techniques employed apply also to documents whose persistent data is maintained in a database.  CHKBOOK uses CFile::Read and Write.

CHKBOOK relies on a simple fixed-length record format for its file.  This sample does not attempt to illustrate more sophisticated file organization.  We have factored the design of CHKBOOK's document class into a generally reusable CFixedLenRecDoc class and a CHKBOOK-specific CChkBookDoc class, which is derived from CFixedLenRecDoc.  You can follow CHKBOOK's example to derive your own document class from CFixedLenRecDoc.

 Illustration:  Multiple Views of Distinct CView-Derived Classes, in Separate MDI Children Windows

CHKBOOK implements multiple views of a document, where each view object is of a different CView-derived class, and where each view object is framed by a distinct MDI child window.  CHKBOOK has two distinct CMultiDocTemplate objects, one corresponding to the Check view, and the other corresponding to the Book view.

The typical use of CMultiDocTemplate objects is to create an independent set of document frame and view objects.  CHKBOOK has two CMultiDocTemplate objects, both using the same CChkBookDoc document class but distinct view classes.  The CChkBookApp::InitInstance function calls AddDocTemplate for both template objects, although only one is needed.  To prevent the framework from presenting the user with the File New dialog that lists two candidate file types, the DocTemplate string resource for the second (IDR_BOOKFRAME) document template does not have a "File New name" (CDocTemplate::fileNewName).

CHKBOOK automatically shows both views when the document is first opened (the user can later close one or the other view).  In order to create the second frame and view, and to ensure that it is attached to the first document object, we override CWinApp::OpenDocumentFile.  The override first calls the base class OpenDocumentFile; the framework creates the first MDI child window and view.  The override then explicitly calls CMultiDocTemplate::CreateNewFrame using the second document template object.


CTRLBARS
CTRLBARS Sample

The CTRLBARS sample illustrates a wide variety of customization options for control bars:

Multiple controls bars in a frame window; selective hiding and unhiding of control bars; dynamic rearrangement of controls along the border of the frame window.

Custom toolbar; dynamic rearrangement of buttons in the toolbar; adding controls (such as a combo box) to a toolbar.

Custom status bar; custom indicators; sending text to the message line.

Dialog bar, which is a control bar whose layout is defined by a dialog resource template.

Floating tool palette, which behaves like a toolbar, but displays a two-dimensional array of tool buttons, and floats as a modeless window above the owner frame window.

Many of the control bar customization options illustrated by CTRLBARS are discussed in Technical Note 31.

Secondarily, CTRLBARS also illustrates using ON_COMMAND_EX, and implementing a thin (no text) title bar.

Building the Sample

Follow the standard instructions for building the Microsoft Foundation Classes samples.

Running the Sample

When you first run CTRLBARS, all the various controls are visible:

 	A toolbar with initially 5 buttons lies immediately below the menu bar.  The first button (thick up-arrow) toggles the toolbar arrangement between "Short" (5 buttons) and "Long" (10 buttons).  All of the buttons are always inactive except this first Short/Long button, and the Help button, which brings up the About box.

A second toolbar lies immediately below the first toolbar.  This toolbar is called the Style Bar in this sample application, since it is where you specify one of the following text alignment styles:  Left, Centered, Right, or Justified.  Selecting one of the styles has no effect other than to change the state of the Style Bar.

A status bar lies at the bottom of the window.

A floating palette, with a 3x4 array of tool buttons, lies on top of the window.

A dialog bar lies on the left border of the window.  It is a "dialog bar" because the layout of this control bar is defined in a dialog template resource (IDD_VIEW_SELECT).

The View menu allows you to hide or unhide (show) any of the first four of the above controls bars.  The dialog bar is always visible.  The hide/show state of the Tools, Styles, and Palette control bars is immediately reflected in the Hide/Show check boxes in the dialog bar.  You can also hide or show one of the other control bars by toggling its respective check box.

With the Dlg Bar Top command of the View menu, you can rearrange the control bars so that the dialog bar is at the top of the Z-order of the control bars.  When the dialog bar is at the top, it extends along the entire left border of the window except for the menu and title bars; the left ends of the two toolbars butt up against the dialog bar.  When the dialog bar is returned to its original Z-order position (after all of the other control bars), the top of the dialog bar butts up against the lower edge of the second toolbar bar, and the bottom of the dialog bar butts up against the upper edge of the status bar.  This reflects the basic algorithm that control bars are allocated window real estate according to the Z-order, on a first-come-first-serve basis.

The Style menu lets you select one of the four text alignment styles:  Left, Centered, Right, or Justified.  Any selection you make is immediately reflected in the Style Bar in two places:  the combo box, and the corresponding button.  Similarly, you can make a selection either by choosing one of the styles in the combo box of the Style Bar, or by pressing one of the four buttons.  The new selection is immediately reflected in the states of the other controls and in the Style menu.

The Palette menu lets you change the arrangement of the palette from 3x4 to 2x6 arrangement of tools.

When you select a tool from the Palette, the status bar message line shows "You have selected the <type> tool", where <type> indicates which of the 12 tools you selected.  This selection is also reflected in the combo box in the dialog bar.  You can also select a tool using this combo box.

The status bar, in addition to showing the most recently selected tool, also shows the states of three keys:  Insert, Caps Lock, and Num Lock.

Illustration:  Multiple Control Bars

CTRLBARS illustrates that you can have arrange multiple controls bars along the borders of a frame window.  They are allocated space in the frame window according to their Z-order, which initially is the order in which they are created (see CMainFrame::OnCreate).  CTRLBARS changes the Z-order of the dialog bar with the CWnd::SetWindowPos function.  It hides or shows a control bar using CWnd::ShowWindow.  Whenever CTRLBARS changes the Z-order or hides or shows a control bar, it calls CFrameWnd::RecalcLayout afterwards, so that the window real estate is reallocated to the remaining visible control bars.

Illustration:  Custom Toolbar

CTRLBARS illustrates two cases of cusomtizing a toolbar.

The first of the toolbars, the Tool Bar, changes the arrangement of buttons between "Short" (5 buttons) and "Long" (10 buttons).  CTRLBARS calls CToolBar::SetButtonInfo for each button, to map it to a tile position in the toolbar's bitmap, and to map it to a command identification.

The second of the toolbars, the Style Bar, illustrates replacing a toolbar button (or separator) with a control-- a combo box in this example.  CMainFrame::CreateStyleBar creates a toolbar separator that is 100 pixels wide.  It then creates the combo box (IDW_COMBO) as a child of the toolbar, and sets the position of the combo box to take the space it just allocated for the separator.

Illustration:  Custom Status Bar

CMainFrame::OnSelChangePalette illustrates how to explicitly set the text in the message line area of the status bar, by calling CStatusBar::SetPaneText.

CTRLBARS also illustrates how to add custom indicators to the status bar.  The framework automatically updates a Cap Lock, Num Lock, or Scroll Lock indicator, if you specify, for example, ID_INDICATOR_CAPS as one of the identifications passed in the indicators[ ] array to CStatusBar::SetIndicators.  CTRLBARS illustrates extending the standard status bar indicators with the overstrike (OVR) state, which the user toggles with the Insert key.  This requires a message handler for the ID_TOGGLE_INSERT command (mapped to the VK_INSERT key), and a resource string (ID_INDICATOR_OVR) for the text ("OVR") to be displayed when the Overstrike mode is on.  The resource identification ID_INDICATOR_OVR is a pre-defined MFC constant.

Illustration:  Dialog Bar

CTRLBARS illustrates a dialog bar, which is a control bar whose layout is defined by a dialog template resource.  As for any control bars, notifications from controls in the dialog bar are routed to the owner of the dialog bar, namely the main frame window.  For example, CMainFrame::OnSelChangePalette is the handler for the CBN_SELCHANGE notification from the combo box control in dialog bar.  CMainFrame also has handlers for two of the three Hide/Show checkboxes (Styles and Palette).  No handler needs to be written for third checkbox, Hide/Show Toolbar, since the standard handler for ID_VIEW_TOOLBAR is provided by the framework.

Illustration:  Floating Tool Palette

CTRLBARS implements a floating tool palette in a reusable class CPaletteBar, derived from CToolBar.  The derivation from CToolBar provides CPaletteBar with toolbar button behavior.  The palette-specific behavior implemented in CPaletteBar includes:

Floating (WS_POPUP) window style.

Two-dimensional arrangement of the tool buttons into rows and columns:  creation, painting, and button hit testing.

Thin (no text) title bar.

Moveable palette using a tracking rectangle.


CTRLTEST
CTRLTEST Sample

CTRLTEST illustrates several techniques for implementing and using custom controls:

Implementing and using custom controls

Spin control

Bitmap button

Owner drawing  of menus and listboxes of menus and listboxes

Using resource files not maintainable by App Studio

Building the Sample

Follow the standard instructions for building the Microsoft Foundation Class Library samples.

Running the Sample

All of the illustrations in CTRLTEST are initiated via menu commands.  You can try out the commands to see what happens; but to appreciate the purpose of each command, you should read about the various illustrations below.

Illustration:  Implementing and Using Custom Controls

You can implement a custom control from scratch by deriving from CWnd, but it is a lot easier if you can borrow functionality from one of the standard Windows controls by deriving from its control class in the library.  This is what CTRLTEST does to implement a specialized edit control, CParsedEdit.  This edit control accepts only specified sets of characters as user input:  numeric, alphabetic, and/or non-control characters.  CParsedEdit is derived from CEdit.  It has an OnChar message handler to filter the characters.

The implementation of the Simple menu commands in CTRLTEST illustrates three different ways to use a custom control, distinguished according to how the application associates instances of the control in the dialog box with the CParsedEdit class.  Each of the three Simple menu command puts up a dialog box with four instances of the CParsedEdit control.  Data entered in the dialog box is sent to the debug port as TRACE output.  The three Simple menu commands are:

Test C++ Derived Class    The CParsedEdit controls are data members of the dialog class.  The controls are explicitly created, using CParsedEdit::Create, in the dialog's OnInitDialog.  See DERTEST.CPP.

Test WNDCLASS Registered    The CParsedEdit controls are layed out in a dialog template resource (IDD_WNDCLASS_EDIT in RES\CTRLTEST.RC2).  The WNDCLASS name of the CParsedEdit control, "paredit", is specified in the CONTROL statement in the dialog template resource.  The WNDCLASS is registered by the CTRLTEST before the dialog is invoked.  See WCLTEST.CPP.

Test Dynamic Subclassed    The controls are layed out in a dialog template resource (IDD_SUB_EDIT in ctrltest.rc) as standard edit controls.  The controls are declared as CParsedEdit data members in the dialog class.  The dialog's OnInitDialog function calls CParsedEdit::SubclassEdit, which in turn calls CWnd::SubclassWindow, to associate each specific instance of the edit control with the CParsedEdit class.  See SUBTEST.CPP.

Illustration:  Spin Control

Note:

The Spin Control is disabled when this sample is built for Windows NT because MUSCROLL.DLL is not a 32-bit Windows NT DLL.

The CTRLTEST sample includes an implementation of a spin control, in a DLL named MUSCROLL.DLL.  The spin control has a small up-arrow and down-arrow button to allows the user to increment or decrement a value.

The spin control is used in the implementation of the "Spin Control" menu item of CTRLTEST's custom menu.  This command invokes a dialog that has four CParsedEdit controls, each associated with a spin control.  Data entered in the CParsedEdit controls in this dialog is filtered to accept only non-negative integers.  The user can enter numeric data by either typing the value into the CParsedEdit control, or by using the associated spin control.

Illustration:  Bitmap Button

CTRLTEST illustrates various ways to use CBitmapButton in the implementations of the following three menu items in the Custom menu:

Bitmap Button 1    The dialog constructor explicitly loads the bitmap resources for each of the three states (up, down, and focus) of the button by calling CBitmapButton::LoadBitmaps.

Bitmap Button 2    The dialog's OnInitDialog calls CBitmapButton::Autoload to load the bitmap resources based on the following naming convention.  The window text of the control serves as the base resource name, and the letters "U", "D", and "F" are appended to create the names of the resources for each of the three bitmap images for, respectively, up, down, and focus.  For example, the three bitmap resources for the "OK" button are named "OKU", "OKD", and "OKF".

Bitmap Button 3    The dialog is an extension of the second dialog above, making use of a fourth possible button state:  "disabled".  To use this dialog, click the left- or right-arrow bitmap button until the displayed number reaches 1, the lowest number, or 10, the highest number.  When the limit is reached, the button is disabled and a fourth bitmap image is displayed.  The naming convention for bitmap resource for the "disabled" state is an "X" suffix, as is reflected in the resource names "PREVX" and "NEXTX".

Illustration:  Owner Drawing (Menu and Listbox)

Various Windows controls, and also menus, have an "owner draw" feature, that allows the parent, or "owner", window to draw whatever it wants in the client area of the control as opposed to the standard control behavior.  The corresponding control classes, and CMenu class, provide this feature in a more convenient, object-oriented way:  the control or menu class itself handles the drawing.  This is called "self drawing".

CTRLTEST illustrates the general technique of self drawing in implementing the following two commands in the Custom menu:

Custom Menu    This menu item invokes a CColorMenu popup menu, derived from CMenu.  Each sub-menu item displays one of 8 colors using the self drawing feature.  A message box confirms the color you select from the sub-menu.

Custom Listbox    This menu item invokes a dialog that displays a CColorListBox, derived from CListBox.  The listbox has 8 entries, each drawn in one of 8 colors using the self drawing feature.  TRACE output confirms your selection from the listbox.

Illustration:  Using Resource Files Not Maintainable by App Studio

The resource file CTRLTEST\RES\CTRLTEST.RC2 is an example of a resource file not maintainable by App Studio in a human-readble form.  If you were to read CTRLTEST.RC2 into App Studio, and then write it back out, you would lose useful human-readable information, even though the Resource Compiler would still be able to compile the .RC2 file and produce an equivalent binary .RES file.  Thus, RES\CTRLTEST.RC2 has been #include'd in CTRLTEST.RC with a Compile-Time Directive specified with the App Studio File Set Includes command.

There are three categories of human-readable information in CTRLTEST.RC2 that are not maintainable by App Studio:

User-defined control styles symbols.  For example, MSS_VERTICAL is a style defined for the "MicroScroll" spin control.  Although App Studio is able to interpret this symbol as it reads in the .RC2 file, App Studio would write it back out to the .RC2 file as a hexidecimal value.

Standard Windows WS_ or control style symbols used in a control from a standard Windows control-derived class.  For example, two standard edit control styles [image] ES_LEFT and ES_AUTOSCROLL [image] are defined for the "hedit" pen control in the IDD_PENEDIT dialog.  Although App Studio is able to interpret these symbols as it reads in the .RC2 file, App Studio would write it back out to the .RC2 files as hexidecimal value.

Arithmetic in the .RC file.  For example, CTRLTEST.RC2 uses expressions such as "IDC_ALC_FIRST+2" to identify controls in the IDD_PENEDIT dialog.  The symbolic expression would be written back out to the .RC2 file as a single hexidecimal value by App Studio.


Illustration:  Pen Control

Note

Not available when this sample is built for Windows NT.


DIBLOOK
DIBLOOK Sample

The DIBLOOK sample illustrates the use of device-independent bitmaps (DIBs) and the closely related use of color palettes.

DIBLOOK also illustrates a document that has an externally defined file format (in this case, the DIB file format).   This is in contrast to an internally defined file format, that is otherwise implied when the framework automatically calls the document's Serialize function to store the contents of the document on disk.

Secondarily, DIBLOOK further illustrates use of the clipboard, CFile, and scroll views.

Building the Sample

Follow the standard instructions for building the Microsoft Foundation Class Library samples.

Running the Sample

DIBLOOK is an MDI application that allows you to view multiple bitmaps at the same time.  Use File Open to open an existing device-independent bitmap (.DIB) file or device-dependent bitmap (.BMP) file.  If you need some bitmaps, try looking at the .BMP and .DIB files in \MFC\SAMPLES\SPEAKN\RES.

Alternatively, you can create a new bitmap document by copying a bitmap from another application, such as Paintbrush, via the clipboard as follows:

From the other application, copy the bitmap to the clipboard.

Use the DIBLOOK File New command to create a new bitmap document.

Use the Edit Paste command to copy the bitmap from the clipboard into the new document.

Although you cannot edit the image in DIBLOOK, you can save the bitmap to another file by using the File Save As command.  The bitmap will be saved in device-independent bitmap format, even if its original format was device-dependent.

Illustration:  Externally Defined Document Format

DIBLOOK reads and stores bitmaps in the standard Windows device-independent bitmap format.  While in memory, the bitmap is managed by Windows via an opague HDIB handle; the internal format of the bitmap is visible to the application.  Thus, DIBLOOK's document does not itself store the bitmap bits or the color table.  Instead, CDibDoc simply holds a handle to the DIB (HDIB m_hDIB).  DIBLOOK is an example of an application whose document format is defined externally (typically some standard file format standard such as DIB), in contrast to an application whose document format is implicitly defined according to the sequence in which it serializes the document items in the CDocument::Serialize override.

DIBLOOK does not override CDocument::Serialize.  Instead, DIBLOOK overrides CDocument::OnOpenDocument and OnSaveDocument.  Both of these overrides use the pszPathName, passed in by the framework, to open a CFile object and read or save the DIB.  The actual code for reading and saving the DIB file is provided in MYFILE.CPP; this code is reusable by any application that needs to read and save DIB files.

Illustration:  Using DIBs and Color Palettes

DIBLOOK illustrates how to display a DIB in a window, and how to prepare the color palette for the window displaying the DIB.

After DIBLOOK reads the DIB from a file, it prepares a CPalette object based on the color table of the DIB, and stores this as m_palDIB in the CDibDoc object.  When DIBLOOK displays the DIB in its CDibView::OnDraw, it calls a ::PaintDIB routine implemented in DIBLOOK's DIBAPI.CPP.  PaintDIB in turn calls the Windows function ::SetDIBitsToDevice or ::StretchDIBits, using the color table of the DIB as the color palette.  The DIB displaying routines in DIBAPI.CPP are reusable by any application that displays DIBs.

DIBLOOK selects a color palette that is optimal for the window that is currently active. Since DIBLOOK  may display several DIBs in different windows, this means selecting a color palette which is the color table for the DIB displayed in the currently active MDI child window.  When an application is about to receive the input focus (shifting away from another application), its top-level window receives the WM_QUERYNEWPALETTE message.  DIBLOOK's CMainFrame window handles this message by sending an application-defined message, WM_DOREALIZE, to each of the descendent windows, which includes all of the views of the possible multiple opened documents.  In turn, each view selects the palette into its display context as a foreground or background palette, depending on whether the view is the active one or not.

Similarly, if another application changes the system palette, then DIBLOOK receives the WM_PALETTECHANGED message.  In this case, the CMainFrame window again sends the application-defined message, WM_DOREALIZE, to each of the views.  In this case, however, each of the views selects its palette into the display context as a background palette, thus yielding the foreground palette to the other application.

Finally, when the focus shifts within the application from one view to another, DIBLOOK selects and realizes the palette for the now active view (see CDibView::OnActivateView).  When the new palette is realized, Windows sends the WM_PALETTECHANGED message to all application top-level windows, including those of DIBLOOK.  This allows DIBLOOK to realize as a background palette the color tables associated with the other DIBs in the other views.


DLLTRACE
DLLTRACE Sample

The DLLTRACE sample illustrates a DLL version of the TRACER tool.   DLLTRACE was introduced in Microsoft Foundation Class Library version 1.0 to illustrate how to write a DLL that is itself statically linked to the framework library.  This DLL provides a C-based program interface to the Windows application to which it is dynamically linked.  A DLL that is statically linked to the framework library can not successfully export member functions of any classes that are derived from framework classes.

The technique of statically linking a custom DLL to the Microsoft Foundation Class Library is discussed in Technical Note 11.

Building the Sample

Building DLLTRACE, like any DLL that is statically linked to the MFC library, requires different libraries than most of the samples.  These libraries are, specifically, NAFXDW.LIB or LAFXDWD.LIB (model for the MFC library, retail or debug, DLL version).

Running the Sample

Run HELLO1, which is built by the DLLTRACE makefile in the DLLTRACE sample directory.  The HELLO1 window displays "Hello, Windows! (with DLL support)".  Choose ChangeTrace Flags from the Debug menu.  This brings up the same AFX Trace Options dialog box as presented by the TRACER tool.

See TRACER for an explanation of the trace options.

Illustration:  Implementing DLL That is Statically Linked to MFC Library

A custom DLL that is statically linked to the MFC library needs to have a CWinApp-derived class and a single object of that application class, just as does an executable MFC application.   The CWinApp object of the DLL, however, does not have a main message pump, as does the CWinApp object of an application.  If the DLL brings up modeless dialogs, or has a main frame window of its own, the application's main message pump must call a routine exported by the DLL which in turn calls the CWinApp::PreTranslateMessage member function of the DLL's application object.  This is illustrated by the FilterDllMsg function exported by TRACER.DLL.

TRACEAPI.H illustrates that a good way to provide a DLL interface to client applications is to use declare functions with extern "C" and the FAR PASCAL_export.  The use of extern "C" has several advantages.  First, it makes your DLL usable by non-C++ client applications.  Second, it reduces DLL overhead, since C++ name decoration will not be applied to the exported name. Third, it makes it eaiser to explicitly add to a .DEF file (for exporting by ordinal), without having to worry about C++ name decoration.

The use of FAR PASCAL _export generates the correct prologue/epilogue sequence for the DLL entry points, when used in conjunction with the /GD compiler switch.  The FAR keyword allows the client application to be small or medium model.


HELLO
HELLO Sample

The HELLO sample is the classic "Hello World" application.  The MFC version of HELLO was introduced in MFC version 1.0.  HELLO illustrates a single application window with a menu and About box.  HELLO does not make use of the framework's document/view architecture.

HELLO also illustrates using string resource names rather than numeric IDs.  Given that App Studio makes it easy to use more efficient numeric IDs and symbols, HELLO's approach of using string names is not recommended.

Building the Sample

Follow the standard instructions for building the Microsoft Foundation Class Library samples.

Running the Sample

When you run HELLO, it displays "Hello, Windows!", centered in the application window.

Use the Help About command, or F1, to see the About box.

Illustration:  Single Application Window, No Views, No Document

Just as any application written using the Microsoft Foundation Class LIbrary, HELLO has a CWinApp-derived class.  This application class provides a minimal implementation of InitInstance, which is to construct a frame window object (of the application-specific class CMainWindow), and then call the window's ShowWindow and UpdateWindow.

HELLO displays "Hello, Windows!" in response to the WM_PAINT message, by specifying a message map entry, ON_WM_PAINT, for CMainWindow, and by implementing the OnPaint handler.


HELLOAPP
HELLOAPP Sample

HELLOAPP is the minimal Microsoft Foundation Class Library sample, which serves to illustrate how few lines of code are required to simply get a window up on the screen.  HELLOAPP is simpler even than the HELLO sample:  HELLOAPP does not paint anything in the main window's client area; nor does it even have a message map for the main window.

HELLOAPP is nevertheless instructive, in that it demonstrates the minimal overhead that is required for a content-less application, as opposed to, for example, a WinMain type of application developed using the Windows SDK.

Building the Sample

Follow the standard instructions for building the Microsoft Foundation Class Library samples.

Running the Sample

When you run HELLOAPP, it displays "Hello World!" in the title bar of an empty application window.

Illustration:  Minimal Application

Just as any application written using the Microsoft Foundation Class Library, HELLOAPP has a CWinApp-derived class.  This application class provides a minimal implementation of InitInstance, which is to construct a frame window object (of the application-specific class CMainWindow), and then call the window's ShowWindow and UpdateWindow.


HIERSVR
HIERSVR Sample

The HIERSVR sample is an example of a full OLE server, which supports linked objects as well as embedded objects.  In addition, as a full OLE server, this application also can directly open and save files. The HIERSVR object is a multiple-level hierarchy diagram, where each node in the hierarchy consists of text surrounded by a rectangle or other shapes.

See MINSVR for an example of a minimum OLE server, which supports only embedded objects, and which does not directly open and save files.  See  OCLIENT for an example of an OLE client application.

In addition to illustrating OLE server functionality, HIERSVR also illustrates the following:  registration of document type with the Window File Manager, and copying to the clipboard.

Building the Sample

Follow the standard instructions for building the Microsoft Foundation Class Library samples.

Running the Sample

You must run HIERSVR as a stand-alone application once in order to register its OLE type with the system.

The type of document or object HIERSVR edits and displays is a single inheritance hierarchy diagram.  Each node in the diagram, except the root node, has only one parent node.  Each parent may have multiple children.  A company's organization chart is an example of a hierarchy diagram.  So is the list of the Microsoft Foundation Classes, since they do not use C++ multiple inheritance.  In fact, we include MFCCLASS.HIE as an example HIERSVR document.

Every node in the hierarchy has a minimal set of attributes:

Description    text consisting of up to 30 characters.

Shape    style of rectangle that surrounds the text rectangle, rounded rectangle, or oval rectangle.

Item Key Link (optional)    name used to refer to a linked item.  If not specified, the item key link defaults to the description string.  This name is visible when you view the link using the Edit Links command in the client application.

A new HIERSVR diagram begins as a single node with the text "Root node".  To add a node, first select its parent node by clicking it.  Then use the Add Node command in the Edit menu.  In the Add Node dialog, specify the three attributes described above.  To change the attributes of a node, select it with a mouse click, and then use the Change Node command.  This simple application does not support deleting a node, or reorganizing the hierarchy.

HIERSVR will import hierarchy information from a text file formatted as follows.  The text in each line (delimited by a line feed) is the node's Description.  The number of tab characters preceding the text determines the level of the node in the hierarchy.  In the HIERSVR sample directory, MFCCLASS.TXT is the text import file for MFCCLASS.HIE, the native HIERSVR file.

To link a hierarchy diagram to a client document, you must first save the file in HIERSVR.  Then select the node you want to copy using Edit Copy.  This will copy the link to the clipboard.  The text of the selected node will also be copied to the clipboard in the CF_TEXT format; and the entire hierarchy of nodes will be copied in a HIERSVR-native clipboard format.  Note, saving the document is required since the link format requires a document name.  Finally, in the client application, use the Edit Paste Link command (or select Paste Link from Edit Paste Special).  The link will be displayed in the client document as the node that you selected before doing the Edit Copy.  The rectangle will also be displayed.

To embed a hierarchy diagram in a client document, you can either use a clipboard procedure similar to that above for linking the object, or use the Insert New Object command in the client application.  If you choose the clipboard procedure, use Edit Paste rather than Edit Paste Link in the client application.  Only the sub-hierarchy starting at the selected node will be embedded in the client document.

Whether you link or embed the diagram, only the top selected node will be displayed in the client application window.  To see the rest of the diagram, you will need to launch HIERSVR from the client application by double-clicking the item.

Illustration:  Full OLE Server

HIERSVR illustrates the class derivations necessary to implement a fully functional OLE server application, and illustrates some of the most common OLE client application user interfaces that require additional code.

The three framework classes used to implement an OLE server application are illustrated by:

A COleTempateServerobject, stored as member variable m_server in HIERSVR's application class.

HIERSVR's own CServerDoc class, derived from COleServerDoc.

HIERSVR's own CServerItem class, derived from COleServerItem.


MAKEHM
MAKEHM Tool

MAKEHM is a console tool which produces a mapping between resource identifications and help contexts.  We provide the sources for MAKEHM to serve as an illustration of a console application that uses the Microsoft Foundation Class Library, and to enable you to modify the tool if desired.  The MAKEHM executable is installed by the Visual C++ setup program in the \MSVCNT\BIN directory; so it is not necessary for you to build it from the MAKEHM sample directory in order to run it.

The purpose and use of the MAKEHM tool is described in Chapter 10 of the Class Library User's Guide.  For additional information on the framework's context sensitive help support, see Technical Note 28.

Building the Tool

MAKEHM is a console application, and so building it requires the console version of the Microsoft Foundation Class Library (NAFXCRD.LIB).

For instructions in building the console version of the MFC library, see Appendix B of the Class Library User's Guide.

Running the Tool

Normally, you do not need to run MAKEHM directly.  Rather, you run the MAKEHELP.BAT file produced by AppWizard, which in turn runs MAKEHM.

If you find occasion to run MAKEHM directly, the command line syntax is:

makehm <from>,<to>,<add> [<from>,<to>,<add> [...]] <resource.h> >>[output.hm]

<from>     Specifies the symbol prefix to be read, such as a command i.d.

<to>     Specifies the symbol prefix of the help context identification to be produced in the .HM file.

<add>    The help ID base number to be added to the value of the <from> identification to produce the help context number.

You may specify one or more sets of <from>,<to>,<add> in the command line.

<resource.h>    The header file that #define's the symbols to be read.

<output.hm>    The .HM file to be produced by MAKEHM.

Look at a MAKEHELP.BAT file produced by AppWizard, to learn what command line values you should use.


MDI
MDI Sample

The MDI sample illustrates using the framework's multiple document interface (MDI) support without using the framework's support for documents and views.  This sample was introduced in Microsoft Foundation Class Library version 1.0.  It has been updated to take advantage of MFC version 2.0 built-in MDI command support and command architecture.  This sample, however, does not take advantage of the document/view architecture in MFC version 2.0.

The MDI sample also illustrates: Windows timers; CColorDialog; CBitmap; and changing the default cursor of a window.

Building the Sample

Follow the standard instructions for building the Microsoft Foundation Class Library samples.

Running the Sample

This sample application illustrates a multiple document interface with two distinct types of MDI child windows:  (1) a Bounce window, in which a ball bounces around, and (2) a Hello window, which simply displays the text "Hello, World!".

Choose the New Bounce or New Hello command of the File menu to create a new MDI child window.  You can create multiple instances of each type of window.

Both MDI children windows determine what menus are shown when they are active.  Both windows have a Color menu.  When you choose a color from this menu, the color of the bouncing ball, or of the Hello text, is updated.  Choose the Custom item to invoke a color dialog, from which you can select a special color.

The Bounce window also has a Speed menu, where you can select a Slow or Fast speed at which the ball moves around the screen.

If you minimize the Bounce window, notice that there isn't a static icon; rather, there is a small ball bouncing around in the icon.  In contrast, the Hello window has a normal icon.

Illustration:  MDI Without Documents and Views

Unlike an MDI application produced by AppWizard, this sample application does not use the framework's support for documents and views.  Thus, it does not use document templates; there is no AddDocTemplate call in the application's InitInstance.

This application nevertheless takes full advantage of the framework's MDI support.  CMainFrame is derived from CMDIFrameWnd; and CBounceWnd and CHelloWnd are derived from CMDIChildWnd.  Commands from the "Window" menu, such as Tile, are handled by the framework's default implementation in CMDIFrameWnd.

Note, although CBounceWnd and CHelloWnd both override Create, this is not necessary to take advantage of the framework's MDI support.  The override of Create is intended to illustrate how to change the default cursor and icon of a window.  This requires registering a new WNDCLASS, by calling AfxRegisterWndClass, and passing the name of the WNDLCASS in the call to Create.


MINSVR
MINSVR Sample

The MINSVR sample is an example of a minimum OLE server, which supports only embedded objects, not linked objects.  Also, as a minimum OLE server, this application only edits embedded objects on behalf of an OLE client; MINSVR does not directly open or save files.  The MINSVR object is simply a string, which is drawn as text centered in a shaded ellipse.

See HIERSVR for an example of a full featured OLE server.

Building the Sample

Follow the standard instructions for building the Microsoft Foundation Class Library  samples.

Running the Sample

To use this simple OLE server with any OLE client application, you must run MINSVR once directly from the Program Manager or File Manager to register it as an OLE server in the registration database.  This is the only time MINSVR is intended to be run directly.

Try MINSVR out with your favorite OLE client application.  Windows Write is an example of an OLE client application.  You can change the size of the MINSVR-drawn ellipse inside the Write document by using the Edit Size Picture command in Write.

1.	Choose the Insert Object command from Write's Edit menu.

2.	From the list of OLE servers, select "Mini OLE Server".  The MINSVR window appears.

3.	From MINSVR's Edit menu, select "Change".  Replace the initial "example string" with some short text.  The ellipse and text is immediately drawn in the Write window.

Usually, an OLE server does not update the client until the user chooses the File Update command.  In this simple illustration, however, MINSVR updates the client as soon as you change the text via the Edit Change command.


MULTIPAD
MULTIPAD Sample

MULTIPAD, a simple text edit, is essentially an MDI version of the Windows NOTEPAD application.  MULTIPAD allows the user to open and edit multiple text files.  Microsoft Foundation Class Library version 1.0 adapted and simplified the Windows SDK MULTIPAD, taking advantage of MDI support in the library.  MFC version 2.0 further simplifies MULTIPAD by taking advantage of several new framework features, including toolbar, status bar, printing, and the CEditView class.  See also DLLHUSK for a simple illustration of deriving from CEditView, and  SUPERPAD for a full illustration of CEditView's features.

Building the Sample

Follow the standard instructions for building the Microsoft Foundation Class Library samples.

Running the Sample

You can use MULTIPAD to view and edit multiple text files at a time.  The user interface is standard for text editors and so needs not be described here. The discussion of CEditView below lists the text file editing and viewing commands that MULTIPAD offers.

Illustration:  CEditView

The CEditView class uses a Windows edit control to hold the entire text document in memory while the user edits the contents of the document.  CEditView signficantly extends the functionality of the edit control by handling the Edit menu Cut, Copy, Paste, Clear, Select All, Find, Replace, Repeat, and Undo commands, and the File Print command.

MULTIPAD does not need a CMDIChildWnd-derived class for the frame window; nor does MULTIPAD need to derive from CEditView.  Serialization of the text file consists of one line of code:  the document object delegates serialization of the text file to the CEditView object.


OCLIENT
OCLIENT Sample

The OCLIENT sample provides a simple illustration of OLE client support.   You will probably start developing your OLE client application using AppWizard's OLE Client option.  OCLIENT implements common user interfaces such as Insert New Object, Edit Paste, and Edit Paste Link, not provided directly by the Microsoft Foundation Class Library.  You can borrow these implementations from OCLIENT to help complete your AppWizard-created application.

Building the Sample

Follow the standard instructions for building the Microsoft Foundation Class Library samples.

Running the Sample

OCLIENT is a simple object drawing program, where the only type of object it draws is a linked or embedded OLE item.

You can add a new object to the OCLIENT drawing in either of the following ways:

Choose Insert New Object from the Edit menu.  From the Insert New Object dialog, select the type of OLE item you want to add.  The OLE server for that OLE item type will be launched.  Edit the OLE item in the server.  Then exit the server, or use the File Update command in the OLE server.

Or, while running an OLE server, copy an OLE item to the clipboard.  Then from the Edit menu in OCLIENT, use Paste to embed the OLE item or Paste Link to link the OLE item.

The newly added OLE item is always placed in the top, left corner of the OCLIENT drawing.  The new OLE item might partially or completely cover an older item.  You can select one OLE item at a time using the mouse; selected items are indicated with inverse video.  You can move an OLE item by dragging it.  You can resize an OLE item by first selecting it and then dragging the lower left corner.

To delete an OLE item, select it with a mouse click; then hit the Del key, or use the Edit Clear menu command.

To edit the contents of an OLE item, double click it with the mouse; or select it with the mouse, and then use the Edit <type> Object command from the Edit menu.  This will launch the server.  Some OLE servers may have additional verbs on the menu.  When you are done editing the OLE item in the server, exit the server, or use the server's File Update command.

Illustration:  OLE Client

OCLIENT illustrates the class derivations necessary to implement an OLE client application, and illustrates some of the most common OLE client application user interfaces that require additional code.  The structure of OCLIENT is similar to a new application created using the AppWizard OLE Client option.

The two class deriviations necessary to implement an OLE client application are illustrated by  OCLIENT.  The document class, CMainDoc, is derived from COleClientDoc.  The CRectItem class, representing an OLE item in the OCLIENT drawing, is derived from COleClientItem.  The only information about the embedded or linked item that OCLIENT is responsible for maintaining is the position and size of the item in the drawing.

OCLIENT illustrates the following common OLE client application user interfaces:

Insert New Object command (Edit menu).

Edit Paste and Paste Link.

The Edit Links command and Edit <verb> <type> Object commands and menu initialization are handled completely by the framework.

A portion of OCLIENT's user interface is highly specific to an object drawing type of application.  Nevertheless, the implementation of these user interfaces illustrates use of various member functions such as COleClientDoc::GetStartPosition and GetNextItem, and COleClientItem::IsVisible.  The application-specific user interfaces are:

Mouse hit detection.

Tracking of the object as the user drags or resizes it.


SCRIBBLE
SCRIBBLE Sample

SCRIBBLE is the tutorial sample application discussed in the first ten chapters of the Class Library User's Guide.  The SCRIBBLE sample directory has seven subdirectories corresponding to different steps discussed in the tutorial.  All of these subdirectories contain the complete sources for a given step, except the SCRIBBLE\STEP6 subdirectory.

SCRIBBLE provides simple illustrations across a wide breadth of framework features.  The Class Library User's Guide and SCRIBBLE provide the best introduction to the framework features listed below:

Application object

Documents, views, and document templates

Commands, message maps, command user interface updating

MDI frame and children windows

Toolbars and status bars

Update hints from documents to views

Dialogs, data exchange and validation

Scroll view

Splitter window

Printing and print preview

Context-sensitive help

Refer to other samples for illustrations of advanced use of the above features, and for illustrations of many other features not covered in the tutorial.


SPEAKN
SPEAKN Sample

The SPEAKN sample brings together graphics output, sound output, and handwriting recognition.  This highlights the Multimedia functions.

SPEAKN illustrates the following programming techniques:

Implementing sound output, using the MultiMedia APIs defined in the Windows SDK header file MMSYSTEM.H.

Using user-defined resources.  SPEAKN uses them for storing MultiMedia data:  sounds and bitmaps.  See Technical Note 35 for a discussion on maintaining user-defined resources in a separate .RC file not maintained directly by App Studio.

Using bitmap buttons. (CTRLTEST provides a more exhausitve illustration of using CBitmapButton.)

Implementing an application user interface which consists of a single dialog box.  (TRACER provides an even simplier illustration of this.)

Building the Sample

Follow the standard instructions for building the Microsoft Foundation Class Library samples.

Running the Sample

A sound card is required if you want to hear the sound output; but the application can still be run without a sound card.

When you first run SPEAKN, it plays a "welcome" sound, and displays a "What is this?" dialog.  When the sound play completes, SPEAKN displays the first of a series of images-- a picture of a dog.  Enter "dog" into the edit box, using your pen, or mouse if you are using the pen simulator, or the keyboard if you have neither Windows for Pen nor the simulator.  When you enter the correct word, SPEAKN rewards you with a sound and moves on to the next image.

The happy face bitmap initially has no smile or frown.  If the first character you type in is correct, the face turns to a smile; if wrong, the face turns to a frown.


SUPERPAD
SUPERPAD Sample

The SUPERPAD sample fully illustrates the CEditView class.  MULTIPAD provides a very simple illustration of using CEditView.  SUPERPAD, in contrast, illustrates advanced uses of CEditView, though class deriviation, including toggling the word wrap state of the edit control and changing the screen and printer font.

Secondly, SUPERPAD illustrates a wide variety of MFC programming techniques:

About dialog showing system resource usage.

Splash window that is displayed when the application first starts.

Persistent window placement, by storing window position information in an private .INI file.

Idle loop processing.

Using a wait cursor.

Subclassing a window.

Adding page headers and footers during printing.

Doing page breaks during printing.

Starting print preview at the current selection in the document.

Returning from print preview to the same position in the document as last previewed.

Standard font dialog (CFontDialog).

Building the Sample

Follow the standard instructions for building the Microsoft Foundation Class Library samples.

Running the Sample

When you first run SUPERPAD, it displays a "splash window" which looks like an About box.  It stays on the screen for a short while then vanishes after a time-out.  You can also close the splash window by pressing any key or by clicking the mouse.

SUPERPAD remembers its window position from the previous time you ran it.  It also remembers whether the document window was maximixed in the MDI frame window.

The File menu offers standard commands:  New, Open, Close, Save, Save As, Print, Print Preview, Print Setup, the most recently used (MRU) file list, and Exit.

The File menu also offers a Page Setup option where you can specify a per-page header and/or footer.  Leave the header or footer blank if you want none.  You can specify any text in the header and footer.  You can also specify any of the following formatting codes:

&f   for the file name

&p  for the page number

any of the formatting codes defined for the C run-time strftime function; for example, %a for the abbreviated weekday name; %B for the full month name; %d for the day of the month; and %Y for the year with century.  Note, these formatting options are not available if you link SUPERPAD to the DLL version of MFC, because strftime is not available in a DLL.

Like the simple MULTIPAD sample, SUPERPAD offers the following Edit menu commands, which are handled by default by CEditView:  Cut, Copy, Page, Delete, Find. Find Next, Replace, Select All, and Undo.  The Edit menu also offers a Word Wrap command to turn word wrapping on or off.

The View menu also offers the following commands, which exercise various features of CEditView:

Set Tab Stops    Enter a single integer in the dialog box for equally spaced tab stops.

Set Font     Specify the font to be used when displaying the file on the screen.

Set Printer Font    Specify the font to be used when printing.

Mirror Display Font     Turn this toggle state on if you want to temporarily deselect the currently specified printer font and instead use a printer font that most closely matches the screen font.

Illustration:  CEditView

SUPERPAD derives its view class CPadView from CEditView.  CPadView accesses the various attributes and operations of CEditView to add to the functionality of CEditView, as described here.

CPadView calls CEditView::SetFont and SetPrinterFont to initialize and change the screen and printer fonts.

To implement the Edit Word Wrap command, CPadView toggles the state of word wrapping by creating a new edit control (whose WNDCLASS is the standard Windows "edit" control).  It toggles the ES_AUTOHSCROLL and WS_HSCROLL styles of the control, which together determine whether an edit control does word wrapping.  CPadView saves the buffer of the old edit control, and moves it into the new edit control.  Finally, it destroys the old edit control, and then associates the hWnd of the new edit control with the CPadView class by calling CWnd::SubclassWindow.

Illustration:  Printing and Print Preview

CPadView overrides OnPrint in order to add page headers and footers.  It overrides OnBeginPrinting to set the current time that is optionally displayed in the header and/or footer, and to start print preview at the current selection in the edit control.

CPadView overrides CView::OnScrollTo to scroll the view to the same position as last viewed during print preview.


TEMPLDEF
TEMPLDEF Tool

The TEMPLDEF tool is a C++ template class expander.  TEMPLDEF uses a syntax similar to the proposed ANSI C++ language syntax.  The TEMPLDEF tool expands a template file into sources for a user-specified class_name, which then can be used as an alternative to:

template_class<type_specifier> class_name

You can model your template classes after the source files for four collection types provided in the TEMPLDEF sample directory:  (1) arrays, (2) lists, (3) maps from keys to values, and (4) maps from strings to values.

In addition to being a useful tool, the source code provided for TEMPLDEF serves as an example of a console based application written using the Microsoft Foundation Classes.

Building the Tool

TEMPLDEF is a console application, and so building it requires the console version of the Microsoft Foundation Class Library (NAFXCRD.LIB).

For instructions in building the console version of the MFC library, see Appendix B of the Class Library User's Guide.

Running the TEMPLDEF Tool

To get a quick look at how the TEMPLDEF tool works, run MKCOLL.BAT from the TEMPLDEF sample directory.  You do not need to build the TEMPLDEF.EXE itself, since it is already provided in the \MSVCNT\BIN directory.

MKCOLL.BAT reproduces the sources for all of the Foundation collection classes, whose sources and headers are included in the MFC\SRC and MFC\INCLUDE directories.  For example, one of the source files produced by MKCOLL.BAT is ARRAY_B.CPP, which is the implementation for the CByteArray class.  This file is exactly the same as the ARRAY_B.CPP file in MFC\SRC.

The TEMPLDEF command lines in MKCOLL.BAT provide a model for how to run TEMPLDEF to produce additional type-specific collection classes, as explained in the next section.   The collection template source files (ARRAY.CTT, LIST.CTT, MAP.CTT and MAP_S.CTT) provide models for how to develop your own template classes.

Producing Additional Type-Specific Collection Classes

The TEMPLDEF sample directory provides sources for four types of collections:

ARRAY.CTT is the template for the array collection shape;

LIST.CTT is the template for the list collection shape;

MAP.CTT is the template for the collection shape that maps keys of a specified type to values of a specified type; and

MAP_S.CTT is the template for the collection shape that maps keys of specifically a CString type to values of some specified type.

The command line syntax for running TEMPLDEF to produce a type-specific collection is illustrated by the following example from MKCOLL.BAT:

templdef "CArray<BYTE,BYTE,1,0> CByteArray" array.ctt temp.h temp.inl array_b.cpp

"CArray" is the template name, as would be specified in the C++ syntax for the template class.

The first template argument (BYTE) is the data type, such as used for the return type of CByteArray::GetAt

BYTE GetAt(int nIndex) const;

The second template argument (BYTE) is the data type, when referred to as an argument to a member function of the template class, as in:

void SetAt(int nIndex, BYTE newElement);

The third template argument (1) sets the value for IS_SERIAL, which determines whether the template class is declared with the DECLARE_SERIAL macro and has a Serialize member function.

The fourth template argument (0) sets the value for HAS_CREATE, which determines whether the template class has additional ConstructElement and DestructElement member functions that are optimized for a particular element type.  The library provides such optimization only for the CString type.  So, you should set this argument to 1 only if the element type is CString.

"CByteArray" is the name of the expanded template class produced by TEMPLDEF.

"array.ctt" is the source file for the class template.

"temp.h" is the header file produced for the  expanded template class.

"temp.inl" is the inline file produced for the template class.

"array_b.cpp" is the implementation file produced for the expanded template class.

Note  MKCOLL.BAT concatenates the header and inline files for all of the Foundation collection classes.  The resulting NEWCOLL.H and NEWCOLL.INL files are the same as the AFXCOLL.H and AFXCOLL.INL files in MFC\INCLUDE.   It is not necessary, nor advised, that you append your own additional collection classes to AFXCOLL.H and AFXCOLL.INL.


TRACER
TRACER Tool

TRACER is a Windows-hosted tool which allows you to set the trace flags in AFX.INI.  These trace flags determine what category of TRACE messages are sent from the debug version of an MFC application to the debugging window or console.  For an explanation of the trace options, see Technical Note 7.  It is not necessary for you to build the TRACER.EXE, since it is already provided in \MSVCNT\BIN.

In addition to serving as a useful debugging tool, TRACER's sources illustrate:  implementing a Windows application whose user interface is simply a dialog, and dialog data exchange.

Building the Sample

Follow the standard instructions for building the Microsoft Foundation Class Library samples.

Running the TRACER Tool

The TRACER dialog box offers 6 trace options.  The first option, "Enable Tracing", turns tracing on or off altogether.  The other 5 options let you select which types of trace messages will be sent to the debugging window or console.


VIEWEX
VIEWEX Sample

The VIEWEX illustrates:

A static splitter window, where the order and number of panes never changes, and the panes are usually of different view classes.

A form view (CFormView) that prints, and that stays synchronized with other views on the same document.

Dialog data exchange (DDX) in general, and specifically dialog data exchange of radio group button data.

Building the Sample

Follow the standard instructions for building the Microsoft Foundation Class Library samples.

Running the Sample

The document in VIEWEX is very simple.  Its data consists of a string, and a color that the text of the string is displayed in when viewed.

When you first run VIEWEX, it presents a "New" dialog box where you select which type of document window is to be illustrated:

Simple Text    Displays the string, using the current color, centered in the window.

Input Form View    Provides a form (a CFormView) in which you can change the string in an edit control, and change the color by selecting from a radio button group.

Splitter Frame with both    Displays both of the above views (Simple Text, and Input Form) in two side-by-side panes of a splitter window.  When you change the string (character-by-character) or color in the Input Form, the Simple Text view automatically reflects the change.

Three-way Splitter Frame    Displays the Input Form view in one splitter window pane.  The other pane is itself divided by a splitter bar:  the upper sub-pane displays a Simple Text view, and the lower sub-pane displays a Color View.  The Color View simply paints itself entirely in the current color.

You can change the string not only by using the edit control in the Input Form but also by choosing the Change Data command in the Edit menu.

You can view multiple documents at a time.  For sake of simplicity, however, you cannot save or reopen documents, nor can you view the same document in more than one of the above windows.

Illustration:  Static Splitter Window

In VIEWEX, the MDI child window creates a 1x2 splitter window within its client area, by overriding OnCreateClient.  In the case of the three-way splitter, VIEWEX embeds a second 2x1 splitter window within the right-side pane of the 1x2 splitter window.

VIEWEX calls CSplitterWnd::CreateStatic instead of CSplitterWnd::Create, in order to create static splitter windows instead of dynamic splitter windows.  Each pane of VIEWEX's splitter window has a different view class; VIEWEX calls CSplitterWnd::CreateView to specify the CView-derived class for each pane.   In the case of the first pane, VIEWEX uses the view class specific in the document template object, which is passed to OnCreateClient in the m_pNewViewClass member of the CCreateContext.  In the case of other panes, VIEWEX specifies the RUNTIME_CLASS of the view.

Illustration:  Form View

VIEWEX's CInputView illustrates printing in a CFormView-derived class.  See the large comment block in INPUTVW.CPP, immediately above the implementation of CInputView::OnPrint.

CInputView also illustrates synchronizing a form view with other views, so that when the user enters data one of the fields, the change is immediately reflect in other views.  CInputView accomplishes this by mapping ON_EN_CHANGE and ON_BLICKED for all of its controls to a central OnDataChange message handler.  OnDataChange calls CView::UpdateData to transfer data from the screen to the member variables of CInputView and then calls the document's UpdateAllViews to inform the other views about the change.

Illustration:  Dialog Data Exchange (DDX)

VIEWEX's CInputView illustrated dialog data exchange (DDX) in general, and specifically dialog data exchange of radio group button data.   If you ClassWizard to view the member variables of CInputView, or if you look at the CInputView::DoDataExchange written by ClassWizard in INPUTVW.H, you will notice that only the first button in the radio group is mapped to the member variable m_iColor.  This m_iColor is a 0-based ordinal value (int) representing which radio button is selected.


VBCHART
VBCHART Sample

Note:

VBX controls, and the VBCIRCLE and VBCHART samples are not supported in Visual C++ for Windows NT.

The Visual C++ 1.0 product for Windows 3.1 supports the use of VBX custom controls.  VC++ 1.0 for NT does not support VBX controls.  This includes both the App Studio resource editor as well as runtime support in the MFC classes (CVBControl).  The VBX API is inherently a 16-bit API packaged as 16-bit DLLs.  32-bit NT applications cannot directly call 16-bit DLLs, so calling a VBX from a 32-bit application is difficult at best.  Complicating the matter, is the fact that the VBX API takes advantage of Intel segmentation to a great degree, using compiler extensions such as based pointers.  This design (especially based pointers) does not mix well with the 32-bit flat address space of NT applications.  If an application is dependent on VBX custom controls, it should be built as a 16-bit Windows application and run under NT's WOW (Windows on Windows) layer.


VBCIRCLE
VBCIRCLE Sample

Note:

VBX controls, and the VBCIRCLE and VBCHART samples are not supported in Visual C++ for Windows NT.

The Visual C++ 1.0 product for Windows 3.1 supports the use of VBX custom controls.  VC++ 1.0 for NT does not support VBX controls.  This includes both the App Studio resource editor as well as runtime support in the MFC classes (CVBControl).  The VBX API is inherently a 16-bit API packaged as 16-bit DLLs.  32-bit NT applications cannot directly call 16-bit DLLs, so calling a VBX from a 32-bit application is difficult at best.  Complicating the matter, is the fact that the VBX API takes advantage of Intel segmentation to a great degree, using compiler extensions such as based pointers.  This design (especially based pointers) does not mix well with the 32-bit flat address space of NT applications.  If an application is dependent on VBX custom controls, it should be built as a 16-bit Windows application and run under NT's WOW (Windows on Windows) layer.


DLLHUSK
DLLHUSK Sample

Note:

The DLL version of the Microsoft Foundation Class Library and the DLLHUSK sample are not supported in Visual C++ 1.0 for Windows NT.

The MFC 2.0 product for Windows 3.1 supports a single shared DLL version of the classes called MFC200[D].DLL (or the _AFXDLL variant).  DLLs on Windows NT are significantly different than DLLs on Windows 3.1.  As such, this shared DLL is not available with Visual C++ 1.0 for NT.  DLL writers can continue to use the _USRDLL variant, where a copy of the MFC implementation is included with the DLL.  Applications which used MFC200.DLL can simply be recompiled to use the static link library, NAFXCW[D].LIB, instead.


Using Search Plus

Search Plus provides a way to search the full text of help files. You can search for a single word, a combination of words in a topic, one word near another word, an exact phrase, and so on.

  To search for a word or phrase:

1.	If the help file is not already open, open it using WINHLP32.

2.	Click Search Plus on the button bar.

3.	Enter the word or words that you want to find in the Search dialog box.

If you want to enter groups of words, or exclude words, and so on, click the Hints button. This displays the Search Hints dialog box. It describes the use of keywords to combine words, the use of quoting and grouping operators, and the use of a wildcard for expanding a root word.

You can also set the range used for the keyword NEAR. It determines how many other words can separate two words for which you are searching.

4.	In the Look At group box, select either the Topic Titles Only or the All Text option button.

5.	In the Look In group box, select the help files in which you want to search for the desired topic.

6.	Click the Search button.

The titles of topics found are displayed in the Topics Found list.

7.	Double-click the desired topic in the Topics Found list. Each entry in the topic displayed is highlighted.

Topics in the current help file have no label before the topic title. Topics in other help files in the group are preceded by a label. These labels change as you switch from one help file to another.

You can also use the Go To, Next and Previous buttons to display topics.

Tips and Troubleshooting

Using Search Keywords

The keywords AND, OR, and NOT operate only on a topic level. The following Search For string finds any topic that contains both words:

menu AND command

The order of words in the Search For string does not matter. The following Search For strings produce identical results:

menu AND command

and

command AND menu

The search mechanism ignores letter case. The same results appear if you search for cobject or COBJECT.

You cannot search for the Search keywords, such as NOT, for instance.

Exclusion from Searches

You can search for alphanumeric characters only. Characters such as ~ [tilde], # [number sign], \ [backslash] and ( [left parenthesis] are excluded from the search.

Some words are excluded from the full-text search capability in order to build a smaller search index file. The excluded words are not usually helpful for finding information in this kind of material, such as "because," for instance.

This exclusion has a side-effect with the NEAR keyword, because excluded words are essentially invisible to the search mechanism, even though they are visible to you on the topic page. For instance, if you set NEAR to 1 and search for:

menus NEAR commands

the search would find "commands because the menus" in the sentence "It may not display all the listed commands because the menus are dynamic," since both "because" and "the" are excluded from the search index.

Narrowing Your Search

If you find a very large number of topics with your search, you can narrow your search in four ways:

Exclude help files in the Look In group from the search list by clearing the check box for the help file.

Use the keywords (AND, OR and NOT) and the grouping operators listed in the Search Hints dialog box to create likely combinations of words.

Use the "" quoting operators to search for an exact phrase.

Use the NEAR keyword with combinations of words to find only those that are close together in a topic.

Recovering from Errors

If you get an error message that refers to an old or missing index file, one of two things may have happened:

The .IND index file may have accidentally been deleted or moved to a directory other than that containing the help files. In this case, reinstall the help files using Setup.

The VIEWER.INI file may have been deleted or corrupted. In this case, simply close the help file, open it again and try again.

If you get an error message that refers to a title setup problem, when you click the OK button, the Help file will close. In this case, open the help file again and continue.