═══ 1. Professor Owl Version 1.08 ═══ "All things bright and beautiful, All creatures great and small, All things wise and wonderful, The Lord God made them all." Cecil Alexander ═══ 2. Special Thanks ═══ Much time and effort has gone into this product, we give a special thanks to the following people: Jacque March for project coordination Gene Krywicki, IBM BESTeam member support. Shawn Jipp for artwork Valerie Jacobsen for proofreading Paul J. Hepworth for software testing And Thanks to all the registered users who support Professor Owl, OS/2, and shareware! Note: Professor Owl is distributed as shareware, NOT free software. You may use it for up to 30 days free of charge. If you wish to continue using the program after your trial period is over you must register. Registration costs just $29.95 (US$). Credit cards are accepted through BMT Micro. ═══ 3. Copyright ═══ Copyright 1995, Edward J. March Jr. All Rights Reserved. Grant of License. Professor Owl is marketed and sold as shareware. The registration key is sold for use on a single computer system only. Copies of the shareware may be distributed freely. The Key Serial number is for one user per computer only. For additional keys contact the author. Using a single copy of the key file on a networked or timeshared computer running more than once at the same time is a violation of this copyright. You may not copy, transmit, give away, disassemble, alter, patch, modify, or change in whole or part, any software contained on the diskettes, or quired through electronic transfer. This license agreement shall remain in effect from the date you open the package, download the software, or use this software until terminated. You may terminate this agreement by destroying all copies of this software, including backups on all types of media. Legal This is not a sale of the software title or rights to Professor Owl and the documentation files. Copyrights, patents, and all other intellectual property rights are retained by Edward March. You may not sublicense, assign, or transfer this license. If you or any organization breaches this agreement, your license is automatically revoked upon that breach. Should a court find you in violation of this agreement, Edward March may be awarded any attorneys' fees, expert fees, and the cost of the legal action. This agreement is governed under the U.S. Copyright law, and the laws of the state of Illinois. Warranty The author disclaims all warranties relating to the use of this software. The author shall not be liable for any misfortune or damages through use, directly or indirectly of any software provided on the diskettes or any other media the software was delivered in part or whole , on or through. In no event shall Edward March or its advertisers and/or suppliers be liable for any damages. Damages include but not are limited to loss of business, business delays, interruptions, and loss of revenue. Information is this manual or software is subject to change without notice. Code Generation All source code, data and binary code generated by and from Professor Owl is freely offered to you and/or your company to be used as you see fit. Edward March holds no rights whatsoever on any software source code or binary code generated by this product. The author is not responsible in any way for the use or misuse of the source code or binary code generated by this product. ═══ 4. Trademarks ═══ Trademarks IBM and OS/2 are registered trademarks of International Business Machines Corporation. Object Window and ResourceWorkshop are registered trademarks of Borland International, Inc.. BOXER is a trademark of Boxer Software. Other product names are trademarks of their respective holders. ═══ 5. Welcome ═══ Welcome to Professor Owl. This product is a code generator for the Borland C++ Object Window Library. It will help you to create OS/2 applications faster and more error free. Professor Owl reads and writes C++ code. When Borland C++ programmers began the migration to the OS/2 operating system one of the first obstacles they faced was the lack of a C++ Object Window Library code generator. Edward March is proud to be a pioneer provider of these programming tools. Traditionally the Borland C++ compiler has been king, it has a great IDE and a well designed class library for graphical user interface development. Professor Owl allows you to generate OS/2 applications in a matter of seconds. When you create a new application, all the framework C++ code, header files, and resources are created for you. Your application can grow to suit your needs by using Professor Owl to add more functionality to your source code. Certainly, no one could remember the hundreds of functions and events that make up the Object Window Library classes. This is where Professor Owl shines. When you want to add an event handler it's a mouse click away. Each event handler macro and function and header prototype will be written for you. This will save hours of time, since you will not need to remember what event macros go with what functions and what parameters they all need. It allows you to concentrate on your application and not the inner working of the class library. Professor Owl puts what you need at your finger tips. It is easy to use and very powerful; it will become your command center. ═══ 6. Installation ═══ Open a OS/2 Session (full screen or windowed). Change to the floppy disk drive directory (CD A: or CD B:) and type INSTALL. If your 3.5" disk is in drive A: do the following. CD A: INSTALL A subdirectory will be created on the desktop to hold the Professor Owl files. This directory will be referred to as Professor Owls Home Directory. Sometimes there are last minutes changes after this manual has been printed. These changes or important notes will be listed in the read me file. You can view the README.TXT file to see any changes that occurred since the manual was printed. This is a good time to start README.CMD that will view the README.TXT file. To execute Professor Owl - run the PROFOWL.EXE - by double clicking on the file, or typing it from the command line. With Professor Owl running you can check the home directory path by clicking on About from the Help menu. This will verify your installation path is correct. There are no environment variables or setting you will need. Everything is contained in this Home Directory. If you copy PROFOWL.EXE to another directory then that directory will be Professor Owls Home Directory. If you have two copies of the executable file, then you have two home directories. Before you can generate an application you will need to set the user settings to ensure the compiler paths and Professor paths match. ═══ 7. User Setup ═══ Once you start Professor Owl enter the User Setup screen by pressing the Setup button In the settings screen there are several options that can be set. Pressing the Default button will give you a good start, however some entries referencing disk drives or paths may not match your computers configuration. Later we will look at the path settings. Professor Owl's path setting should match the Borland compiler paths. But now let take each entry of the settings screen in a logical order. ═══ 7.1. Code Generation ═══ The code generation section of the setup screen allows you to define how Professor Owl will generate the C++ code. You can use tabs or spaces for indentation. The default is 4 spaces. This seems to be a popular format and can be handled by all editors. Changing this parameter takes effect immediately. However it will not change existing code already written. But the next time your generate code, this new type of indentation will be used. If you change from tabs, to spaces, your code may not look indented as you expect. We suggest keeping with one style of indentation throughout a project. ═══ 7.2. Include Path ═══ The #include path is the include statement that the generated code will use to find the Object Window class library. Your compiler should know where to search for include files. Normally the compiler will search X:\BCOS2\INCLUDE. (where X: represents the disk drive the compiler was installed on.) This is a Compiler setting, and not a Professor Owl Setting. Borlands OWL library is normally in X:\BCOS2\INCLUDE\OWL. Therefore since the compiler can find files in the parent directory, we need to only prefix the owl files with "owl\". Using all the factory default of the Borland C++ compiler you should not have change this from owl. You do not need the trailing backslash if you provide one it will be stripped off. Here is an example if the setting was set to owl, this code would be generated. #include "resource.h" #include #include #include Notice dialog.h, combobox.h and edit.h are preceded with the path owl. ═══ 7.3. Comments ═══ Your Code Comment Here is a comment that Professor Owl uses to flag places where you may need to edit the code. If several programmers are working on the same code, this can be used to flag the person who generated this function with his comment. For example Bill's comment might be INSERT>> Bills code and Franks might be INSERT>> Frank Smith. Yes, the common text string in both of their comments, 'INSERT>>' can be searched for no matter who generated the code. You can use C++ style // comments or C style /* */ comments. Here is an example of the user comment inside a function: //---------------------------------- // Cancel Button Pressed //---------------------------------- void MyClass::EvClickCancel(void) { // INSERT>> Your Code Here CmCancel(); } You will see comments like the above throughout the generated code. You can search for these and add the functionality you need at this point in the source code. The function delimeters are inserted before the function with a comment between them describing the function. The _head_.cpp and _head_.h files are used when creating a new class. When a new file is created to hold the class data, these special header files will be put at the beginning of the generated class. These header file can be any name you like, by default we use '_head_.h' and '_head_.cpp'. You can also specify a path to them, if no path is given they are assumed to be in the current project directory. There are several Macro's that are expanded. Each macro name begins with a dollar sign. They are: $time, $file, $path, $class, $base and $product. $time will expand to time/date string like "Mon Dec 25 12:01:02 1995", $file if the file name without the extension. $FILE is the file name in capitol letters, $path and $PATH is the current drive and path where your new files will be created, and $product is the current version of Professor Owl such as "Professor Owl 1.08". Lets assume you create a new Class call MyNewClass of TDialog type in a file NewClass.Cpp and this is your _head_.cpp file. //=============================================== // $path\$file.cpp created $TIME // // Using $product // Class Name $class derived from $base // Prototypes are in $file.h // upper case name is $FILE and lowercase is $file //=============================================== The final code would look like this: //=============================================== // d:\pro-owl\newclass.cpp created MON DEC 11 12:34:56 1995 // // Using Professor Owl 1.08 // Class Name MyNewClass derived from TDialog // Prototypes are in newclass.h // upper case name is newclass and lowercase is NEWCLASS //=============================================== Notice $file and $FILE expand to the same name except for the case. This is true for most macro names, except $product, $class and $base. ═══ 7.4. Owl Path ═══ You will need to include the path to the Borland C++ Owl header files. The default path may be correct, if you installed the Borland C++ compiler in the default directories on your C: drive. If you used another disk drive or a different path, you will need to enter the correct drive and path. The default is C:\BCOS2\INCLUDE\OWL. This is used to scan resources , and also to generate the make-file when new application code is generated. ═══ 7.5. Editor Save Options ═══ The editor options control Professor Owl's built-in editor. As you add code, the changes will be shown in the editor window on Professor Owl's main screen. You can set this editor option to one of four choice. Read Only: This means that the source code shown in the edit window can be viewed and not changed by you. Use this option if you do not feel comfortable editing outside of your favorite editor. In this mode, you cannot alter the text, and you need not worry about saving unwanted changes to your source file. Never Save: Allows you to make changes in the editor for your viewing purposes only. None of the changes you make will be written to the disk. Prompt To Save: Professor Owl will Prompt you (Yes or No) to determine whether you would like to save the changes in the editor to the disk file. If you say No, your changes are lost and not saved to disk. Auto Save: This is the default, and the most likely choice. In this case, the changes in the editor are always saved. You will not be prompted to save your changes. The file will always be up to date with the code in the edit window. More about backup files in the next section. ═══ 7.6. Editor Backups ═══ Enable Backups is a safety feature. Before saving the editor text to disk, it will rename the disk file to the backup extension you provided. You may want to choose a unique extension to distinguish these backup files from other backup files created from different editors. It is not necessary to do this. If you do not want the extra disk clutter, you can use the same backup extension as your favorite editor or just turn off this feature. Turning off the Enable Backups saves very little time. Professor Owl will save the edit file to disk before making any changes to the file itself. All automatic changes are done on a file basis. Professor Owl does not add the text into the editor as you would. It inserts text changes into your disk file. When you add a event or function to your code, the edit text may be saved to disk. Professor Owl add its necessary code to the files. After the files are updated, the C++ code file is loaded into the edit window. The text is positioned to show the newly added function. ═══ 7.7. Help Tools ═══ You may add eight favorite or frequently used programs to the tools dialog buttons. There are eight user defined buttons. You can name these buttons anything you like. When pressed they run a executable file. The button names will appear on the face of the buttons when the tools dialog is active. Each button can have a ~ (tilde) character in front of the character on the button you want underlined. You can access these tools with a single keystroke using Control F1 through Control F8. Pressing the Default button in the dialog shows some examples. There are several macros -- $hfile, $cfile, $home, $path and $line. These will expand to the current header file, source file, and home directory path, current path and line number of the built-in editor. You do not have to use these. The dollar sign variables will be expanded in the Button Name Tool Directory and in the Executable Path. Normally the Directory is set to the current directory '.\' but there may be cases when you will want to run a tool from its directory so it may find its DLL's or INI files. In that case you will need to use the $path\$cfile to have it locate your .CPP file. If you were to use the Boxer text editor you might have a setting like this: C:\BOXER\B2.EXE $cfile -g$line Notice the -g$line causes boxer to start editing at the same line number as Professor Owl's built-in editor. The -g is a Boxer switch, the $line is a Professor Owl variable that represents a line number from 1 through N (the maximum number of lines in the file). If you are using the Mister Ed editor (it's whats the author uses) you would have a setting like this: C:\MED\MED.EXE $cfile $line 1 Notice the $line causes Mister Ed to start editing at the same line number as Professor Owl's built-in editor. The 1 is the column number. If you were editing the AboutDlg.Cpp on line 27 then Mister Ed would see these parameters. C:\MED\MED.EXE aboutdlg.cpp 27 1 Boxer and Mister Ed Are OS/2 Shareware Editors ***** For furthur information on Boxer call or email David R. Hamel, (603)-924-6602, 70242.2126@compuserve.com ***** For further information on Mister Ed write or email Matt Prefsdorff, 76135 Karlsruhe, Germany. matz@karlsruhe.netsurf.de Pressing Cancel discards any changes in the user settings. Pressing Save writes these setting to the PROFOWL.INI file in the home directory. When you press one of the tool buttons to start another application, Professor Owl will leave the tool dialog active until that application finishes executing. This is done so that you do not modify your source code with Professor Owl and the tool application at the same time. You can override this safety, by closing the tools dialog. By be careful about modifying the same file by two different applications. ═══ 7.8. Home Directory ═══ This is a good time to mention what the home directory is used for. This directory is what Professor Owl uses to find the PROFOWL.INF help file and PROFOWL.INI setup file. You can tuck Professor Owl away, in some directory, but use it in directories where your C++ source code exists, and not have your disk cluttered with extra PROFOWL.INI files or PROFOWL.INF files. Unlike other environments that splatter files all over your disk, The author does not do this. All files are in the installed directory. The Home Directory can be seen from the About dialog box under the Help menu. Making shadows of the Professor Owl Icon does not change the home directory. It only allows you to start Professor Owl from a more convenient location; such as a Tool Bar, Launch Pad, or another folder. ═══ 7.9. Project Directory ═══ If you do not use a project file then all C++ files must be contained in the current project directory. To change the project Directory/Path select Project/Path from the File menu. Professor Owl works using YOUR C++ code. There are no databases or other saved information about your classes, functions or events. This means that your source code will not get out of sync with any database, that may happen with other code generators. You have freedom to change your code, at any time and rescan it so Professor Owl will recognize your changes. You can start using Professor Owl Now even if you are in the middle of a project. You can also use Professor Owl with older projects. This is because it not only writes C++ code but also knows how to read it and can find key places to add changes. Professor Owl like to read code written with a certain style. You can read about these under Limitations. ═══ 7.10. Project Window ═══ If you do not use a project file then all C++ files must be contained int the same directory. Usinga Project file allow you to have a more flexible directory layout. You can might have a directory layout such as this: G:\MyProject\Include\ G:\MyProject\Common\ G:\MyProject\Res\ G:\MyProject\Code\ Your Project might have several header files in the Include directory, but the classes are implemented in another directory 'Code'. The Common directory might contain code that is used in this project and other projects. The 'Res' directory would hold the .RC file that is for this OS/2 application. You must add in all files that are part of your project. This includes not only the .CPP files but the .H or .HPP files as well, and also the .RC files. Don't forget the .H file that has all the constants used for the resource ID's! Saving the project file save the list of file show in the project window to a file called PROJECT.OWL. There is only one project file per directory, but that project file can point to files anywhere on the system. The button Tool #1 shows the last tool number that was run. You can use the right mouse click to select a tool to run. The selected tool will show a check on that menu item of the right click popup menu. Once a tool is selected, you may double click the entry of the path\file name, press the Tool # button to run the tool again. The Tool will see the full path and file name as the $cfile and $hfile, the line number $line will always be 1. You may keep the project dialog box open while working with Professor Owl. Pressing the delete button deletes the entry into a undelete buffer that is 128 levels deep. You may undelete while the windows remains open, once the windows is closed the undelete buffer is flushed. Changes made to the project list must be saved to the Project.Owl file before than take effect. Adding a new class will ask if you want the new files added to the project list if a valid Project.Owl file is found. Warning: A empty Project.Owl file is just that, you have no files in the project and Professor Owl will NOT find any classes during its Rescan! If you are not using a project file, delete the Project.Owl file. ═══ 7.11. Create Makefile ═══ Using the files in the project window you can create a makefile. The other two parameters needed to create the makefile are: 1) The name of the makefile, and an optional path to store the obj files. By default the object files are placed in the same directory as the source files. you may leave this field blank or use a period, to specify the current directory. See the macro $(OBJ_DIR) in the .Mak file for furthur details. Link switch /Toe = Create /Type OS/2 .Exe File Link switch /Tod = Create /Type OS/2 .Dll File Link switch /aa = Create Application Type API Link switch /v = Create Symbolic Debug Info for Turbo Debugger Link switch /x = Do Not Create MAP file See Borland BC.HLP or BC.INF (use HLP2INF on BC.HLP) located in the Borland bin directory (i.e. x:\BCOS2\BIN\) for more details on TLink. ═══ 8. Create New Applications ═══ "Come on, then!" roared the Queen, and Alice joined the procession, wondering very much what would happen next." Alice in Wonderland If you have never created an Owl application for OS/2, now is the time to start! Without Professor Owl, you would be typing for long time, especially if you never created an application before. Well forget the typing for a minute and get ready to push some buttons! Professor Owl knows how to create stock applications that are the backbone of your final product. After Professor Owl generates your application code it can run the make-file it generated to compile your newly created application. Select the menu item Code, and then Select Create New Application. You will be given several options. Select any options you want. The code generator will create several files in the project directory. New applications consist of a resource file RESOURCE.RC and a resource header file RESOURCE.H and sever C++ file. The function OwlMain and the class TApplication are in the file MYAPP.CPP. the other files are ABOUTDLG.CPP, MYSDI.CPP, or MAINDLG.CPP. Each .CPP file has a corresponding .H file. So now that you know what the files are, lets compile them. ═══ 8.1. Compiling ═══ You can build you application using the command line make -fmyapp.mak or using the BC++ IDE compiler and adding the file to the .PRJ file. Start the compiler, and enter all the .CPP files into the project list. Also, enter the RESOURCE.RC file into the project list too. Its is a common mistake to forget to enter the resource file into the project list. Next you will need to select several project options from the Borland IDE. Set the Target type to PM (Presentation Manager). In the Linker Library section select static for all three library types. Your application should compile and link with out errors. If you get compiler error most likely the paths from Professor Owl do not agree with the path setting of the compiler. Check you compiler settings and verify them against the Professor Owl settings. If everything compiled ok but there are linker errors, check the Borland C++ Project Setting. Each library: Standard run-time, Container Class, and Object Window should be set to Static or Dynamic, neither of them should have None as a selected option. The Executable Target should be set to PM application and not a text mode application. Borlands resource linker should compiler the resource.rc file, and bind it into the executable. Once this is done you can select Run from the IDE menu and see it execute. As you toy with your new application you will find it is very simple. It is a foundation on which to build upon. The important thing is what happens next. Because this determines how you craft this simple application into your final product. Like a master craftsmen uses his tools, you will use Professor Owl and the Borland Class Library to create your end master piece. Learning how Professor Owl operates is vital to achieving the end results you desire. ═══ 9. Operation ═══ Professor consist of six sections as seen on the screen. The drop down list of classes, the list of items, the list of events/functions, the edit source file; and the controls menu and buttons. The sixth part is the menu which is accessed by clicking the right mouse button. Lets review each of these sections for a better understanding of what they do. ═══ 9.1. The Class List ═══ When you look at the list of classes in the drop down list, you will see the four things. The class name, a colon the base class, and in parentheses two file names. The header file and the code file. You may see an option id=ID_XXXX if this is a class representing a resource dialog. Here is a example of a class called MyDialog, based on the TDialog Object Window Class. It represents a Dialog class with a resource ID_MYCLASS, as defined in the resource.h and resource.rc files. MyClass : TDIALOG ( mine.h mine.cpp ) id=ID_MYDIALOG From this we know that MyClass has a parent class TDialog, and has the class prototypes in the file mine.h, and the class code in mine.cpp -- also the resource id is ID_ MYDIALOG as defined in the .RC file. Professor Owl puts the class declaration in the header file and the actual class code in the source file. Classes are made up of two files. The header file tells the outside world what members are in the class. The source file is the actual code for these members. When Professor Owl is started, it looks for C++ code in the current directory. When it finds Object Window classes it adds them to the drop down list box labeled Classes. So what is the identifier for? It has nothing to do with the C++ language itself. Classes are often made that represent the functions of a dialog box. When you create a dialog box with Borlands ResourceWorkshop, you might write code to give it functionality. The resource code determines what the dialog will look like and what controls it will have. It is the class code with the dialog resource that determines how your dialog box will appear on the screen and function to the operator. You will learn more about creating classes after we create an application. Identifiers are also used for other resources like buttons, list boxes, bitmaps. I dialog resource can have many other type of resources drawn on it. Each one of these resources if give a identifier. These Id's allow you to manipulate the controls of a dialog box. ═══ 9.2. Item List ═══ This is a list of items for the selected class. Depending on the class type. You may see: Virtual functions, Standard Messages, Identifiers, and Commands. If your class has virtual functions they will be listed in the event/function list box. The same is true for standard messages. Identifiers come from your resource files. Standard messages are implemented with message macros that take no parameters; Identifiers as defined in a header files such as resource.h; Commands as defined in a header file or in one of Borlands header file. Note the all Identifiers must start with ID_ such as (ID_FILE), and all commands must start with CM_ as CM_EDITCOPY. This is Borlands convention, and it tends to keep the source code well organized. Above these identifiers and commands and the files listed in angle brackets of where there are defined. Show Constants Option Sometimes it is convenient to just assign a number instead of ID_'s to the items. This is true with static text controls. Professor Owl has a option to show controls that have ID numbers as numeric constants. But it is bad practice to hard code these ID's in your program C++ code. So you can weed out controls that will not be used in the program but are still needed for visual purposes. The option is saved to disk in the Profowl.Ini file when the save button is pressed in the setup dialog. ═══ 9.3. Event / Functions ═══ This is a list of functions that can be added to this class. What you see in this list depends on what Item is selected. And what you see in the Item list depends on what class typed is selected. This list has hundreds of functions, depending on the combination of class and item selected. This is where Professor Owl will save you hours of scanning through reference manuals trying to figure out what Macro name, function name and parameter list all go together. You simply select a function from the list, if the selected function is already in the source code, then the source file will move to the position of the function within the edit window, if it is not you can press the Add Function button or select it from the menu to add this function in the source file, prototype file, and if a macro if needed for event handling it will be added in the source file too. ═══ 9.4. Edit Window ═══ This is a multi line editor control, that allows to edit and make changes to the source code. You will want to read the user setting to know about saving the changes you make. Professor Owl will do its best to keep the source code position to what functions are current being added. ═══ 9.5. Controls ═══ There are two way to use the controls on Professor Owls main screen. The menus are available for traditional keyboard use along the certain letters being underlined for quick access. If you prefer the keyboard over the mouse you might want to add functions with ALT+C, A. however mouse lovers might prefer to click on the add button. If you really love the mouse, in the OS/2 spirit of things, there is a right click menu. You can right click on the Item list, on the event/function list or on the edit window. Each right area has its own right click menu. This menu gives you the same features of the button and pull down menus with a little more convenience. ═══ 9.6. Title and Status Bar ═══ Professor Owl will show the current Project Directory path on the title bar on the main window. You can always be sure where you are by looking at the title. The status bar on the bottom of the main screen shows messages regarding the operation or adding or deleting or searching for events and functions. ═══ 9.7. Short Cut Keys ═══ For Convenience you can use ALT+1, ALT+2, ALT+3, to move between the class list, item list and event list. Alt+T will bring up the tools dialog. The second letter is the name of the button you gave them in the setup screen. Also Control F1 - F8 are short cuts for the tools. You can add events and macro by double clicking the event list box entry. In this case no warning are issued if a function already exists in the code! Generally during code development you will be adding events and functions. Double clicking the functions and event names is the faster way to add them. ═══ 9.8. Searching ═══ Since both list boxes of items and events have so many entries starting with the same letter a search feature is provided. You can find any string by searching for partial phrases or key words. Also the right click in each list box will have a search in their menu. If you search for the paint you may find the entry EV_WM_NCPAINT. The search is NOT case sensitive. You may hilight text in the editor and it will be the default text to search for. Also when text is found in the editor it is hilighted. ═══ 10. Create New Classes ═══ This allows you to create a new class derived from one of the popular types of Object Window classes. When you create a new class, you must derive it from an existing Borland Class. Since several classes don't make sense as a base class, or are rarely used, we provided the most common classes in the list as your choice of bases classes. If your base class is a from a TDialog you will need to select an identifier. This is because TDialog classes are made up of resources controls. The list of resource ID's will show what files there are used in. A resource with a question mark in the file name is not used. By convention classed have their 1st letter capitalized, but this is not necessary. Notice the header file and code files will be the same name of the class. If you entered 'MyClass' then the two files used to create the class will be myfile.h and myfile.cpp. Each class should be contained in its own .cpp file. Once your class has been created you will get a default constructor for that class type. Dialog classes will also get a few commonly used functions. EvInitDialog, and cancel and Ok will be created by default. Almost always you will need these helper functions. When you return back to the main screen, your new class will be selected, and you can add more functions as needed. ═══ 11. Naming Conventions ═══ " 'Must a name mean something?' Alice asked doubtfully. 'Of course it must,' Humpty Dumpty said with a short laugh.' " Alice in Wonderland Professor Owl follows the Borland naming conventions. These are not hard and fast rules, they are only guidelines to help you stay a bit more organized. We strongly suggest you stay with these guidelines. All resource objects such as menus dialogs bitmaps and all other are normally kept in one .RC file. Normally you can use the same file name such as RESOURCE.H for every project. Since each project will be in its own subdirectory. Keeping the same name make it easy to edit the file. It is not necessary to have project one use proj_one.rc and project number two use proj_two.rc when one name will do. All resource identifiers start with ID_ This is what Professor Owl scans for. It is not necessary to include several other header file inside the resource.h file. The only exception to this may be to include header files from third part software vendors. Resource files are small and compile fast. Commands such as menu functions are normally named starting with CM_ -- these should be in a header file. Professor Owl expects to find CM_ #defines in a header file. If your commands are used once in a .CPP file, include the header. Professor Owl will not scan .CPP file for CM_ command since this is too time consuming. Variables by convention of Professor Owl start with m_, for member. This is not necessary. Professor Owl find variables by looking in the class declaration and class constructor. No special naming is checked. We have found it helps to keep member variables name differently than local variables just for organization. ═══ 12. Variables ═══ Pressing the variables button allows you to add member variables to the currently selected class. When you add a variable it can have a public, private or protected scope. Generally variables are private, so that only member functions of that class can access them. There are two kinds of variables, although we make no major distinction between them. A simple variable is an integer, long, character or a data type known to the C++ language. The other kind is a class or user defined type. Our user defined types are Object Window class type of controls. Let's examine the simple types first and see how Professor Owl handles them. here we see a variable that is an unsigned long, called m_MyULong and has a private scope. It looks like this in the class declaration of the header file. class MyClass : public TDialog { private: // Variables unsigned long m_MyULong; TListBox *m_Mylistbox; public: // Methods MyClass(TWindow *parent); --- cut--- It is good practice to initialize all variable to some default value to prevent unexpected surprises. Here we see the value set to zero in the constructor of the class. //---------------------------------- // Constructor //---------------------------------- MyClass::MyClass(TWindow *parent) : TDialog(parent, ID_DLGMSG1000) { // INSERT>> Your Code Here m_Mylistbox = new TListBox(this,ID_OBJECTS); m_MyULong = 0; } You can edit the constructor and set any other value besides zero if you need to. Professor Owl will recognize the variable because it appears in the headers and the source file. The second kind of variable is normally used in dialog boxes to gain access to controls. This is a pointer type. Three references of code are generated to create these kind. In the header file we see a m_Mylistbox is declared as a TListBox pointer. Here is the header file section showing the variable. class MyClass : public TDialog { private: // Variables TListBox *m_Mylistbox; public: // Methods MyClass(TWindow *parent); --- cut---- This is common with dialog boxes that have several types of controls on them. If for example you want to add a list box to your dialog. You would use ResourceWorkshop to add a the control to the dialog box. When the RESOURCE.RC file is saved. Professor Owl will need to rescan it to know about this new control that was just added. If you executed workshop from the tools menu then Professor Owl will automatically rescan when the tool is done executing! In this example you have a dialog with an Id of ID_MYDIALOG. You use ResourceWorkshop to add a list box with an Id of ID_MYLISTBOX. You want to be able to access the Object Window functions like AddString() and GetSelIndex(), to make use of the listbox control. To do this you need a member variable or control variable. Professor Owl can add one for you. Press the variables button. A dialog will show all of the current variables in this class. Perhaps you have none right now. Press the default button Add Variable and another dialog will allow you to choose the type, and scope of the new variable. For type select from the list box of types, Choose ID_MYLISTBOX, a name of m_Mylistbox will appear. You can edit this name, and rename it. Remember the m_ is not necessary only our convention. For our example lets use the default name of m_Mylistbox, and leave the scope as private. Press OK to create the variable and return to the previous variables dialog. You will notice that your new variable m_Mylistbox is show in the list of variables. ═══ 12.1. Variable Examples ═══ Here is a sample of the constructor: //---------------------------------- // Constructor //---------------------------------- MyClass::MyClass(TWindow *parent) :TDialog(...) { // INSERT>> Your Code Here m_Mylistbox = new TListBox(this,ID_OBJECTS); } Here is a sample of the destructor: //---------------------------------- // Destructor //---------------------------------- MyClass::~MyClass() { // INSERT>> Your Code Here delete m_Mylistbox; } A lot has happened here. First we will look at the header file and later the code file. The header file added a new variable. This variable matches the control with the Id of ID_MYLISTBOX. This Id is defined in the resource file when you created the listbox. When you drew the control in ResourceWorkshop, it created an entry under ID_MYDIALOG -- a new control with the attributes set to WC_LISTBOX. This was saved in the RESOURCE.RC file. Professor Owl scanned the RESOURCE.R file and noticed the new control and the identifier ID_MYLISTBOX. When you added a new variable of using ID_MYLISTBOX, Professor Owl knew to make the variable a pointer to a TListBox class. The code file, has three changes. First a new include header was added if needed. Code was added in the constructor class to create a new TListBox on the heap. Secondly code in the destructor of the class was written to destroy the variable. Finally the variable names defaulted to m_ this is just a convention to let you know it is a member of a class. You are free to name the variables anything you like. ═══ 13. Events and Functions ═══ Events are noteworthy happenings in the graphical user interface world, which occur when the user clicks the left mouse button, releases the left mouse button, or presses a key. Events are necessary to inform your program what the user is doing. Without events your program could not communicate with he human using the computer. The operating system has an event queue that hands off these events to the active program. If you have ten programs running under OS/2 and you press the space bar, only the active program will get the event. The other programs are still running, in the back ground. This philosophy can be taken one step further. Your program may have multiple windows or controls, but only one of them has input focus. Events have a WM_XXXX type of message. WM_PAINT, and WM_LBUTTONDOWN, are examples of message constants that correspond to a window being painted, or to the user pressing the left mouse button down. These events messages are sent to the parent class and are normally handled by their default virtual functions. Events have message map entries in a table, so that when OS/2 sees an event, it can tell the Object Window Library. Borland's classes look for an event handler, through the class hierarchies. When you add an event, you will add a macro in the message map table. Some macros take parameters and some don't. If no parameter is needed then, the function attached to the event is a fixed constant name. When there are parameters to the macro they are usually the function name. An example may help to clarify how event handler work. If you add a WM_LBUTTONDOWN event handler. You would get a function added to you code like this: EvLButtonDown(UINT modKeys, TPoint& point) { } You cannot choose the function name or the parameters, this is chosen for you by the class library designers. The point is the x and y coordinate where the user pressed the left button down. The operating system knows about events and calls functions or virtual functions through a message map table. ═══ 13.1. Message Maps ═══ Here is an example of a message map; //---------------------------------- // MESSAGE MAP FOR MyClass //---------------------------------- DEFINE_RESPONSE_TABLE1(MyClass,TDialog) EV_BN_CLICKED(IDOK,EvClickOk), EV_BN_CLICKED(IDCANCEL,EvClickCancel), EV_WM_LBUTTONDOWN, EV_COMMAND(CM_ABOUT,EvCmAbout), END_RESPONSE_TABLE; The above function EvLButtonDown is defined by Borland, so the macro name and function name are predefined. But if all macro names were hard coded, there would be a limited number of possible macros and function name combinations. Parameters allow the same event to trigger different functions. When a button is pressed, the same macro handler is used, but each button may call a different user defined function. Notice the EV_COMMAND macro is triggered by the CM_ABOUT command to call the EvCmAbout functions. Here is the function definition: //---------------------------------- // Event EV_COMMAND for CM_ABOUT //---------------------------------- void MyClass::EvCmAbout(void) { // INSERT>> Your Code Here } Next let's look at virtual functions, and see how they differ from events. ═══ 13.2. Virtual Functions ═══ These are functions that can be overridden by the derived class. They do not necessarily have events tied to them. When a class library is designed, it has many functions. Without functions it would be a data structure. So together data members and functions members, bring data and code together to make useful objects. The public functions allow the class to interface with the outside world (you the user). The private functions allow the class to work internally. You will sometime need to tap into key places, to know when something happens. Virtual function can be thought of like a patch panel. If there is no plug for what we want we can not get the signal. But if the designer has kept us in mind and has of provided a lot of functions or plugs we can use, then we can over-ride that function in our own class. Once we do we get control at some point and must take the same parameters as the virtual function of the original class. In order not to break working code, we need to pass this intercepted information back to the original class. So almost always, a virtual function should call its base class function with the same parameters it received. If you think of each class as a black box, you will understand this analogy. In effect, it is like unplugging the patch cord from a patch panel and plugging it into to your own device (your class). Once you get control of the information, you need to patch it back to the main panel again. To make matters more interesting, this splicing in is followed down the whole tree of classes. So when you derive a class Son from Father who was derived from Grandfather, you have access not only to your Father's virtual functions but all the way down to the base or root class. Fortunately for you the Object Window library is only a handful deep! Here is an example of a virtual function and the call to its parent class. //---------------------------------- // Virtual Function //---------------------------------- BOOL MyClass::Create(void) { BOOL RetValue =TDialog::Create(); // INSERT>> Your Code Here return(RetValue); } ═══ 13.3. Add Function ═══ The Add Function button adds the event macro handler and function to the header files and source files. In the case of virtual function there is no message map macro. Only events have message map macros. However, some events have fixed names and some have variable names. When a macro can accept a variable name, a question mark precedes the function name as in ?EvClick. You might have a dialog with ten buttons, and you want to know which button is pressed. Hence you need an event handler for that button, you select the ID_MYBUTTON1 in the item list, and the click event. This name cannot be a constant since all buttons can be clicked on. Therefore you must supply a unique function name that makes the function for that particular button. You would do the same for button two and buttons three through ten. You could however have button 3 and 4 use the same event handler. Why? Depending on your dialog's design, it may be more convenient. When the function is called you won't know which button was pressed. This is not a problem if your design is such that both buttons are not enabled at the same time! Either way the choice is yours when it comes to user defined function names. ═══ 13.4. User Functions ═══ You can use Professor Owl to add good old everyday functions to your code that have nothing to do with macro, events, or parent class virtual functions. When you select the Virtual Function item, and select the User Function event, you will be prompted to add a function. Your function can be virtual or non-virtual, and its scope can be private, protected or public. Just fill in the return type, function name and parameter list. You can use default parameters. Press the Example button for an idea of how this works. ═══ 13.5. Delete Function ═══ Functions and events can be deleted just as easily as they are added. Once the event or function is created, by selecting an item and event in the two listboxes, you can press Delete Function. If the function is in the source code, it will be deleted. To prevent the loss of code, the function is commented out. Prototypes from the header are actually deleted. Here is an example of the source file after a function has been deleted. //---------------------------------- // Event EV_COMMAND for CM_ABOUT //---------------------------------- #if 0 //DELETE_BEGIN //DELETED void MyClass::EvCmAbout(void) { // INSERT>> Your Code Here } #endif //DELETE_END "One who fears limits his activities. Failure is the only opportunity to more intelligently begin again." HENRY FORD ═══ 14. Browse Code Snippets ═══ This dialog box shows a name section and a list of snippets names. This provides two levels of catagories and make it easy to find routines. There are two files PROFOWL.DAT and PROFOWL.USR that are used to hold these commonly used snippets of code. Both files have the same format. A section name is in brackets, You can have as many sections as you want. In between each section is a code snippet. Each snippet begins with a period and a title string, after the title is the actual lines of code and/or comments. Each code snippet end with a .END marker. The begin and end staements must have the period in the first column. Code that is actually inserted or copy to the clipboard is shown in blue. [Comment Blocks] .Dashed line 20 char's long //---------------------------- .END .Big Block Comment For Function Header //*************************************************** // Function: // // Input: // // Returns: // //*************************************************** .END [Next Section] It is recomended that you leave PROFOWL.DAT alone as each new version of Professor Owl will include this file. All user code snippets should be aded to PROFOWL.USR. if you must change PROFOWL.DAT make a backup copy so when you upgrade Professor Owl, you will not loose the changed when the file is over written. Both files must reside in the home directory where Profowl.Exe is. View Clipboard starts "CLIPOS2.EXE" this file is in the X:\OS subdirectory and is part of the OS/2 operating system. ═══ 15. OWL Help From Borlands INF Files ═══ To aid you in learning the OWL class library, Professor Owl offers you a quick and convenient way to search Borlands OWLPM.INF file. Under the main help menu is a menu item to search OWLPM.INF. This function uses the VIEW.EXE (included with OS/2) to execute a command line "VIEW.EXE OWLPMINF keyphrase". The keyphrase is held in a history list for your convenience. You may also select an item function name and right click to popup a menu, under this menu you will see the OWL help item, this will serach the INF file for that function member. If you have selected a event where the function name is user defined, you will be put into the "Command Message" help screen. If you select a or class identifier section, you will be put into the "TWindow Class" section. You may also hilight text in the built-in editor and right click on the editor text to search the OWLPM.INF file on the hilighted text. For this feature to work, both VIEW.EXE and OWLPM.EXE must be in your PATH. OWLPM.EXE is located in the x:\BCOS2\BIN directory and VIEW.EXE is located in the x:\OS directory. ═══ 16. Questions and Answers ═══  Q. Professor Owl created a New Class and when I compiler I get linker errors?  A. You need to add the new class .CPP file to your project or make-file. Professor Owl does not modify the .PRJ project file only the make-file.  Q. I added a variable to my dialog, and called my dialog from a menu selection and I get a compile error on the variable from the calling class. Why ?  A. When Professor Owl add a variable (a class pointer) it includes the proper header file in the header file for that class. When you call that class from another C++ file, the may or may not be present. You may need to include the same owl header file where you are using Your Class.  Q. Where do all these CM_ constants come from ? They are not in my source files.  A. Borland has many command constants defined in the owl directory, they are used internally by the class library. You can use them too. Professor Owl uses the Borland path to scan these symbol onstants into the item list box.  Q. Professor Owl sees code in between preprocessor directives that is not compiled. Why ?  A. Professor Owl is not a compiler! It parses on a line oriented bases. It will not know what symbols are defined. Use C++ comments // to prevent it from seeing lines code you don't want.  Q. I added function to my source code using Pofessor Owl. Why don't I see these changes in the Borland Compiler IDE editor ?  A. The Borland IDE editor opens a file and holds it in memory. If the file changes on the disk it does not know. It is safest to close the file in the Borland IDE when transferring to other application that will cause hanges to that same file.  Q. How can I create a modeless dialog box that is not clipped by the parent but stays anywhere on the desktop?  A. In the Init Dialog function you need to call WinSetParent() the example code fragment below will make the parent the desktop. #define INCL_WINWINDOWMGR #define NULL 0 #include //---------------------------------- // Init Dialog //---------------------------------- BOOL MyDialog::EvInitDialog(HWND hWndFocus) { BOOL RetValue = TDialog::EvInitDialog(hWndFocus); WinSetParent(HWindow, HWND_DESKTOP,0); // Set Parent To Be The Desktop return(RetValue); }  Q. Will Turbo Debugger run with 'mouse comet' enabled ?  A. No, you must turn off the 'Comet Cursor' for turbo degugger to run properly. Open the OS/2 System Folder, Open the System Setup Folder, Open the Mouse Setting Notebook. Make sure the comet cursor is uncheck, also press the disable button. Reboot and this should fix Turbo Debugger. ═══ 17. Limitations ═══ -- Coding Styles Professor Owl like to read C++ code much like it writes it. This means functions should be on one line. Below are example of legal and illegal classes. LEGAL: MyClass::MyFunctions(int x) // OK { } ILLEGAL: // This will not work MyClass:: MyFunction( int x) { } Professor Owl Scans for ClassName :: FunctionName( to find class member functions. Spaces and tabs are ignored. Also, function closing braces Must be in column 1 as shown. void MyClass::GoodFunc(void) { ... // body } This style will also cause problems with Professor Owl. void MyClass::BadBraces(void) { // braces are not left justified ! } ═══ 18. Registration ═══ You can register your Professor Owl in may ways using the services provided by 'BMT Micro' Note: Your credit card will show BMT Micro, and not Professor Owl or Edward March. You may print the next two sections order forms and the appropriate one to the author or BMT Micro. Each registered user will receive a special serial number key code to be entered into Professors Owls registration dialog. ═══ 19. Professor Owl Order Form (Checks / Money Orders) ═══ You may print this order form  Mail To Edward J. March Jr.  1206 South Birch Drive  Mt. Prospect, IL 60056    The Author Accepts US (and Major Foreign Country) Personal Checks and Money orders  made payable to 'Edward March'. Please do not send cash  in the mail. Personal checks are subject to clearance.  ─────────────────────────────────────────────────────────────────────   Name ________________________________________________________________   Address _____________________________________________________________   _____________________________________________________________   Phone _______________________________________________________________   E-Mail ______________________________________________________________   Where did you find Professor Owl ? __________________________________   Total Enclosed: $29.95 for ═══ 20. Professor Owl Order Form (Credit Cards) ═══  Mail Orders To BMT Micro  PO Box 15016  Wilmington, NC 28408  U.S.A.   Voice Orders 9:00am - 7:00pm EST (-5 GMT)  (800) 414-4268 (orders only)  (910) 791-7052   Fax Orders (800) 346-1OS2 (1672) 24 Hours / 7 Days  (910) 350-2937 24 hours / 7 Days  Online Orders via modem (910) 350-8061 10 lines, all 14.4K  (910) 799-0923 Direct 28.8K line   Ordering and general ordering questions  Via AOL bmtmicro  via Compuserve Thomas Bradford, 74031,307  via Internet orders@bmtmicro.com  tbrad@wilmington.net   We accept Visa, Mastercard, Discover, American Express, Money Order,  Cashiers Check, Personal Check. Please do not send cash in the mail.  Personal checks are subject to clearance.  _____________________________________________________________________   Name ________________________________________________________________   Address _____________________________________________________________   _____________________________________________________________   Phone _______________________________________________________________   E-Mail ______________________________________________________________   Product Quantity Price Number of copies  ___Professor_Owl_______ _$29.95 Each__ ________________   x ____________ = + $ _______   North Carolina add 6% Sales tax ($1.80 @ $29.95) (6%) + $ _______   Total: $ _______  ───────────────────────────────────────────────────────────────────  For credit card payment only   Circle one: VISA / Master / Discover / American Express   Credit card number: _____________________________________________   Expiration date: ________________________________________________   Authorization signature: ________________________________________   ─────────────────────────────────────────────────────────────────── ═══ 21. Where To Enter Your Registration Code ═══ When you register you will be given a Serial number with your name. Select the Help Menu - Select About, Press OK, and you will see this dialog. Enter you name and serial number as given to you. This means all spaces, upper/lower case and punctuation are important. Professor Owl will create a PROFOWL.KEY file in its home directory. PLEASE DO NOT GIVE YOUR SERIAL NUMBER AWAY TO OTHERS. Profowl.exe and Profowl.ini are not modified, you can transfer these files to others to allow them to evaluate Professor Owl. Should you decide to unregister Professor Owl delete the Profowl.Key file. ═══ 22. Technical Support ═══ There are a number of ways to get help with Professor Owl. The most obvious is reading the manual. Most tech support calls can be avoided by simply reading the book. Also, Borland manuals are a great source of information on the Object Window Library classes. You can contact the author via Email, UsMail, or telephone. See the next sections. ═══ 22.1. US Mail ═══ Edward J. March Jr. 1206 South Birch Drive Mt. Prospect, IL 60056 ═══ 22.2. Phone ═══ (847) 228 - 1234 All messages will be answered with 24 hours of the next business day. ═══ 22.3. Internet ═══ Since the nature of the problems tend to be complex, we would prefer to handle technical assistance via E-Mail on the Internet. Address your technical questions to emarch@ais.net and include any code samples or files that will help diagnose the problem. -- All Email will be answered within 24 hours of the next business day. ═══ 23. Internet Information ═══  Professor Owl Home Page -- http://www.cl.ais.net/emarch  (or try http://www.cl.ais.net/~emarch) Note ~ before emarch  Bmt Micro Professor Owl -- http://www.wilmington.net/bmtmicro/catalog/prof_owl.html  Bmt Micro (general) -- http://www.wilmington.net/bmtmicro/  OWL general Info -- http://keep.ioc.ee  Borland -- http://www.borland.com Professor Owl can also be found on Compuserve's IBM OS/2 Developers Forums #1 Under Development Tools. Professor Owl ZIP files are named PFOWL108.ZIP for version 1.08 -- Look for PFOWL###.ZIP. ═══ 24. What's News In This Version? ═══ What's New In Version 1.08 Bug fix TGadgetBox is spelled correctly as TGadgetBar Browse Menu Added For Code Snippets Price Reduction Was $39.95 Now Only $29.95 !!! What's New In Version 1.07 * Fixed multiple #include in code generation. * Default window size/position is based on desktop resolution. 640x480 gives a smaller edit window, than higher resolutions of 800x600 thru 1280x1024. But all controls should be visible. * Added browse buttons to tool setup dialog. * Setup searches the PATH enviornment to find the BCOS2 installed directory and only defaults to C:\BCOS2\include if BCOS2 is not in the PATH or BCOS2 has been renamed. * CD-ROM drives without a CD inserted will no longer show the OS/2 System Retry/Fail. * Help Button added to User Setup, User Comments, user Function, Create New Class, and Create New Application Dialogs. * Class Name/File Name Is Remembered For Next Session. * Project Path will find ZIP / SYQUEST drives with removable media, * Project Path Can Be Remembered, For The Next Session. * Added Project Window modeless dialog to support files in multiple directories. * Run Tools From Project Window on specific Path\File. * Make files can be generated from the project list. * Added date/time stamp to deleted functions. * Resources can have BEGIN/END or open close braces { }. * Help Menu has OwlPm.Inf Searching Also available on right click popup menus. ═══ 25. Testimonials ═══ What some people are saying about Professor Owl. ------------------------------------------------ WOW!!!! I must say Professor OWL is way cool! I have spent the last two weeks getting a user interface going with a toolbar, messagebar, and menu with a couple dialogs and I redid "almost" the whole thing in one evening with Professor OWL. Being a newbie OWLer converting from API, Professor OWL is just what I needed. Lee R. Copp, Houghton, MI ------------------------------------------------ As a novice to OWL programming, I have found Professor OWL (together with Borland's Resource Workshop), to be indispensable in providing a structured framework that facilitates the construction of PM program interfaces. Technical help and advice from the author via E-mail has been outstanding, and has even surpassed levels of assistance normally expected or recieved in commercial software support. The software that I use on a daily basis includes only a small select group of quality shareware programs; Professor Owl definitely has earned its place in this exclusive group. Leslie G. Thompson Associate Professor of Petroleum Engineering University of Tulsa 600 S. College Avenue Tulsa, OK 74104 ------------------------------------------------ "Sufficiently advanced technology is indistinguishable from magic." ARTHUR C. CLARKE I hope Professor Owl is doing its magic for you! To all Professor Owl users (Registered and Unregistered). If you would like your testimonial added please email or write me. I look forward to hearing from you. Thank-You