================================================ README.TXT FOR LCKOWL.DLL Version 1.02 ================================================ Company Information: Larry Klein Principal LCK Consulting 732 Symphony Woods Drive Silver Spring, MD 20901 Phone: 301-593-2745 Fax: 301-593-4262 Introduction ============ LCKOWL is a subset of a larger set of tools that were written to simplify managing windows that have more than just the basic Microsoft Windows components. In this release, LCKOWL includes five OWL-derived window classes: o TMDIFrameTools - based on TMDIFrame, this class automatically manages a status bar, a tool bar and a tool box. The status bar, tool bar and tool box are based on Drover's Toolbox controls. TMDIFrameTools also manages groups of child windows that have been created using the other windows classes that come in this DLL, allowing users to easily stamp an ID to one or a group of windows, and to easily count and close a group of child windows based on their IDs. o TLCKWindow - based on TWindow, this class opens a window that includes an ID. It also allows a user to set it so that it can't be resized, in which case the sizing frame of the window as well as its maximize button are disabled. Additionally, the class registers itself as by its title, so that an icon that is associated with the window becomes the icon for this window, and any other window with an identical name. o TWindowTools - based on TLCKWindow, this class adds auto support for status bar, tool bar, and tool box controls using the same setup as that of TMDIFrameTools. o TMDIChildWindow - based on TWindowTools, this class is designed to be used when you need an MDI window that includes a dialog box. The window is automatically set not to be resized, and uses a parameter that automatically opens a child dialog within itself (using TMDIChildDialog described below). The class automatically manages resizing the window at startup, to match that of the dialog it contains. Though the user can't resize the window using the keyboard, using the MDI messages that cascade and retile child windows a WM_SIZE message must be processed, in which case the class automatically ensures that the window remains the same size as the dialog it contains. Additionally, the window manages the focus problem inherent in having a dialog box within a MDI child window. NOTE: there is a bug within this version: YOU MUST PRESS A KEY FIRST TO START THE TAB KEY WORKING IN THE DIALOG BOX. Because this class is derived from TWindowTools, it also supports automatic management of status bar, tool bar and tool box controls within its window. o TMDIChildDialog - based on TDialog, this class is used with TMDIChildWindow to manage the focus issue of having a dialog within a MDI child window. Additionally, the cancel and OK requests within the dialog box automatically close the window in which the dialog box is located. Drover's Toolbox can be purchased from FarPoint Technologies or from any number of software vendors that specialize in software for developers. FarPoint can be reached at (614) 765-4333. If you call FarPoint, please let Tamara Calaway (Director of Marketing) know that I referred you, and if there is enough of a response I might be able to get them to agree that I include more of Drover's toolkit on a review basis in my next version. NOTE: There are other toolkits available for the types of controls that I implemented. Because of the way in which the classes are set up, it should be fairly easy for someone to exchange Drover's Toolbox for another vendor's set of controls. Installation ============ Copy the enclosed .ZIP file to a first-level directory and unzip. If this has already been unzipped and is not in a first-level directory, copy the files into a first-level directory. COPY ALL DLLs INTO A DIRECTORY ON YOUR PATH, OR PREFERABLY INTO THE WINDOWS (typically \windows\) DIRECTORY OR THE WINDOWS SYSTEM (typically \windows\system\) DIRECTORY. IF THE DLLs ARE NOT COPIED INTO ONE OF THESE DIRECTORIES, LCKOWL.DLL AND GENMDIX.DLL WILL NOT KNOW WHERE TO FIND SUPPORTING DLLS. NOTE: If the files are not in a first level directory, the project will have to be edited so that the references to the project files match the directories in which they are located. NOTE: If Borland's C++ files were not installed in the default \borlandc\ directory, you will have to update the Options | Directories so that the header and library files point to the correct locations. Quick Explanantion ================== To start, I suggest you first run the enclosed GENMDIX.EXE application. It contains the features that demonstrate the functionality available in LCKOWL.DLL. GENMDIX.EXE also serves as a shell MDI application, and can therefore be used as a basis for creating an OWL-based MDI applications with status bar, toolbar and toolbox. Description of Menu Options in GENMDIX.EXE ------------------------------------------ File | New Window - Creates a new child window. The purpose of this function is to see how the window moves within the client area when the statusbar and toolbar are turned on and off. File | New Window With Dialog - Creates a new child window that contains an embedded dialog box. File | How Many Windows of Type - allows user to display in a dialog box the number of windows that the user designated with a certain ID. File | Close All Windows of Type - allows user to close all windows that the user designated with a certain ID. File | Enter Status Bar Text - Accepts any character string that will be displayed in the first status bar field. This option is only tied to the frame window status bar. File | Enter Status Bar Progress - Accepts any numeric value that will show as a percentage progress on the second status bar field. This option is only tied to the frame window status bar. Options | Create... - Creates appropriate control. If the focus is on the frame, then the control is created in the frame. Otherwise, it is created in the child window that has the current focus. Options | Destroy... - Destroys appropriate control. If the focus is on the frame, then the control is destroyed in the frame. Otherwise, it is destroyed in the child window that has the current focus. Options | Toggle... - Toggles appropriate control. If the focus is on the frame, then the control is toggled in the frame. Otherwise, it is toggled in the child window that has the current focus. Windows... - Standard MDI windows routines Explanation of TMDIFrameTools Functions --------------------------------------- OWL has certain menu IDs that are reserved so that OWL can automatically manage certain functions, without the developer having to code anything. For example, CM_CASCADECHILDREN automatically cascades child MDI windows without having to code a line in the header or source file. Simply add this as a menu option, derive your MDI window from TMDIFrame and OWL will take care of cascading children. (NOTE: You must add OWLRC.H to your source so that the Resource Workshop will recognize these menu IDs). Similarly, TMDIFrameTools has several menu options that automatically manage status bar, toolbar and toolbox functionality. To get these menu IDs to work in your resource (.RC) file, add the header file LCKOWL2.H to your resource (File | Add To Project from the Resource Workshop menu). By deriving your MDI window from TMDIFrameTools (which is itself derived from TMDIFrame), the following menu IDs will automatically work: IDM_CREATESTATUSBAR IDM_CREATETOOLBAR IDM_CREATETOOLBOX IDM_DESTROYSTATUSBAR IDM_DESTROYTOOLBAR IDM_DESTROYTOOLBOX IDM_TOGGLESTATUSBAR IDM_TOGGLETOOLBAR IDM_TOGGLETOOLBOX The management of the status bar, tool bar and tool box is demonstrated in the GENMDIX.EXE application that is enclosed. GENMDIX.EXE does not actually have any code associated with managing these MDI features, except to initialize them. TMDIFrameTools also manages its child windows as groups, by providing two functions that count and close child windows as a group. By using the other window classes in this DLL, that automatically stamp a window with an ID, TMDIFrameTools can count or close all windows that are stamped with identical IDs. An ID is any number assigned by the developer. GENMDIX.EXE demonstrates this feature by allowing a user to open a window and assigning it an ID of the user's choice, and then offering the user menu options to count or close all windows with identical IDs. In this way a developer can manage groups of child windows easily within an MDI application. Explanation of TLCKWindow Functions ----------------------------------- TLCKWindow is designed to manage two things: an ID associated with the window, as well as its resizing capability. The resizing option allows a user to set a resizing flag so that the window cannot be resized. In this case, all mouse resizing capabilities are disabled. Explanation of TWindowTools Functions ------------------------------------- TWindowTools is designed to supply the status bar, tool bar and tool box functionality found in TMDIFrameTools. Explanation of TMDIChildWindow Functions ---------------------------------------- TMDIChildWindow is used if you want to have a MDI child window with a dialog in it. This greatly simplifies creating MDI child windows using dialog resources that can easily be painted using Resource Workshop or a similar tool, rather than painting the window directly. This class automatically manages the sizing of the window to match that of the dialog box. NOTE: by default this class expects a TMDIChildDialog-base dialog, and the dialog should be created using the Child and No Border options in the Resource Workshop. This class also manages focus, so that focus passes to the controls of the dialog within the window. Since TMDIChildWindow is based on TWindowTools, it supports status bar, tool bar and tool box controls. Explanation of TMDIChildDialog Functions ---------------------------------------- TMDIChildDialog is designed to work with TMDIChildWindow so that focus is properly passed to the controls of the dialog when the dialog resides in a MDI window. This class also manages the cancel and OK buttons, so that they properly close the window when the dialog is closed. Explanation of Tieing Buttons to Menu Commands ---------------------------------------------- This is automatic, so long as the ID used for a button is the same as the ID for a menu option. This relieves the programmer from any extra coding. In GENMDIX.EXE, I used BM1 to represent the File | Enter Status Bar Text, and BM2 to represent File | Enter Status Bar Progress. The only requirement was that BM1 and BM2 have the same ID as the menu options they represent. You set the ID of a button in the source file when creating the structure that represents the toolbar and toolbox. GENMDIX.CPP is an example. Brief Technical Directions on Using LCKOWL.DLL =============================================== 1. Copy ALL the files of this package into a first level directory. Copy ALL DLLs into the \windows or \windows\system directory. 2. Add the header file GENMDIX3.H to your source file. The reason this is necessary is because you need some identifiers to use the LCKOWL.H file, which in turn uses identifiers from toolbox.h, which I could not include in this package. I have therefore included only the relevant identifiers in GENMDIX3.H. If you purchase Drover's toolbox, replace this file with toolbox.h (make sure to use the expression extern "C" {toolbox.h } when compiling in C++) 3. Add the header file LCKOWL.H to your source 4. Add the header file LCKOWL2.H to your resource file 5. Derive your MDI Frame from TMDIFrameTools 6. Derive your MDI child window from either TLCKWindow or TMDIChildWindow, depending on whether the window will contain a dialog 7. Initialize the status bar, tool bar or tool box controls in the window constructor of your TMDIFrameTools class using the Init... functions (see GENMDIX.EXE for an example). Follow the format that's found in GENMDIX.CPP for creating structures for a status bar, tool bar and tool box to be used in the Init... functions. 8. Add LCKOWL.LIB to your project 9. If you use Borland-style dialogs, add BWCC.LIB to your project and call BWCCGetVersion() at the start of your program 10. Add the menu options for status bar, toolbar and toolbox creation and destruction that are relevant to your application 11. Compile and have fun running your application! What Is Included ================ This version includes two projects: LCKOWL.PRJ and GENMDIX.EXE. The LCKOWL project includes all the source code and other files to create LCKOWL.DLL, except for the Drover's Toolbox header and library files. In order to revise and recompile LCKOWL.PRJ, you will need to purchase the Drover's Toolbox. However, because the Drover Toolbox DLLs are distributable, LCKOWL.DLL can be used as-is since all the necessary Drover's Toolbox DLLs are included. The GENMDIX.PRJ includes all the files necessary to compile a general purpose Windows program that includes a status bar, a tool bar and a toolbox. The executable, GENMDIX.EXE, is a fully functional MDI application that makes use of all the functions available in LCKOWL.DLL. You can use GENMDIX.PRJ directly, adding the necessary functionality to complete an application of your own. I suggest that you copy GENMDIX.PRJ (all files begining with GENMDIX*.*) to another directory, so that you can have a clean version for a second application. Note that the Options | Directories expect Borland files to be in the default \borlandc\ directory. Also note that the project expects to be in a first-level subdirectory, which means that if you copy this to another level directory, you will have to change the locations of the project files. This version includes LCKUTIL.DLL, which is used by LCKOWL.DLL along with a variety of other DLLs (not included) to centrally process standard messages, and to provide a central location for commonly used functions that are not available in standard libraries or Windows (such as word-, rather than string-, oriented functions, and some file and directory functions). Further Description of the TMDIFrameTools in LCKOWL.DLL and its Associated Project ============================================================ === To use TMDIFrameTools, simply specify TMDIFrameTools instead of TMDIFrame when you derive your own MDI Frame class. Then, to use any of the controls, simply initialize whichever or all the three controls using the InitStatusBar, InitToolBar or InitToolBox functions functions. A good example of how to do this can be found in the GENMDIX.PRJ project. The rest is managed automatically. What exactly is being managed? When a statusbar or toolbar is created, the client area must be adjusted so that a new window does not overlap the statusbar or toolbar. In other words, the statusbar and toolbar must be the topmost window within the MDI frame. Further, when the frame is resized the statusbar and toolbar must be resized accordingly, along with the client area. If the user clicks on any of the buttons on the toolbar or toolbox, then if the ID of the button matches that of a menu item the menu option should be initiated. There should be an easy way of updating text in the status bar, or if the status bar has a progress line, then the percentage filled should be easily updated. Finally, there should be an easy way to have these controls created, destroyed and toggled on or off using a menu option. All this is managed by TMDIFrameTools! To accomplish the last task, that of creating, destroying and toggling these controls, I have designated menu IDs to accomplish this along with their identifiers in LCKOWL2.H. To get these effects with no programming effort, include LCKOWL2.H in your resource file, and use those IDs for their approriate menu items (refer to GENMDIX.RC for an example). Once these menu IDs are used, TMDIFrameTools manages the rest automatically. More Questions, Suggestions, Criticisms ======================================= Please call me at (301) 593-2745, or fax me at (301) 593- 2745, or send me a message on Compuserve at 76330,2525.