OS/2 Shareware BBS: 10 Tools/10-Tools.zip/krcls012.zip/KrClass/doc/krclguid.INF

OS/2 Help File | 1997-02-25 | 20KB | 474 lines

ΓòÉΓòÉΓòÉ 1. About this guide ΓòÉΓòÉΓòÉ

Kroni's Classes
Version 0.12

--  A class library for lazy PM programmers  --

User's Guide


 Software requirements:    OS/2 Warp and Visual Age C++.

 Hardware Requirements:    none (anything which runs Warp and VAC++ is good enough).

Please read the file readme.1st and the copyright notice before you go on!


ΓòÉΓòÉΓòÉ 1.1. Copyright notice ΓòÉΓòÉΓòÉ

Kroni's Classes -  License.

You may:

     make and distribute as many copies of the complete archive as you want.
      When doing this, the archive must always stay complete and may not be
      changed in any way.

     install the software on one computer and run all .exe files.

 If you are not registered, you may not do anything else with the software,
 including studying of the source code.

 To register, you must write your full name and the version number of Kroni's
 Classes on a postcard and mail it to the author.

 If you are registered, you get the following additional rights:  You may

     use the source codes for studying

     use and change the software to write your own programs

     distribute compiled versions of your own programs

     distribute source codes of your programs that include parts or all of
      Kroni's Classes if you also include the copyright notices that are placed
      at the top of all original source code files of Kroni's Classes.

 NOTE THE DISCLAIMERS.


ΓòÉΓòÉΓòÉ 1.2. DISCLAIMERS ΓòÉΓòÉΓòÉ

NOTE THESE DISCLAIMERS:

I release this software "as is". Use it completely at your own risk. I can not
be hold responsible for any damage which is inflicted directly or indirectly to
you or other persons or objects in any way by bugs or unexpected behaviour of
Kroni's Classes. If you do not accept this, you are not allowed to use the
software at all. If these conditions are illegal in your country, it is not
allowed to use the software in your country at all.

I wrote this software completely on my own. However, in some countries, even
simple algorithms might be copyrighted. This means that in some countries I
might not have the right to grant you the above rights. If this is indeed the
case in your country, it is not allowed to use the software in your country at
all.


ΓòÉΓòÉΓòÉ 1.3. Contacting the author ΓòÉΓòÉΓòÉ

The author's name and address are:

Wolfgang Kronberg
Richard-Linde-Weg 16a
21033 Hamburg
Germany

Please send your registration to this address.

Registered users may also contact the author using this e-mail address:

[e-mail]

Please keep mails to this account small (<10k).


ΓòÉΓòÉΓòÉ 1.4. Where to get Kroni's Classes ΓòÉΓòÉΓòÉ

I will always upload the latest version of Kroni's Classes to

ftp.leo.org/pub/comp/os/os2/leo/devtools/libraries ,

and I will use krclsxyz.zip as the filename, where x.yz is the version number.

In addition, you'll most likely find Kroni's Classes at these places:

hobbes.nmsu.edu  (ftp- and www-server)
GfD-Net      (filenet based on fido technology)
Bite Hamburg   (Mailbox, modem: [phone])
Amt Winsen    (Mailbox, modem: [phone])

However, the latest version may take some more time to arrive there.


ΓòÉΓòÉΓòÉ 1.5. Introduction ΓòÉΓòÉΓòÉ

This class library is by no means professional software. I wrote it to suit my
own needs. I do hope, however, that some other people have at least partly the
same needs, and for those it is that I documented and released this software. I
don't want to have money for it, but I want your help in eliminating bugs and
flaws so that the whole community will benefit from it, and I want to know if
there are at all people needing this software, so please don't forget to send
me your postcard. I won't publish updates of this software if I don't get
enough of them.

This guide should help you through some items, but it is by no means complete.
Use it together with the reference guide and the demo programs to find out all
about the use of Kroni's Classes.

Now go write your programs and have fun!


ΓòÉΓòÉΓòÉ 2. Compiling and linking your programs using the IBM Workframe ΓòÉΓòÉΓòÉ

You can compile and link the programs that use Kroni's Classes just like any
other program, with the following exceptions:

     Since Kroni's Classes are based on the UICL, you must activate
      multithreading, e.g. on Options/Compile/Object/Multithread.

     Since your programs need the header files from Kroni's Classes, you must
      add a path to them (x:\...\KrClass\include) to your include path, e.g. on
      Options/Compile/File/Options/Command line include path.

     Since the Linker must be able to find the library (in
      x:\...\KrClass\lib), you must tell it where to look for it, e.g. by
      adding the full name (e.g. x:\...\KrClass\lib\krclas.lib) to
      Options/Link/Filenames/Libraries to use.

     Always use the correct version of the library! Depending on whether you
      use dynamic linkage and/or debugging information, the library must be
      recompiled using different options. For your convenience, the
      installation program creates libraries for all cases and gives them these
      names:

        -  krclas.lib  (dynamic linkage, no debuging information)

        -  krclasd.lib  (dynamic linkage, with debuging information)

        -  skrclas.lib  (static linkage, no debuging information)

        -  skrclasd.lib (static linkage, with debuging information)

 Of course, all other settings must still make sense, e.g. you must link your
 program as a PM program.

 Please remember that linkage and debugging settings have vast influence on the
 size of the generated code. When you write programs for yourself, you should
 use dynamic linkage. Even when you distribute your programs, you should
 consider dynamic linkage. See "Managing Libraries", "Packaging the Visual Age
 C++ Runtime Libraries" in the Visual Age C++ User's Guide and Reference for
 more information.

 Also, consider using a make file like the one in the demo directory instead of
 or in addition to the Workframe, since this takes care of all the above.


ΓòÉΓòÉΓòÉ 3. Basic KrClass objects ΓòÉΓòÉΓòÉ

All public objects and include files are preceeded by "Kr" to show that they
belong to the KrClass library. Private symbols not intended to be of any
importance to the user start with "_Kr". I hope that this way, they don't
interfere with any other class libraries.

The next few pages will explain some of the basic tasks that can be done using
Kroni's Classes.


ΓòÉΓòÉΓòÉ 3.1. The asynchronous main() function ΓòÉΓòÉΓòÉ

#include "krasyncm.hpp"

One of the biggest problems for beginners in PM programming is the fact that
the programmer has to actively give OS/2 the chance to do even basic things
like drawing the application's windows. That means that you can't just wait for
user input in main() and then continue doing some work in main(). You have to
actively leave main() to draw the window which will let the user do some input.

The KrAsyncMain class works around this problem by letting you define your own
main() function, which will then run in a seperate thread, while all the other
tasks are still taken care of. Since the asynchronous main() function runs in
idle priority, it will always give way to important things like screen
redrawing of your program (or of others), but it will also take all so-far
unused CPU time.

Your main function will consist of a huge switch() construction, of which only
one branch leads to the "main() code" itself. The other ones give you the
chance to delay actions till the one you're just working at is done, and to
react to user input.

To write your own asynchronous main() function, do the following:

   1. Define a class which inherits from KrAsyncMain and forwards its
      constructor.

   2. Define the virtual function main() of this class.

   3. Put a switch() statement in there as shown in hello.cpp.

   4. Add more case statements to be able to post commands from within your own
      main() function to make sure that other parts of it are executed later.

   5. Add case statements for window IDs of controls like Menues and
      PushButtons to be able to react to user command input like shown in
      ini.cpp.

   6. Create an instance of your new class directly before calling
      IApplication::current().run().


ΓòÉΓòÉΓòÉ 3.2. The common text output window ΓòÉΓòÉΓòÉ

#include "krcto.hpp"

Especially when writing software that is not supposed to be published, it comes
in extremely handy to use the common stream output mechanism to output text on
the screen. Unfortunately, this won't work in PM programs since they don't have
an appropriate text window by default.

The KrCommonTextOutput class uses a multi line edit control for this purpose.
It inherits from IMultiLineEdit and can be treated exactly like other
IMultiLineEdit objects. It features an ostream object which can be used for
output in the very same way all other ostream objects (e.g. cout) can be used.

To include a common text output window in your program, do the following:

   1. Create the main window or the canvas you want to put the text output
      window into.

   2. Create an instance of KrCommonTextOutput using the IWindow object you
      created in step 1.

   3. The output stream can now be accessed using this instance's member
      function "stream()".

 To assign the stream to any ostream_withassign object (e.g. cout), do the
 following:

   4. Use the operator "=" to assign the stream.

   5. Set the flag "ios::unitbuf" on your target stream using the member
      function "setf()" of the target stream.

 Note:   This class is not suitable for large output or professional sorftware,
         since it is rather slow and produces flickering during output. This is
         a restriction of the class IMultiLineEdit this class is based on.


ΓòÉΓòÉΓòÉ 3.3. The windowed communication class ΓòÉΓòÉΓòÉ

#include "krwc.hpp"

To implement user input turns out to be even more difficult than user output in
PM environments. The only acceptable way is to present the user a dialog window
in which he may enter the input. The class KrWinComm constructs such dialogs
from almost common stream input.

To prepare your program for user input via KrWinComm, do the following:

   1. Create an instance of KrWinComm.

 This needs to be done only once in your program.

 To prepare a variable for input from the user, do the following:

   2. Optionally, use the << operator with the previously created KrWinComm
      object and a string to define a text which informs the user about what he
      is supposed to type in.

   3. Use the >> operator with the previously created KrWinComm object and the
      variable, just as you would do if you were using cin instead of the
      KrWinComm object.

 To actualy display the dialog with all previously defined variables and change
 their values if user leaves the dialog by pressing OK, do the following:

   4. Use either the >> operator or the << operator with the previously created
      KrWinComm object and the manipulator display.

 Note:   Step 3 works only with objects derived from one of these classes:

     IString

     double

     unsigned long

     signed long

     KrBitfield

     KrChoice

     KrUserDataField

 With some work, it is also possible to input variables of other types.


ΓòÉΓòÉΓòÉ 3.4. The printer class ΓòÉΓòÉΓòÉ

#include "krprint.hpp"

Though the UICL provides some support to draw graphics on the screen, it does
nothing to help the user print his art. The KrPrinter class acts very similar
to the UICL class IDrawingCanvas, except that it does not show the contents of
its IGraphicList on the screen, but outputs it on a printer instead, thus
solving this problem.

KrPrinter can use any printer installed in the OS/2 system. It also lets the
user both choose the printer he wants to print on and change its settings.

To add printer support to your program, do the following:

   1. Create an instance of the KrPrinter class.

 Initially, all printer output will go to the system's default printer using
 its default settings. To present a dialog to the user so that he is able to
 change this, do the following:

   2. Call the printDialog member function of the previously created KrPrinter
      object. You may call this function at any time and as often as you want
      to.

 To actually print someting, do the following:

   3. Create an IGList object holding all the graphics you want to print.

   4. Select the IGList object into the KrPrinter object by calling the member
      function setList of your KrPrinter object.

   5. Call your KrPrinter object's member function print.


ΓòÉΓòÉΓòÉ 3.5. Drawing bitmap cached ΓòÉΓòÉΓòÉ

#include "krbwin.hpp"

If you have ever put a large IGList into your IDrawingCanvas, you will most
likely have hated the very long time the system needed for redrawing whenever
you moved any window in front of your graphics output window. You can now get
rid of this by drawing into a memory bitmap and then putting this memory bitmap
instead of all the time-consuming graphics primitives into your IDrawingCanvas.

To create a memory bitmap, do the following:

   1. Create an instance of KrMemoyBitmap.

 To draw into the memory bitmap, do the following:

   2. Create an IGList object holding all the graphics you want to display.

   3. Select the IGList object into the KrMemoyBitmap object by calling the
      member function setList of your KrMemoyBitmap object.

 To draw the memory bitmap's contents on the screen, do the following:

   4. Create an IDrawingCanvas object.

   5. Create an IGList object and add your KrMemoyBitmap object to it.

   6. Select the IGList object into the IDrawingCanvas object.


ΓòÉΓòÉΓòÉ 3.6. Using your own coordinate systems ΓòÉΓòÉΓòÉ

possibly #include "krgobj.hpp"

possibly #include "krbwin.hpp"

#include "krcstran.hpp" if none of the above was included

Drawing graphics in the system's coordinate system can sometimes be very
complicated, because (a) the window size and hence the coordinate system size
is usually unknown at compile time, (b) the need to use integer variables
sometimes prevents exact placement, and (c) there's no way to get a logarithmic
scale.

While (a) may partly be solved by using a transformation matrix and (c) is most
likely interesting for scientists only, it would still be much more user
friendly if the programmer could place all items within the coordinate system
he chooses.

To define a coordinate system, do the following:

   1. Create an instance of KrCoordSystemTranslator.

 You can use this coordinate system to create instances of all classes which
 are defined in krgobj.hpp. You may also define your own classes. In addition,
 you may assign a memory bitmap to the coordinate system. If you do the latter,
 be certain to not display the bitmap in any common IDrawingCanvas, but only in
 an KrDrawingCanvas, and be sure to insert it into a KrGraphicList instead of
 an IGList.

 You may collect your graphics in a KrGraphicList object and display them in a
 KrDrawingCanvas or print them using a KrPrinter. This is done using the common
 UICL methods. Refer to demo.cpp and to the IBM open class library
 documentation for details.


ΓòÉΓòÉΓòÉ 4. Extensions ΓòÉΓòÉΓòÉ

This chapter will give a short glance at some non-basic classes and give hints
on how to extend Kroni's Classes to make them serve your needs better.


ΓòÉΓòÉΓòÉ 4.1. Using other than the predefined types for user input ΓòÉΓòÉΓòÉ

There are generally three ways to define input for other than the predefined
objects.

   1. Create a subclass from KrUserDataField and wrap your input variable into
      an instance of that subclass. This is demonstrated in demo.cpp.

   2. Write an overload for the >> operator for the type of your input
      variable. This is done the same way as for common text mode streams,
      except for the declaration of the operator itself, which must be:

      KrWinComm & operator >> (KrWinComm & aWinComm, YourType & aObject);

   3. Create a subclass from KrUserDataField and write a constructor for it
      which expects as its only argument a pointer to the structure you want to
      input. Then write an overload for the >> operator. This is demonstrated
      in dialog3.cpp.

 Notes:

   1. Method 1 and 3 are very flexible, because using this method you can
      create an arbitrary subwindow for the user input. Method 2 lets you only
      stack subwindows for already known input types.

   2. Method 2 is very convenient, since there's no need to explicitly define a
      wrapper object when querying the user for input. Method 1 requires more
      work and Method 3 most work of all three methods.

   3. Method 3 is most powerful, since it can be used to input arbitrary types
      (as opposed to method 1, which is restricted to classes inheriting from
      KrUserDataField), and the input can be done using arbitrary windows (as
      opposed to method 2). In most cases, it is a good idea to choose method
      3.


ΓòÉΓòÉΓòÉ 4.2. Using your own graphic classes with a KrCoordSystemTranslator ΓòÉΓòÉΓòÉ

To let your own graphic objects make use of you own coordinate system, have a
look at krgobj.hpp and krgobj.cpp and study the definition of KrGLine. If you
plan to make use of a logarithmic scale, please don't forget the additional
work this will need.


ΓòÉΓòÉΓòÉ 4.3. Frames ΓòÉΓòÉΓòÉ

Especially when printing, is is often convenient to use a rectangle within the
whole window for output, while the graphic objects that print their output into
that rectangle still think that the rectangle is the whole window.

This can be achieved using frames. Have a look at demo.cpp for how to use them.

Note:   Never forget to release each frame using a KrAntiFrame. If you fail to
        do so, repainting of your window will take place inside a frame instead
        of the whole window next time, and on the next redraws this will even
        become nastier.