##### The history of all hithero existing society is the history of class struggles.

##### Karl Marx/Friedrich Engels

## Beta 1 (including Fix 1)

#### (16. April 1997)

© Stefan von Brauk, Jens von Pilgrim, Thomas Bonk 1996,1997

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).

Because we´ve just started to develop this library only the most modern operating system (OS/2 Warp 3 or higher) is supported, ports to Windows NT/95®. and LINUX will start spring/summer 1997 (refer to FAQs for details)

### Highlights in this version

- Compiler-support for Visual Age C++®, Watcom® and EMX/GCC
- New classes for DDE, (named) pipes, notebooks, Apple® style bubble-help and more
- access the World Wide Web with OOL
- DB2/2 access with OOL
- Run Java applets in your C++ application
- Printer class
- mailing list, see We give help / mailing list

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
- License
- We need help!
- We give help / mailing list
- Bug reports
- Overview
  - class index
  - Installation
    - Installation for EMX/GCC
    - Installation for Visual Age C++
    - Installation for Watcom C/C++
  - Things which dont work
  - What the samples show you
  - Hints
  - Create new window classes
  - Templates
  - Other
    - Exceptions
    - DLL naming conventions
- History/Changes
- FAQs

### Thanks

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

- E. Mattes for EMX and for answering our questions
- Benjamin Stein for supporting us in multiple ways
- Fabrizio Aversa because we can use some code of his MAVERIK CLASS LIBRARY

### 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

### 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:

- implement graphic-classes (OpenGL)
- implement TCP/IP-classes
- implement classes for data-propagation (XDocument?)
- improve already existing classes
- improve documentation
- port the OOL to other compilers ( Borland...)
- or port the OOL to other 32bit-plattforms (Linux, Windows NT®., Atari ST, AIX®....)
- or......

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 question, answers or disussion-text to the mailing list, send your EMail to ool-list@wg.saar.de

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

#### 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" (line 32).

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 DLL(s) 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 source compiled with EMX/GCC cannot be linked against the WebExplorers library without errors the XWebView is not avaible in the OOL for EMX/GCC. From the same linking-problems the XTable class for DB2/2 access is not avaible for EMX.

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:

- SET INCLUDE=PATH\include;...
- SET LIB=PATH\lib;...
- LIBPATH=PATH\lib;...

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.
To rebuild the DLL for DB2/2 access you need to modify the makefile. Replace the given database name where SQLPREP/SQLBIND is called with your database name.

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 (OOLC3I03.lib) and os2386.lib. The runtime library DLL OOLC3I03.DLL must in the current LIBPATH and must be delivered with your application.

WARNING: You may have problems including header files like described in Overview. In this case you need to disable the option "Use Precompiled Header" in your project.

Back to Titlepage

#### Installation for Watcom C/C++

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:

- LIBPATH=PATH\lib;...
- SET INCLUDE=PATH\include;...
- SET LIB=PATH\lib;...
- SET OOL=PATH

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

### 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

Sample2 shows how to use toolbars, controls (buttons, listboxes etc), using online-help (XHelpInstance), using the WebExplorer-control
NEEDS MMPM/2 AND WEBEXPLORER TOOLKIT (does not work with EMX)

#### 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

Access data from DB2/2 (does not work with EMX and Watcom C/C++, needs a DB2/2 or client installed)

#### 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.

Back to Titlepage

### Hints

#### Including headers

To include header-files use this simple method: 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
    #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 -> only call a destructor if you want to destroy 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:

- You want to create a class with a window-type wich is known from the OS, e.g. a window-type wich is registered from a DLL. In this case you need to know with which name that window-type is registered (a value like WC_* ). You should derive the C++ class from XControl and override all functions from XWindow/XControl you need to handle the window. The OOL class XWebView is a good example to create new classes in this manner.
- You may create a complete new class. In this case you have to handle nearly everything, escpacialy drawing the window. Derive your C++ class from XUserWindow, override Draw() and all other methods you have to handle. There a some classes in the OOL which show you how build window-classes yourself: XToolBar, XBubbleHelp, XChart and XPie.

### Templates

The OOL does not contain templates because the Standard Template Library (STL) is a new standard in C++.
Click here to download the STL.

### Other

#### Exception-Handling

The OOL throws exceptions (class XException and derived) under folowing circumstances:

- A window, control, framewindow or menu could not be created
- A resource-library could not be loaded
- In class XTable on every error an exception is thrown
- A rexx-interface could not be created

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 (not possible in earlier versions of 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 (only required for apps which use the multimedia classes: XVideo, XSound, XGraphicButton) and DIVE classes.
- | "T" | - | - | - | TCP/IP related, actualy only XWebView (not avaible for EMX/GCC)
- | "J" | - | - | - | Java related stuff
- | "1" | - | - | - | DB2/2 database class (XTable) (not avaible for EMX/GCC and Watcom C/C++)
- | - | "3" | - | - | actualy only 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 (this version)

Always needed is OOLRES.DLL which contains dialog-templates for printer-support.

### History/Changes

- Beta 1
  - Support for Visual Age C++®. and Watcom®.
  - changed to EMX 0.9c
  - the library is split in multiple DLLs, new DLL-names
  - the OOL throws exceptions
  - "empty" classes are now "filled", means they have now some or many member-functions (e.g. XValueSet)
  - some new classes avaible:
    - Window related:
      - XBubbleHelp
      - XExtendedMessageBox
      - XFontDialog
      - XIcon
      - XJavaApp and related
      - XModalDialog
      - XModelessDialog
      - XNoteBook
      - XNoteBookPage
      - XWebView (not avaible for EMX)
    - Multimedia
      - XBlitterWindow and related (DIVE)
    - Communication/System related
      - XDDE
      - XEventSemaphore
      - XFileInfo
      - XMutexSemaphore
      - XNamedPipeClient
      - XNamedPipeServer
      - XPipe
      - XPrinterDevice
      - XProfile
      - XRexxInterface
      - XTimer
    - Database access
      - XTable (not avaible for EMX and Watcom C/C++)
    - Other
      - XException
      - XRexxException
      - XSemaphoreException
      - XTableException
  - most classes have new member-functions (e.g. XFile, XEntryField, XComboBox)
  - bug(s) fixed in: XUserButton, XContainerEditEvent, XContainerControl, XGraphicDevice, XGraphicObject, XBitmap, XText, XString, XMultiLineEntry, XKeyboardHandler
  - graphic classes (XGraphicObject and derived) are updated and can be used carefuly, functionality is still pour
  - direct editing in container-controls supported (see sample4)
  - user-defined drawing in listboxes and menus supported (see sample6), also in container-controls (sample4)
  - the names of member-functions have been modified:
    1. the name of a function wich set data now starts with Set, example: SetText

    2. the name of a function wich retrive data now starts with Get, example: GetText, in earlier versions of the OOL they often started with Query

    3. the name of a function wich ask for a boolean state now starts with Is, example: IsVisible
  - XContainerHandler must now be attached to the container-controls, not to their owner (Sample4), so XContainerHandler::GetWindow() in container-event returns the control, not the owner!
  - XPopupMenu can now be constructed with XWindow or a derived class
  - DoSize has now two parameters, you must change your apps if you have overriden DoSize (otherwise DoSize is never called).
  - If in a constructor of XFrameWindow() or derived WIN_VISIBLE is not set, the window is not displayed.
  - Parameters in XFile::Open() changed!
  - new samples:
    - sample6 - rare-used controls, notebooks
    - sample7 - using graphic objects and printer
    - sample8 - using DDE
    - sample9 - using named pipes
    - sample10 - DB2/2 access
    - sample11 - Java support
    - sample12 - Rexx interface
- alpha release 2 (not documentated)

Back to Titlepage

### FAQs

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

   Yes, would be great. Ports to LINUX and Windows 95/NT®. will start in spring/summer 1997, if you want to support us, mail to:

   - Jens for LINUX
   - Stefan for Windows NT/95®.

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 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 (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