(Base One logo) .NET database and distributed computing tools

BFC | Visual Studio | Database Technology | Distributed Computing | Utility Classes

BFC's Screen and Application Library Classes
Extending MFC (Microsoft Foundation Classes)

Contents


Screen Library Classes

The Screen Library (B1SLib) provides a complete set of state-of-the-art screen controls, such as table (grid) controls, tab controls, hierarchical list boxes, enhanced status bar, 3-D and mask edit controls, etc., which are designed to be easily connected to the database classes. Most controls are built using MFC and the Win32 common controls.

BFC is a large, integrated class library, broken down into subsystems that can be understood separately. A standard BFC application uses four basic low level libraries as underpinnings: the Utility, Database, Screen and Application libraries (derived in that order).

The Screen library sits on top of the Database Library and depends on it because, for example, of the built-in Screen Dictionary records and mask edit controls that know about data dictionary information. The Screen library includes the Database and Utility header files, but has no knowledge of any other BFC subsystem but the BFC Resource DLL (B1RDLL).

The Screen library is responsible for the basic look and feel of a typical BFC application. Programmers are free to alter the way their applications behave.

The Screen library is constructed on top of a combination of Windows and MFC (Microsoft Foundation Classes) libraries and the BFC Utility and Database libraries. Application programmers can achieve completely different looks and feels by intermixing direct use of the libraries underlying the Screen library and deriving from BFC screen classes.

The Screen library includes a wide variety of enhanced screen controls which can be used for building forms and dialogs with large scale scrollable tables (grids), combos, and tree controls (hierarchical list boxes). Sophisticated base classes for creating data aware edit controls, calendars, spin controls, 3D static text controls and bitmap buttons greatly simplify programming of commercial quality screens.

Some of the major screen control classes include:

clsTblScrlBase (scrollable table base class)
clsCmbScrlBase (scrollable combo base class)
clsTreeCtrlHierBase (hierarchical tree control base class)
clsEdBase (edit base class)
clsSpinCtrl (spin control class)
clsBitmapBtn (bitmap button class)
clsStaticPlus (static plus control class)
clsCalendar (calendar class)
clsWndNavBar (navigator (scroll) bar window class)
clsWndPopup (popup window (tool tip) class)

BFC Screen Control Classes Hierarchy Chart

BFC Screen Control Classes Hierarchy Chart

Besides screen controls, the Screen library includes basic application building classes such as:

  • clsScrMgr (Screen Manager class)
    - For simplified launching of complex forms and dialogs, for providing easy access to the status bar, the user's log, if any, and shared resources such as pens, brushes & fonts, and handling abnormal termination for all severe errors.

  • clsWndMainFrameBase (Main Frame Window Base class)
    - For controlling security access to menu items and popup menus, forcible log off & message broadcast and for enhanced MDI (multiple document interface) window positioning and cleanup. clsWndMainFrameBase is derived from MFC's CMDIFrameWnd, whose functions and data members are available to your application. Although BFC does not present a typical Microsoft Multiple Document Interface (MDI), because database application end-users often find it confusing, the BFC Demo App contains an example of how to use BFC as the basis for a regular MDI application. The Command File Editor/Viewer uses a CEditView and a Command File Document class to illustrate the standard MDI model. (To see this example of typical MFC document/view architecture, choose the File/New or File/Open menu items in the Demo App.)

  • clsAppBase (Application Base class)
    - For simpler, more reliable startup/logon and cleanup during termination, sending a message to all views in the app, automatic clearing of status bar messages, and memory leak and overwrite detection.

  • clsMultiDocTemplate (Multiple Document Template class)
    - For sharing of resources such as menus and accelerator tables.

  • clsFrmVwBase (Form View Base class), clsFrmVwTblBase (Table Form View Base class)
    clsFrmVwDetailBase (Detail Form View Base class),
    clsFrmVwTblAndDetailBase (Table and Detail Form View Base class)
    - For rapid form development, security features for controlling privileged operations, such as Add, Change, Delete or View, support of a 3D look, and automatic table/detail field coordination. Dynamically adds appropriate Sort, Search and Filter menu items to the top of the View menu.

  • clsVwTabBase (Tab View Base class)
    - For providing a Property Sheet (tabbed) interface for views, with colored tab support and automatic activation of views for each tab.

  • clsWndSplitter (Splitter Window class)
    - For drawing a splitter window with two panes side by side and creating the classes for both left and right views.

  • clsDlgBase (Dialog Base class)
    - For incorporating as a lookup dialog (for example within a combo control or a calendar in a date control), detecting if a modeless dialog has been created on the stack and is causing MFC errors, and for creating Abort Dialogs with a <Cancel> button to halt long jobs.

  • clsScrDbBuf (Screen Database Buffer class)
    - For automating data exchange between the database and screen controls and providing an event based interface for simplified programming of forms and dialogs.

Command File Document Screen

Command File Document Screen

  • Command files can be viewed in any text editor (File > New > Command File).
  • Used for editing, saving and running a command file. 
  • Sample of how to use typical MFC Document/View architecture in combination with the BFC framework.

The Screen library makes extensive use of the classes in the Database and Utility libraries. A typical example is the relationship between the Screen library’s Edit Base class (clsEdBase) and the general purpose Database Field Mask class (clsDbFldMask) and the Utility Date and Time classes.

The SetMask() function of clsEdBase can be used at any time to set or change the mask. (You still use the normal GetWindowText() and SetWindowText() to get and set the data in the edit control.) If a mask is supplied, clsEdBase does the required validation as the data is entered by user in the edit control and in case of any error, it flashes the appropriate message in the status bar.

Example: SetMask for Numbers:
m_edTest.SetMask("$9(6)0.0099,"); // e.g. '$123,456.1234' and '$0.00'
m_edTest.SetMask("9(7).9(4)"); // e.g. '1234567.1234'
m_edTest.SetMask("9(4)"); // e.g. '1234'
m_edTest.SetMask("9(3)0"); // e.g. '0' and '123'

Example: SetMask for Character Strings:
m_edTest.SetMask("x(10)"); // e.g. 'abc123ABCD'
m_edTest.SetMask("Pic: aalluu!!"); // e.g. 'Pic: aZbbXX1X'
m_edTest.SetMask("(999) 999 - 9999"); // e.g. '(212) 475 - 1942'

Example: SetMask for Dates:
m_edTest.SetMask("%m/%d/%Y"); // e.g. '01/31/1996'
m_edTest.SetMask("%d/%b/%Y"); // e.g. '01/Nov/1996'

The character and numeric mask formats available to clsEdBase come from the Database Field Mask class (clsDbFldMask). The mask can be obtained directly from the data dictionary by specifying the database record type (table) and field name (column). The characters to be used for currency, decimal point and thousands separator are obtained from Control Panel/Regional Settings (as stored in the Win.ini file):

Similarly, the date and time format masks available to clsEdBase come from the Date and Time classes (clsDate, clsTime, clsDateTim). When clsEdBase recognizes a date format specification, it automatically provides a date lookup button that can be used to bring up a calendar.

Test Form Screen

Test Form Screen

  • This Form View class provides examples of various BFC controls: clsEdBase, clsBtnBase, clsBitmapBtn, clsTblScrBase, clsTblLookupBase, clsCalendar, clsStaticPlus.

  • This form shows how these controls operate. The source code can be changed to debug a control and try different options.

  • Edit controls with various masks are shown.

A programmer can do many database operations, such as AddRec(), either directly through the Database Library or go to the Screen library, which makes some standard end user interface assumptions. Adding a record using the database subsystem means filling in field values into an area of memory and then calling AddRec() to do the database insert operation. On the other hand, the screen library assumes a more complicated structure, with concepts of:

StartAdd, which turns a screen from display-only mode to modification mode, with enterable fields left blank or filled with defaults,

Cancel, which interrupts work before the database operation is started and restores the screen to its previous state, and

Save or Apply, which calls the screen library AddRec, which calls the database library AddRec to do the actual database insert.

The database subsystem's AddRec() returns a completion code, e.g. APP_RetCodOk (0) if all goes well. The screen subsystem's AddRec() causes a completion message to be displayed on the status bar, possibly including a color (for example, "Duplicate data" in red, with a beep).

In general, the meaning of a particular operation depends on whether it is being done by the Screen subsystem, which assumes end-user interaction, or the Database Library. For example, a screen Cancel means interrupting an end-user data entry operation, whereas a database Cancel would be a multitasking interrupt of an actual database operation, such as stopping a long running query or rolling back the addition of a record after it had already started. A screen Copy record operation means priming a data entry screen with the contents of another record, which allows the end-user to quickly make a few changes and then choose whether to add it as a new record or cancel. On the other hand, a database Copy record operation would directly copy a record from one part of the database to another.

StartAdd, StartCopy, StartDel, and StartChg are all facilities provided by the Screen library that are not needed or provided by the Database Library. So, when you are thinking about screen based data entry or display, you will often find that the easiest way to do your database operation is to let the Screen library handle it for you automatically. On the other hand, concepts like screen Cancel (restoring previous values) have very limited applicability for batched, long running jobs of database operations, and for these you go directly to the Database Library.


"We needed a tool that would allow us to quickly and simply create a payroll system with dozens of screens and maintenance routines. We found BFC [Base/1 Foundation Component Library]  and have been thrilled with the results. Using the BFC classes helped to make the development of multi-page maintenance routines simple and bulletproof."
John Lapenta, Director of Development, Entel Systems


Application Library Classes

The Application Library pulls together all the components into a unified application. It is a small library, which sits on top of the Screen library and also makes direct calls to the Database and Utility libraries, and is responsible for the BFC Foundation Application (B1_APP.EXE). More importantly, the Application library is the starting point for a typical BFC application.

(click for Demo Application screen shots)
The Demo Application's About Dialog

BFC has the concept of deriving an entire application from another, in addition to just deriving individual classes. The Starter Application (ZZ_APP.EXE) illustrates how to derive from B1_APP.EXE. The Starter Application uses the classes, resources and command files of B1_APP.EXE as a base.

The Application library classes, which are the starting point for a typical BFC application, include:

clsAppMgr (Application Manager class)
- Derive from and register your application's screens (forms and dialogs), documents, views, combos, menus, etc.

clsBFCApp (BFC Application class)
- Derive from clsBFCApp and override InitInstance(), InitAfterLogon(), CleanupApp(), etc., and add your application's specific member functions.

wndMainFrame (Main Frame Window)
- Derive from and add handlers for your application's menu items.

clsGVar (Global Variable class)
- Derive from and include any application specific public member variables that need to be available globally.

dlgbarMainFrame (Main Frame Dialog Bar)
- Derive from and add your application's main bitmap buttons.

wndMDIClient (MDI Client Window)
- Derive from if you want to create a custom tailored client window for your app.


Application Class Hierarchy

A standard BFC application, like any MFC application, requires a CWinApp derived class to be constructed when other C++ global objects are constructed. When you create a new BFC application, a CWinApp based application class is automatically created for you.

If you give your application a short name of "YYY" and an ID of "YY", then there is an application class created called clsYYYApp. Your application class, clsYYYApp, in turn is derived from the Foundation App's application class, clsBFCApp. Since your application class is derived from BFC's, you can override the functions of clsBFCApp, such as InitInstance(), InitAfterLogon(), CleanupApp(), and DispAbandonShip() to add your own behavior.

clsBFCApp, which is contained in the BFC Application Library, is derived from the BFC Screen Library's clsAppBase. clsAppBase performs all sorts of useful services, such as:

  • sending a message to all views in the application

  • performing pre and post logon operations

  • automatic clearing of status bar messages

  • displaying an AbandonShip or Special AbandonShip dialog

  • automatic memory leak and overwrite detection (under DEBUG mode)

  • robust InitInstanceSafe() and CleanupApp() functions that are exception safe

Finally, clsAppBase is derived from MFC's CWinApp, whose functions and data members are available to your application. To review the MFC hierarchy, CWinApp is derived from CWinThread, which is derived from CCmdTarget, which is derived from CObject.

To summarize, the BFC application class hierarchy is as follows:

CObject - MFC Object Class
    CCmdTarget - MFC Command Target Class
        CWinThread - MFC Windows Thread Class
            CWinApp - MFC Windows App Class
                clsCommonAppBase - BFC Common App Base Class - Screen Library
                    clsAppBase - BFC App Base Class - Screen Library
                        clsBFCApp - Base/1 Foundation App Class - App Library
                            clsYYYApp - Your Application Class

In addition, you can, in turn, derive a second application from your own application (let's call it YD_App.EXE). Then, you can override your base application's behavior to create an easy to maintain, custom tailored version. In this case, the inheritance chain for the required application class (e.g. named clsYYYDerivedApp) would extend one more level, for example:
...
    clsAppBase - BFC App Base Class - Screen Library
        clsBFCApp - Base/1 Foundation App Class - App Library
            clsYYYApp - Your Application Class
                clsYYYDerivedApp - Your Derived Application Class (optional)

The bulk of the power of the BFC's application class comes from the Screen Library's clsAppBase and not from the Application Library's clsBFCApp. In general, you can derive directly from Screen Library classes and completely skip over the BFC Application library if you wish to entirely circumvent the typical behavior of the Foundation Application. However, usually it is much easier to accept the Starter Application as it is created for you and just override individual functions.


Main Frame Window Class Hierarchy

Like most MFC applications, a BFC application has a main frame window, which surrounds all of the other windows. Assuming you give your application a short name of "YYY" and an ID of "YY", then there is a main frame window class created for you called wndYYYMainFrame, which will be found in YY_MainF.H & CPP. As is usual with MFC architecture, you can add handlers in the main frame window class for your application's menu items.

Your main frame window, wndYYYMainFrame, in turn is derived from the Foundation App's main frame window class, wndMainFrame, located in B1_MainF.H & CPP. You inherit and can override its message handlers, for example for the Build Application Database menu item.

Further, wndMainFrame, which is contained in the BFC Application Library is derived from the BFC Screen Library's Main Frame Window Base Class, clsWndMainFrameBase. clsWndMainFrameBase performs all sorts of useful services, such as:

  • Controlling access to all menu items and popup menus when the user is logged on as Database Setup User (for initial database creation)

  • Periodically checking the database and broadcasting administator's messages, if any, to all currently logged on users

  • Under system administrator's discretion, forcibly logging off all the users or preventing logon of any users

  • Allowing all the active views to close gracefully during app exit

  • Storing the app's main window's position in the app's .INI file during app exit and restoring the settings the next time the app is started.

clsWndMainFrameBase goes a long way towards eliminating the need for all those message handlers whose only function is to launch a form or dialog. clsWndMainFrameBase handles WM_COMMAND messages (for example, from selecting a menu item) that do not have corresponding message handlers. If there is an entry in the Menu Item, Form View and Dialog Info array (gastruMenuItmFrmVwAndDlgInfo) in your Global Definitions file (YY_GDef.cpp) for the ID selected and an associated form view or dialog, then clsWndMainFrameBase will automatically launch it.

Finally, clsWndMainFrameBase is derived from MFC's CMDIFrameWnd, whose functions and data members are available to your application. Although BFC does not present a typical Microsoft Multiple Document Interface (MDI), because database application end-users often find it confusing, the Base/1 Foundation App contains an example of how to use BFC as the basis for a regular MDI application. The Command File Editor/Viewer uses a CEditView and a Command File Document class to illustrate the standard MDI model. (To see this example of typical MFC document/view architecture, choose the File/New or File/Open menu items in the Foundation App.)

To review the MFC hierarchy, CMDIFrameWnd is derived from CFrameWnd, which is derived from CWnd, which is derived from CCmdTarget, which is derived from CObject.

To summarize, the BFC main frame window class hierarchy is as follows:

CObject - MFC Object Class
    CCmdTarget - MFC Command Target Class
        CWnd - MFC Window Class
            CFrameWnd - MFC Frame Window Class
                CMDIFrameWnd - MFC Multiple Document Interface Frame Window Class
                    clsWndMainFrameBase - BFC Main Frame Window Base Class - Screen Library
                        wndMainFrame - BFC Main Frame Window - App Library
                            wndYYYMainFrame - Your Main Frame Window

Application Manager Class Overview

Every BFC application is created with an Application Manager Class for registering application screens (forms and dialogs), documents, views, combos, menus, document templates, etc.. Assuming you give your application a short name of "YYY" and an ID of "YY", then your starter application will contain code for clsYYYAppMgr, which is derived from the Base/1 Foundation App's clsAppMgr.


Screen Manager Class Overview

The Screen Manager Class, clsScrMgr, provides some central functions for the screen library and the application as a whole. There is one instance of the Screen Manager Class (clsScrMgr) in the application.

clsScrMgr allows for simplified launching of complex forms and dialogs, for providing easy access to the status bar, the user's log, if any, and shared resources such as pens, brushes & fonts, and handling abnormal termination for all severe errors.

The clsScrMgr has functions for screen control, including:

SetupFrm, DoModalDlg(), CreatNewFrame()
SetStatBarTxt(), RegisterInitScrInfo(),

The clsScrMgr functions used to assist in handling Graphic Device Interface (GDI) objects include:

GetPen(), GetBrush(), GetFont().

clsScrMgr provides some convenient wrappers for database functions, such as: 

OpenDb(), AddRec(), ChgRec(), DelRec(), ExecDbModOp()

clsScrMgr plays a central role in error handling and logging for an application and has functions such as:

AbandonShip(), IsAbandonShipInProgress(),
ChkMemStat(), SetDbTraceParams(), DbTraceProc()
InitLog(), LogStr()

Other useful clsScrMgr functions include: 

GetAppShortNam(), GetAppIcoId()


Form View Classes

Screens having forms for data entry and display are key ingredients of most business applications, and BFC provides several form view base classes as starting points. They are all eventually derived from MFC's CFormView and provide enhancements that:

  • Implements security features so that operations like adding, changing, deleting, or even viewing of the form can be privileged operations

  • Automatic table/detail field coordination

  • Provides virtual function, such as InitCtrls(), ActivateFrm(), etc., to simplify custom tailored behavior

  • Provides support for screen database exchange to aid rapid development of database forms

  • Implements a 3D look

  • Prevents resizing (optionally) & turn on/off CScrollView's scroll bars

  • Processes useful private messages, such as PM_QueryNeedToStayOpen, PM_EdModified, etc.

There are 4 form view base classes:

  • clsFrmVwBase (form view base class)

  • clsFrmVwTblBase (table form view base class)

  • clsFrmVwDetailBase (detail form view base class)

  • clsFrmVwTblAndDetailBase (table and detail form view base class)

The Form View Base Class (clsFrmVwBase) is derived directly from MFC's CFormView class and provides the basic additional functionality for the other BFC form view classes. You will seldom need to derive directly from this class, since most forms contain either a table of data, or individual record detail fields or both. Usually you will use the table form view, detail form view or table and detail form view base classes

clsFrmVwBase responds to the private message PM_QueryNeedToStayOpen, and if a modification operation is in progress, it presents the user with the choice to Save or cancel the operation. clsFrmVwBase uses its Screen Database Buffer Class (clsScrDbBuf) member to determine whether the form is currently being modified. (See clsScrDbBuf for more information about screen database exchange.)

clsFrmVwBase traps the PM_EdModified private message, which is sent by the Edit Base Class (clsEdBase), and sets the MFC document's modified flag only if the form has its own non shared MFC CDocument class.

The Form View Table Base Class (clsFrmVwTblBase), which is derived from Form View Base Class, is used to present data in a tabular fashion. It coordinates with the Scrollable Table Base Class (clsTblScrlBase) and the Screen Database Buffer Class (clsScrDbBuf) to display data in a table. It also provides functionality to sort, search, or filter the data that is obtained from the database through Scroll Cache Record Set class (clsRecSetScrlCache).

If the main menu contains a "View" popup menu, clsFrmVwTblBase dynamically adds Sort, Search, and Filter menu items to the top of the View menu.

The Form View Detail Base Class (clsFrmVwDetailBase), which is also derived from Form View Base Class, is used to represent the details of a database record on the screen. The Database Access Control Form (frmDbAccCtrl) and the Batch Job Detail Form (frmBatJobDetail) illustrate this model.

The Form View Table And Detail Base Class (clsFrmVwTblAndDetailBase), which is derived from the Form View Table Base Class), provides coordinated table and detail fields functionality. User Administration (e.g. frmUsrMastLst) and Distributed Batch Processing Services screens (e.g. frmBatJobMastLst) illustrate this model. Here is the inheritance chain for clsFrmVwTblDetailBase, the Table & Detail Form View Base Class:

CObject - MFC Object Class
    CCmdTarget - MFC Command Target Class
        CWnd - MFC Window Class
            CView - MFC View Class
                CScrollView - MFC Scroll View Class
                    CFormView - MFC Form View Class
                        clsFrmVwBase - BFC Form View Base Class
                            clsFrmVwTblBase - BFC Table Form View Base Class
                                clsFrmVwTblDetailBase - BFC Table & Detail Form View Base Class
                                    frmYYYSample - Your Sample Table & Detail Form View Class

By convention, BFC uses the Hungarian notation of "frm" for form view instances of all types (clsFrmVwBase, clsFrmVwTblBase, clsFrmVwDetailBase, clsFrmVwTblAndDetailBase).
(e.g. frmUsrMastLst, frmBatJobDetail, frmDbAccCtrl)

You use the runtime class of the derived form while adding the document templates or while calling the screen manager's SetupFrm(). Automatic launching requires an entry in the array of Menu Item, Form View and Dialog Info structures (tagMenuItmFrmVwAndDlgInfo), maintained in your Global Definitions file (YY_GDEF.CPP). You provide the runtime class of the derived class to permit the screen manager (clsScrMgr) to launch the form view automatically, for example, in response to a menu command.

To provide Sort and Search functionality, override GetPFrmSortSearchInfo() and return a pointer to the tagFrmSortSearchInfo structure.

To provide Filter functionality, override GetPFrmFilterInfo() and provide all the filter information for the form in a structure of type tagFrmSortSearchInfo.


Dialog Base Class Overview

The Dialog Base Class (clsDlgBase) is the general purpose base class used for deriving dialog box classes in BFC. It is derived from MFC's CDialog and provides:

  • Automatic launching of dialogs in response to menu commands using the Screen Manager's DoModalDlg() function

  • Detection and throwing of an error if the modeless dialogs are not created on the heap, thus avoiding some weird crashes in MFC's code

  • Ability to use a dialog as a lookup dialog, for example in the Combo Scroll Cache Base Class (clsCmbScrlBase) and in the calendar displayed by a date control

  • Facility for creating Abort Dialogs having a <Cancel> button that halts long-running operations

You can use a clsDlgBase derived class as a member or instantiate on the stack for dialog box functionality. Automatic launching requires an entry in the array of Menu Item, Form View and Dialog Info structures (tagMenuItmFrmVwAndDlgInfo), maintained in your Global Definitions file (YY_GDEF.CPP). You provide the runtime class of the derived class to permit the screen manager (clsScrMgr) to launch the dialog box automatically, for example, in response to a menu command.

Here is the inheritance chain for clsDlgBase, the Dialog Base Class:

CObject - MFC Object Class
    CCmdTarget - MFC Command Target Class
        CWnd - MFC Window Class
            CDialog - MFC Dialog Class
                clsDlgBase - BFC Dialog Base Class
                    dlgYYYSample - Your Sample Dialog Class

By convention, BFC uses the Hungarian notation of "dlg" for dialog instances. (e.g. dlgAbout, dlgBatJobMgr, dlgCmdProc)


BFC | Visual Studio | Database Technology | Distributed Computing | Utility Classes


Home Products Consulting Case Studies Order Contents Contact About Us

Copyright 2012, Base One International Corporation