The history of all hithero existing society is the history of class struggles.
Karl Marx/Friedrich Engels

Release 1.0 (Offical Version)


(1. Apr. 1998)

© Stefan von Brauk, Jens von Pilgrim, Thomas Bonk, Mathias Hasselmann, Jan-Helge Bergesen 1996, 1997, 1998

The Open Objects Library (OOL) is a C++ library wich contains classes for GUIs, datatypes, multimedia and more. To use OOL it is an advantage if you have some experiance in programing using class-librarys and/or OS/2-API functions.

After very nice tests in "c´t magazin" 10/96 and "Software Entwicklung" 11/96 we proudly present the newest release of the library, still very stable, but much more functionality (see History/Changes).

Currently only the most modern operating system (OS/2 Warp 3 or higher) is supported, for ports to Windows NT/95® and LINUX see FAQs.

Highlights in this version

If you are already using the OOL please read History/Changes first, it might be nessecary for you to make some changes porting your applications to the new OOL release.

Contents

Thanks

In the last months we had support from different people. Special thanx to:

License

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
  1. The Open Objects Library (OOL) is copyrighted freeware
  2. Redistributions of any files must retain the above copyright notice, this list of conditions and the following disclaimer.
  3. You are not allowed to sell or commercially distribute the OOL or any part of it. If you want to distribute the OOL commercialy you have to apply the authors permission.
  4. If you want to distribute the OOL with another product you have to apply the authors permission.
  5. If you want to reprint sourcecode of the OOL you have to apply the authors permission.
  6. To keep applications small, please use the OOL in your programms in the form of the DLL(s) distributed with this package. Static linkage is only allowed if you have problems using excepitons. In this case you have to say in your online- and offline documentation that your application is build with the OOL. Distribution of self-constructed DLLs is not allowed!!!
  7. You are not allowed to commercialy distribute programms which base on the examples distributed with this package.
  8. You must send a copy of every programm which you have developed with the OOL to the authors of the OOL (to test and enjoy ;-) ).

BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

Back to Titlepage

Trademarks and Service marks

The following terms used in this publication are trademarks or service marks of IBM Corporation in the United States or other countries:

Windows is a trademark of Microsoft Corporation.

UNIX is a registered trademark in the United States and other countries licensed exclusively through X/Open Company Limited.

Java is a trademark of Javasoft.

Other company, product, and service names may be trademarks or service marks of others.

Some code of the OOL is based on software which underlies the General Public License (GPL), the original code is distributed in the directory OOL\ORIG, see there for further information about the GPL.

The Future of the OOL?

As you may have noticed IBM isn't interested in the SOHO market any more and only supports theire professional custumors of Warp and Warp Server. From this reason there seams no need for a freeware class library for OS/2 Warp (professional users work with Visual Age/OCL).

To make it clear: at the time the OOL is (nearly) complete, the platform it is designed for is dead.

So, what is the future of the OOL? Port it to Windoze/Linux/Rhapsody (and who will do the wet work)?

We need Help!

Writing a class-library needs a lot of time and know how. If you inspect the OOL-project you will see that a lot of functionality is implementated but also a lot of things are missing. If you have time and the know how to:

you should contact the authors, subject: Its Me!

Back to Titlepage

We give Help!

Yes, we know: Using a class-library you have a lot of questions without an answer. Therfore we offer COMMERCIAL SUPPORT. For more informations on commercial support contact the authors, subject: help!

There is also a OOL specific mailing list avaible:

Subscribe

To subscribe to the mailing list send an EMail to majordomo@wg.saar.de, the body of the mail must only contain subscribe ool-list

Unsubscribe

To unsubscribe to the mailing list send an EMail to majordomo@wg.saar.de, the body of the mail must only contain unsubscribe ool-list

Help for mailing-list

To get help for the mailing list send an EMail to majordomo@wg.saar.de, the body of the mail must only contain help

Send mails to the mailing-list

To send questions, answers or disussion-text to the mailing list, send your EMail to ool-list@wg.saar.de

Online documentation

Frequently updated online help is avaible at http://ooldoc.home.ml.org/

Back to Titlepage

Bug reports

If you think you found a bug in the library:
  1. Make sure that you use the class/function correctly
  2. Read the documentation of the function/class and the documentation of all parent classes
  3. Return to number 1
  4. Read the header-file of the class and return to number 1
  5. RTFM
  6. Make sure that the error is a bug, not a feature
  7. Try to locate the error in the library
  8. Try to fix the error yourself
  9. If you have fixed the error send your solution to the author of the class, otherwise send a description of the error to the author. Usualy you find the EMail adress of the author in the header-file of every class.

Back to Titlepage

Overview

Installation and Requirements

The following sections describe how to install for the different supported compilers and the additonal requriements.

If you use the OOL graphic library (OOLGLIB) it is always required that

are installed on the machine you develop and on the machines your application should run. OOLGLIB works compiler independent, the sources of the DLLs are only distributed (and build) with the EMX-package of the OOL, the DLLs itselfs are part of the main OOL package (OOL\LIB\..)

Installation for EMX/GCC

To develop using the Open Objects Library (OOL) you need the EMX package 0.9c for OS/2, additional the EMX runtime-package (the multithreading DLLs) must be installed on the target system(s). The makefiles delivered with OOL are for GNU MAKE, if you want to use them you need to install GNU MAKE.

To get full access to all functions you need the header files of the developers toolkit (IBM) (don´t forget to enable them in os2emx.h and to add them to the CPLUS_INCLUDE statement in your config.sys), you need this files too if you want develop DIVE-related applications. If you use EMX with IBM header files you have to disable the structure-definition PRINTDEST you find in the file OOL\INCLUDE\XINCLUDE, line 41.
If you don´t want to install the header files of the developers toolkit you cannot use the REXX-interface of the OOL. In this case you must modify the file OOL\INCLUDE\XINCLUDE: Delete the line

#include "rexxsaa.h"

in the file, otherwise you will not be able to compile without errors.

If you want to use Multimedia-related classes, you need the multimedia extensions for EMX (MM4EMX). In this case MMOS/2 must be installed on the system you develop and on the system(s) your applications should run. If you want to use the DIVE-classes you need the header files of the developers toolkit (IBM).

To rebuild the library you need the header files of the developers toolkit (IBM). Additionaly some import librarys must be build from the toolkit. Therefore some simple rexx-scripts are delivered in the directory OOL\TOOLS. To build the librarys change to the lib-directory of the toolkit and run the following scripts:
Function Rexx-Filename Output
rexx import rexxlib.cmd rexx2emx.lib
java-support javalib.cmd java2emx.lib
multimedia-support (including DIVE) mm.cmd mm2emx.lib
new OS2 import library oolimp.cmd oolimp.lib
Copy the libs to your EMX libpath eg. c:\emx\lib

If the OOL-files are zipped, unzip them and copy them to the place you want to. Copy the DLLs to a directory of your LIBPATH, for example C:\OS2\APPS\DLL. At least change the settings of EMX in the config.sys. Just add the following line to the CPLUS_INCLUDE_PATH statement:

PATH/ool/include;

where PATH ist the path you have copied the OOL-files to. For example,the complete statement looks like

SET CPLUS_INCLUDE_PATH=c:/emx/include/cpp;c:/emx/include;c:/emx/ool/include;

Now add the following line to the config.sys:

SET OOL=PATH;

where PATH is the path where you have copied the OOL-files to.

Finaly copy the LIBs which are shipped in this package to the LIB-path of EMX, for example c:\emx\lib. (dont forget to reboot!)

Known problems
Because exceptions are used you MUST DISABLE ANY FORM OF OPTIMIZATION (eg. -O or -O2), otherwise in the best case your program crushes if an exception is thrown, usualy you have several problems to link your program. You may have problems with the samples if an exception is thrown (excpecialy sample9)

In the DIVE-related header files of the OOL a multimedia related macro is redefined to make it work with EMX. If the compiler throws some warnings, ignore them.

Back to Titlepage

Installation for Visual Age C++

If you want to use Multimedia-related classes, MMOS/2 must be installed on the system you develop and on the system(s) your applications should run, the toolkit for multimedia related stuff must be installed on your system.

If you want to use XWebView, the DLL webexwin.dll must be installed on the system you develop and on the system(s) it should be used (the DLL is part of the WebExplorer). If you want to develop the XWebView you need the WebExplorers toolkit additionaly.

If the OOL-files are zipped, unzip them and copy them to the place you want to. Edit the settings of VAC++ in the config.sys:



where PATH ist the path you have copied the OOL-files to.

Now add the following line to the config.sys:

SET OOL=PATH;

where PATH is the path where you have copied the OOL-files to.

If you want to develop the OOL, process installation described above. Additional you must change the paths given in the makefile of the OOL (..\OOL\SOURCE\VA.MAK), MAKE will then copy the created files to the place you need them.
The library contains a C runtime library for VisualAge C++. To keep your applications small and fast you should include this library instead the VisualAge librarys. To compile use the /Gn+ /Gd+ switches, your applications must be linked against the C runtime library (OOLC3I10.lib) and os2386.lib, switch /NOD. The runtime library DLL OOLC3I03.DLL must in the current LIBPATH and must be delivered with your application.

Known problems
If you rebuild the OOL Visual Age C++ should be on the most recent fixlevel, BUT: I wasn't able to build the C-runtime library with the CPPOMO30.DLL of fixpack 8 (I used the original DLL instead).

Back to Titlepage

Installation for Watcom C/C++

Currently we have some problems with Watcom 10.x so the librarys and DLLs for this compiler are not distributed (the makefiles for the compiler are part of the package so you are able to build these files yourself).

To develop using the Open Objects Library (OOL) you need Watcom C/C++ 10.0 (or higher) and a Developer's Toolkit 3.0 (or higher). If you want to use Multimedia-related classes, MMOS/2 must be installed on the system you develop and on the system(s) your applications should run, the toolkit for multimedia related stuff must be installed on your system.

If you want to use XWebView, the DLL webexwin.dll must be installed on the system you develop and on the system(s) it should be used. If you want to develop the XWebView you need the WebExplorers toolkit additionaly. Please note that you have to use the edited webexwin.h header file, which resides in the OOL include directory. I had problems with the original file: wlink wasn't able to find the WebExWin functions.

If the OOL-files are zipped, unzip them and copy them to the place you want to.
Edit your config.sys:

Where PATH is the drive- and pathname where you've copied the OOL to.

If you want to recompile the OOL change to your OOL directory and type

nmake -f watcom.mak

You're also able to make the dll's and the samples separate; only change to Source or Samples directory and type
nmake -f watcom.mak

Known problems
Under Warp 3 and the Toolkit that came with DevCon#10, wlink wasn't able to find the function mciSendString allthough it is exported in MMPM2.LIB; so I wasn't able to compile OOLM3W03.DLL under Warp 3. Under the Warp 4 beta along with the Toolkit for Warp 4 (from the beta June 1996) it compiled and linked fine. So I compiled and linked the OOL under Warp 4; both dll's also work under Warp 3.

Back to Titlepage

Debugging features

The OOL contains some simple aids to make debugging a little more easier.
  1. XConsole is a class like the console of Java, it shows you which things are printed to STDOUT and STDERR. To invoke the console the first line of your main()-routine should be 
      XConsole::CheckConsole(argc, argv);
    Additionaly your application must be started with '-console' as an argument.
  2. The OOL contains also a simple memory-observer which observes the C-functions memcpy(), strcpy(), malloc() etc. To enable this function you need to define DEBUG at the begining of you code, then create an instance of XMemoryCheck in the main()-function. Don't include 'string.h' or 'stdlib.h', these files are included by the OOL.
To enable this debbuging-tools your main()-function should look like: 
//first lines:
#define DEBUG
#define INCL_OOL
#include "ool.h"

void main ( int argc, void ** argv)
{
   try
   {
      XMemoryCheck memObj;
      XConsole::CheckConsole(argc, argv);
      //if you want to check if the meory-observer is running:
      char * s = (char*) malloc(12);
      strcpy(s, "12345678901");
      strcpy(s, "not freed 1");
      strncmp(s, "123", 10);
      strcat( s, "1234567890");
      char * n = (char*) malloc(20);
      strcpy(n, "not freed 2");
      char * x = (char*) malloc(0);

      //here enter your code (and don't forget the -console switch)
      MyAppWindow * window = new MyAppWindow();
      XApplication::GetApplication()->Start();  //let the application work
   }
   catch( XException e)
   {
      e.ShowError();   //shit
   }
}

Things which dont work

Toolbars

If a toolbar has the style TB_RIPABLE and the user rips the toolbar and plug it eg. at the left of the window the content of the toolbar might not be shown correctly if you have set X- or Y-offsets to the controls of the toolbar. In this case you should disable TB_RIPABLE

Graphic output

The classes for painting are updated, but can make some trouble. Be careful.

Custom Controls

We have started to implement some custom-controls (XChart and derived classes). Functionality is reduced, wait for the next release.

What the samples show you

Sample1

Sample 1 is a little intro, it shows multithread-programming, building simple application windows, introduction in drag/drop and in the handler-concept of the OOL.

Sample2

How to use DBase III-classes

Sample3

Sample3 shows how to use the multimedia-interface of OOL, how to use he bubble-help. NEEDS MMPM/2

Sample4

Sample4 is an introduction into container-programming (the windows, not the collections!). More about handlers and drag/drop.

Sample5

Sample5 shows how to construct windows from resources (which are build with the dialog-editor), including a resource DLL.

Sample6

Sample6 shows how to use controls which are not so often used like: XNoteBook, XUserButton, XValueSet, XSlider, XCircularSlider..

Sample7

Sample7 is an introduction to use graphic classes and how to print.

Sample8

How to use DDE: client and server-application wich communicate via DDE

Sample9

Using named pipes (client/server) and semaphores

Sample10

Bitmap viewer

Sample11

Run Java applets in your C++ application

Sample12

Using REXX within a C++ application

Sample13

Example of the DIVE-interface

Sample14

How to use modeless and modal dialogs.

Sample15

Example of the Multiple Document Interface (MDI).

Sample16

How to use socket-classes.

Back to Titlepage

Hints

Including headers


There are two methods to include header files of the OOL in an easy way:
  1. To include all header files at once (useful if you work with precompiled header) 
    #define INCL_OOL
#include "ool.h"
  2. To include header-files one by one include the standard header of OOL (xheaders.h) and then include the header-file of the class you want to use by typing the classname with the suffix "_i", for example:
    #include "xheaders.h"        //the standard header of the OOL
#include XFrameWindow_i      //class XFrameWindow
#include XMenuBar_i          //class XMenuBar
//and so on

To improve perfomance in some header-files functions are inlined, dont touch them!

compiling/linking


You have to compile/link your programms multithreaded because the OOL - DLLs are build multithreaded too (otherwise you will have problems to start your application).
Refer to your compilers documentation.

Destructors


Destructors of windows, menus, toolbars etc are called automaticaly => never call the destructor of a window!
From this reason you must be carefull with constructions like the following:

//wrong way:
void xyz(void)
{
  XMenuBar menu(...);  //the menubar is constructed
  blabla               //do something
                       //the destructor of XMenuBar is called when the
                       //function is left and the menu is destroyed!
}
//correct:
void xyz(void)
{
  XMenuBar * menu = new XMenuBar(...);   //the menubar is constructed
  blabla                                 //do something
                                         //the destructor of XMenuBar is not called!
                                         //the destructor of XMenuBar is called when
                                         //the user requests closing the associated window
                                         //automaticaly.
}

Back to Titlepage

Create new window classes

After programming a while with OOL you may need to create new window classes. There are two methods to do this:

Templates

The OOL does not contain templates/container classes because the Standard Template Library (STL) is a new standard in C++ and contains lots of fast templates.
Click here to download the STL.

Other

Exception-Handling

The OOL throws exceptions (class XException and derived) under folowing circumstances: Refer to the sample how to catch exceptions. If the methods throwing exception are documentated you usualy find a description of the type of the thrown exception in the docs.

EMX ONLY: Since the OOL is compiled with the -fhandle-exceptions switch you can use exception-handling in your applications if you use OOL. Because exception-handling of EMX/GCC does not work correctly, you may have some problems to catch exceptions from the OOL.

DLL-Naming conventions

DLLs and LIBs of the OOL project follow these naming-conventions, you must decide which library(s) you need to include in your project (depending on the compiler you use and which modules of the OOL you need).

The letters of the names of the OOL-Librarys/DLLs have the following meaning:
1 - 3
always
"OOL"		4
module index		5
operating system		6
compiler		7 - 8
version		meaning
-"C"---C runtime library (only for VisualAge C++ avaible)
-"W"---window-related stuff, the main module
-"M"---multimedia-extension (since Release 1.0 part of the main module)
-"T"---TCP/IP related
-"J"---Java related stuff
-"1"---DB2/2 database class (XTable) (removed from Release 1.0)
-"2"---DBase III database classes
--"3"--OS/2 Warp 3/4®
---"E"-EMX/GCC
---"I"-IBM Visual Age C++ 3.0®
---"W"-Watcom C/C++®
----"01"alpha release 1
----"02"alpha release 2 (no public version)
----"03"Beta 1
----"04"Beta 2 (no public version)
----"10"Release 1.0 (this version)
Always needed is OOLRES.DLL which contains dialog-templates for printer-support and other resources.

History/Changes

Back to Titlepage

FAQs

  1. Will you port the OOL to LINUX (would be great)?

    Yes, would be great. A basic port to Win95/NT is done (frame-windows, simple controls etc.), but we don't have the time to do the ports to other plattforms.
    If you would like to port the OOL to other plattforms,     mail!.

  2. What is AutoDoc?

    AutoDoc is a tool to create documentation automaticaly :-)
    It creates program-documentation in HTML-format out from C/C++ sourcecode including derivation and comments inserted by the programmer. Shareware-version (perhaps) soon avaible!

  3. And what is Object WorkFrame?

    Object WorkFrame is a Visual Age-like workframe for programmers, HTML-developers etc (Shareware). It contains a C++ class-browser, an utility to create makefiles and a find-utility. Download from Hobbes or LEO (OWF.ZIP).

  4. Where is OS2ME.H?

    EMX ONLY: OS2ME.H is a file from the multimedia-extensions for EMX, you need to install them to compile multmedia-related stuff. The file MM4EMX.ZIP should be found on the Hobbes-CD or on every server which distributes EMX.

Back to Titlepage