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

OS/2 Help File | 1997-02-25 | 46KB | 1,695 lines

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

Kroni's Classes
Version 0.12

--  A class library for lazy PM programmers  --

Reference 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. Introduction ΓòÉΓòÉΓòÉ

This reference guide lists all public classes and functions defined in Kroni's
Classes and explaines the meaning of their members and arguments. Since Kroni's
Classes are build upon the IBM open class library, this reference guide tries
to maintain the open class library's reference guide's "look & feel".

This guide should not be used as a general tutorial. Please have a look at the
user's guide and the demo software to find out more about that subject.


ΓòÉΓòÉΓòÉ 2. Classes by Name ΓòÉΓòÉΓòÉ

KrAntiFrame
KrAsyncMain
KrAlignment
KrBitfield
KrBitfieldData
KrChoice
KrChoiceData
KrCommonTextOutput
KrCoordSystemTranslator
KrDrawingCanvas
KrFrame
KrGBox
KrGLine
KrGString
KrGraphicList
KrMemoryBitmap
KrMenuBar
KrPoint
KrPrinter
KrProfile
KrRectangle
KrTrace
KrUserDataField
KrWinComm


ΓòÉΓòÉΓòÉ 3. Carefree main() function ΓòÉΓòÉΓòÉ

By inheriting from the KrAsyncMain class, you get a new main() function which
offers convenient features.


ΓòÉΓòÉΓòÉ 3.1. KrAsyncMain ΓòÉΓòÉΓòÉ

Description

Derivation

Constructors

Public Functions

Enumerations


ΓòÉΓòÉΓòÉ 3.1.1. Class Description - KrAsyncMain ΓòÉΓòÉΓòÉ

#include "krasyncm.hpp"

Beginners to OS/2 PM programming usually find this message processing style in
which PM programs have to be written highly disturbing. The IBM open class
library helps somewhat by providing ICurrentApplication::run(). However, the
associated handler concept is not easy to comprehend, and the programmer ist
still responsible for not blocking the message queue for more than a few
milliseconds.

By inheriting from KrAsyncMain, you get a new main() function with the
following nice features:

     It runs in its own thread on idle priority. This means that you can do
      whatever you want in this main() function, the system will still be able
      to multitask as if no system load existed, you'll be able to move around
      your app's window on the screen etc., but main() will still get as much
      CPU power as possible under these circumstances (usually, this will be
      approx. 99.9%).

     It will receive commands send to your window, thus benefiting from the
      advantages of the message system while avoiding its disadvantages (s.a).

     It will receive a startup message, i.e. you can now easily write commands
      which are supposed to be part of the program's initialization, but which
      also require that the system parts of the application already are fully
      functional (i.e. that IApplication::current().run() ist already running).


ΓòÉΓòÉΓòÉ 3.1.2. Derivation - KrAsyncMain ΓòÉΓòÉΓòÉ

KrAsyncMain inherits both from ICommandHandler and from IThreadFn.


ΓòÉΓòÉΓòÉ 3.1.3. Constructors - KrAsyncMain ΓòÉΓòÉΓòÉ

KrAsyncMain is a virtual class. You cannot construct objects of this class.
Instead, derive a new class from KrAsyncMain which defines at least a new
function main.

You can construct one object of a derived class and attach it to your
application's main window. Though it might be possible to create more objects
and destruct them, this is not recommended.

The construction of this object should take place immediately before calling
IApplication::current().run().

Overload 1

public:
KrAsyncMain (IWindow* mainWindow);


ΓòÉΓòÉΓòÉ 3.1.4. Public Functions - KrAsyncmain ΓòÉΓòÉΓòÉ

Constructors
KrAsyncMain

main() function
main


ΓòÉΓòÉΓòÉ 3.1.4.1. KrAsyncMain::main ΓòÉΓòÉΓòÉ

You must overwrite this pure virtual function. It is called on program startup
and whenever a command is received by your application's main window. This
command may come from any source, including having been issued from within this
function.

The command is passed in the parameter event. Have a look at the enumeration
commands to find out what commands are used.

public:
virtual void main (IEvent & event) = 0;

Note:   This function is called once at a time only. You don't need to take
        care of any synchronization issues, but you must be aware that no
        further commands will be processed by this function while it is still
        running.

However, if commands are received while the function is still running, these
commands are not lost. Instead, they are stored in a FIFO (first in, first out)
queue and being processed as soon as the function is left.


ΓòÉΓòÉΓòÉ 3.1.5. Enumerations - KrAsyncMain ΓòÉΓòÉΓòÉ

commands


ΓòÉΓòÉΓòÉ 3.1.5.1. KrAsyncMain::commands ΓòÉΓòÉΓòÉ

public:
typedef enum {cmdStartUp = 1, cmdFuncFinished, cmdUser} commands;

These command codes are being passed in IEvent::parameter1() to main. These are
their meanings:


 cmdStartUp           Used on first call after program startup

 cmdFuncFinished      Reserved for internal use

 cmdUser              This and all subsequent values are free for you to
                      use for your own commands. Be aware, however, that
                      you must avoid conflicts with other commands sent
                      to your application's main window, e.g. IDs of
                      menu items.


ΓòÉΓòÉΓòÉ 4. Menu support ΓòÉΓòÉΓòÉ

Use KrMenuBar to add a menu bar (possibly with drop-down menus) to your
application.


ΓòÉΓòÉΓòÉ 4.1. KrMenuBar ΓòÉΓòÉΓòÉ

#include "krmenu.hpp"

KrMenuBar does not provide real new features, but rather a bugfix. It behaves
exactely like IMenuBar, from which it inherits, with one exception: when
constructed using

public:
KrMenuBar (IFrameWindow *owner, const Style & style = defaultStyle());

the correct system font for menus is used to build the menu bar and the
associated menus (IMenuBar erranously uses the system proportional font).


ΓòÉΓòÉΓòÉ 5. Screen text output ΓòÉΓòÉΓòÉ

The class KrCommonTextOutput allows you to easily output text to the screen.


ΓòÉΓòÉΓòÉ 5.1. KrCommonTextOutput ΓòÉΓòÉΓòÉ

Description

Derivation

Constructors

Public Functions


ΓòÉΓòÉΓòÉ 5.1.1. Class Description - KrCommonTextOutput ΓòÉΓòÉΓòÉ

#include "krcto.hpp"

This class contains a ostream object. All output that goes to this object is
displayed in an IMultiLineEdit window.

You can use this class to redirect output from cout etc. to the screen.


ΓòÉΓòÉΓòÉ 5.1.2. Derivation - KrCommonTextOutput ΓòÉΓòÉΓòÉ

KrCommonTextOutput inherits from IMultiLineEdit.


ΓòÉΓòÉΓòÉ 5.1.3. Constructors - KrCommonTextOutput ΓòÉΓòÉΓòÉ

You can construct and destruct objects of this class.

Overload 1

public:

KrCommonTextOutput (unsigned long id, IWindow* parent, IWindow* owner,
          const IRectangle& initial = IRectangle (),
          const Style& style = defaultStyle () | readOnly);

The constructor works exactly like the corresponding constructor of
IMultiLineEdit.


ΓòÉΓòÉΓòÉ 5.1.4. Public Functions - KrCommonTextOutput ΓòÉΓòÉΓòÉ

Constructors
KrCommonTextOutput

Associated stream
stream


ΓòÉΓòÉΓòÉ 5.1.4.1. KrCommonTextOutput::stream ΓòÉΓòÉΓòÉ

Use this function to access the ostream associated to the KrCommonTextOutput
object.

public:
ostream & stream ();

Usually, you will assign it to some other stream like cout using the operator
=.

Note:   The ostream has and needs the property ios::unitbuf. Unfortunately,
        this is not copied by the operator =. Hence, you must take care of this
        yourself by calling ios::setf (ios::unitbuf).

Do not use this function before the object is properly initialized, i.e. before
IApplication::current().run() has been called.


ΓòÉΓòÉΓòÉ 6. Easy user input ΓòÉΓòÉΓòÉ

The class KrWinComm provides you with the ability to easily query the user for
input for some basic variable types, using the common >> operator.

In addition, the following classes let you ask the user for input of more
complicated data structures and even of arbitrary types.

KrBitfield
KrBitfieldData
KrChoice
KrChoiceData
KrUserDataField


ΓòÉΓòÉΓòÉ 6.1. KrWinComm ΓòÉΓòÉΓòÉ

Description

Derivation

Constructors

Public Functions

Operators

Manipulators


ΓòÉΓòÉΓòÉ 6.1.1. Class Description - KrWinComm ΓòÉΓòÉΓòÉ

#include "krwc.hpp"

This class, in combination with some operators, acts similar to an istream
object. It queries data from the user by presenting him a dialog box.

Please note that this class does not really inherit from istream, so that not
all types which can be input via an istream can also immediately be input via a
KrWinComm object. It is possible, however, to provide that support for
arbitrary objects in a convenient way. Have a look at the user's guide and the
demo programs dialog3 and demo to learn details.


ΓòÉΓòÉΓòÉ 6.1.2. Derivation - KrWinComm ΓòÉΓòÉΓòÉ

KrWinComm inherits from IBase.


ΓòÉΓòÉΓòÉ 6.1.3. Constructors - KrWinComm ΓòÉΓòÉΓòÉ

You can construct and destruct objects of this class.

Overload 1

public:

KrWinComm (const IString & aTitle = "Dialog");

The constructor initializes essential object data, but does not create the
dialog window. The window is created when the first input is queried from the
KrWinComm object. The dialog title can be changed at a later time using
setTitle.


ΓòÉΓòÉΓòÉ 6.1.4. Public Functions - KrWinComm ΓòÉΓòÉΓòÉ

Appearance
setFont
setTitle

Constructors
KrWinComm
~KrWinComm

Diagnostics
ok

Display Dialog
run

Input
addEntryField

Output
addToNextPrompt
setNextPrompt


ΓòÉΓòÉΓòÉ 6.1.4.1. KrWinComm::setFont ΓòÉΓòÉΓòÉ

Use this function to change the default font used in the dialog window.

public:
void setFont (const IFont & aFont);


ΓòÉΓòÉΓòÉ 6.1.4.2. KrWinComm::setTitle ΓòÉΓòÉΓòÉ

Use this function to change the dialog window's title.

public:
void setTitle (const IString & aTitle);


ΓòÉΓòÉΓòÉ 6.1.4.3. KrWinComm::~KrWinComm ΓòÉΓòÉΓòÉ

public:
~KrWinComm ();


ΓòÉΓòÉΓòÉ 6.1.4.4. KrWinComm::ok ΓòÉΓòÉΓòÉ

Use this function to find out whether the last dialog has been aborted.

public:
Boolean ok ();

This function returns true if the user completed the dialog and pressed the OK
button, and false if he aborted it.


ΓòÉΓòÉΓòÉ 6.1.4.5. KrWinComm::run ΓòÉΓòÉΓòÉ

This function displays the dialog and waits for the user input.

public:
Boolean run ();

The function returns true if the user completed the dialog and pressed the OK
button, and false if he aborted it.

Note:   It is recommended to use the display modifier instead of this function.


ΓòÉΓòÉΓòÉ 6.1.4.6. KrWinComm::addEntryField ΓòÉΓòÉΓòÉ

This function prepares the KrWinComm object to input variables of the
corresponding type.

Overload 1

public:
void addEntryField (IString & s);

Overload 2

public:
void addEntryField (double & d);

Overload 3

public:
void addEntryField (unsigned long & l);

Overload 4

public:
void addEntryField (signed long & l);

Overload 5

public:
void addEntryField (KrBitfield & b);

Overload 6

public:
void addEntryField (KrChoice & c);

Overload 7

public:
void addEntryField (KrUserDataField & f);

Overload 8

public:
void addEntryField (KrUserDataField * f);

The function returns true if the user completed the dialog and pressed the OK
button, and false if he aborted it.

Note:   Do not use any of these functions. Use the corresponding operator >>
        instead.


ΓòÉΓòÉΓòÉ 6.1.4.7. KrWinComm::addToNextPrompt ΓòÉΓòÉΓòÉ

This function appends a string to the introducing line for the next input
field.

public:
void addToNextPrompt (const IString & title);

Note:   It is recommended to use the operator << instead of this function.


ΓòÉΓòÉΓòÉ 6.1.4.8. KrWinComm::setNextPrompt ΓòÉΓòÉΓòÉ

This function sets the introducing line for the next input field.

public:
void setNextPrompt (const IString & title);

Note:   It is recommended to use the operator << instead of this function.


ΓòÉΓòÉΓòÉ 6.1.5. Operators - KrWinComm ΓòÉΓòÉΓòÉ

For your convenience, overloads to the common input and output operator are
provided for the use with KrWinComm

operator <<
operator >>

Note:   Make sure you do not use any of these operatrs before
        IApplication::current().run() has been called, since they require the
        existence of a message queue.


ΓòÉΓòÉΓòÉ 6.1.5.1. KrWinCom - operator << ΓòÉΓòÉΓòÉ

This operator lets the programmer add "prompt lines" to the dialog window
presented to the user. KrWinComm accumulates all strings directed to it using
this operator, until the operator >> is used to input some variable. Then, the
accumulated string is used as the prompt line, and its contents is deleted so
that the same can be done for the next input variable.

Overload 1

public:
KrWinComm & operator << (KrWinComm & aWinComm,
             const IString & aString);


ΓòÉΓòÉΓòÉ 6.1.5.2. KrWinCom - operator >> ΓòÉΓòÉΓòÉ

Use the overloads of this operator to query input from the user.

Use the last overload, which expects a pointer to a KrUserDataField object, to
define the input for objects for which no pre-defined operator exists, and
which are not derived from KrUserDataField. The corresponding KrUserDataField
will be deleted after the dialog window has been displayed. Have a look at the
user's guide and the sample programs display3.cpp and demo.cpp for details on
this subject.

The other overloads do not delete the objects passed to them as arguments.

Overload 1

public:
KrWinComm & operator >> (KrWinComm & aWinComm,
             IString & aString);

Overload 2

public:
KrWinComm & operator >> (KrWinComm & aWinComm,
             double & aDouble);

Overload 3

public:
KrWinComm & operator >> (KrWinComm & aWinComm,
             unsigned long & aUnsigned);

Overload 4

public:
KrWinComm & operator >> (KrWinComm & aWinComm,
             signed long & aSigned);

Overload 5

public:
KrWinComm & operator >> (KrWinComm & aWinComm,
             KrBitfield & aBitfield);

Overload 6

public:
KrWinComm & operator >> (KrWinComm & aWinComm,
             KrChoice & aChoice);

Overload 7

public:
KrWinComm & operator >> (KrWinComm & aWinComm,
             KrUserDataField & aUserData);

Overload 8

public:
KrWinComm & operator >> (KrWinComm & aWinComm,
             KrUserDataField* aUserData);


ΓòÉΓòÉΓòÉ 6.1.6. Manipulators - KrWinComm ΓòÉΓòÉΓòÉ

The display manipulator will show the dialog on the screen and let the user
type his input. Its influence on KrWinComm objects is similar to that of the
operator flush on ostream objects.


ΓòÉΓòÉΓòÉ 6.1.6.1. KrWinComm - manipulator display ΓòÉΓòÉΓòÉ

This manipulator displays the dialog window defined by previous uses of the
operators << and >> on a KrWinComm object and evaluates the user input.

public:
KrWinComm & display (KrWinComm & aWinComm);


ΓòÉΓòÉΓòÉ 6.2. KrBitfield ΓòÉΓòÉΓòÉ

Description

Derivation

Constructors

Public Functions


ΓòÉΓòÉΓòÉ 6.2.1. Class Description - KrBitfield ΓòÉΓòÉΓòÉ

#include "krwc.hpp"

This class represents a set of options, each of which has a name, and each of
which can indpendently be selected or deselected. Its main purpose is to be
used as an input data structure for  KrWinComm.


ΓòÉΓòÉΓòÉ 6.2.2. Derivation - KrBitfield ΓòÉΓòÉΓòÉ

KrBitfield inherits from IBase.


ΓòÉΓòÉΓòÉ 6.2.3. Constructors - KrBitfield ΓòÉΓòÉΓòÉ

You can construct and destruct objects of this class.

The default constructor creates an empty set of options. Before an object
created that way is actually used, add should have been called at least once.

Overload 1

public:
KrBitfield ();

You may also construct a KrBitfield object from an existing KrBitfieldData
object.

Overload 2

public:
KrBitfield (const KrBitfieldData & aData);


ΓòÉΓòÉΓòÉ 6.2.4. Public Functions - KrBitfield ΓòÉΓòÉΓòÉ

Adding new options
add

Constructors
KrBitfield

Control options
isChecked
toggle

Queries
getFirstKey
getNextKey
getText
numberOfEntries


ΓòÉΓòÉΓòÉ 6.2.4.1. KrBitfield::add ΓòÉΓòÉΓòÉ

There are to ways to add a new option to the set.

Overload 1

public:
int add (const IString & newEntry, Boolean checked = false);

Use this overload to add an option and assign the next free id to it. This id
is returned by the function. The parameter checked lets you control whether the
option should initialy be set.

Overload 2

public:
int add (int id, const IString & newEntry, Boolean checked = false);

Use this overload to add an option and assign a predefined id to it. If this id
is not free anymore, the call fails, and zero is returned. Otherwise, the
predefined id itself is returned.


ΓòÉΓòÉΓòÉ 6.2.4.2. KrBitfield::isChecked ΓòÉΓòÉΓòÉ

Use this function to query the status of the option identified by the parameter
id.

public:
Boolean isChecked (int id);


ΓòÉΓòÉΓòÉ 6.2.4.3. KrBitfield::toggle ΓòÉΓòÉΓòÉ

Use this function to change the status of an option. There are two overloads.
Both return the new status of the option identified by the parameter id.

Overload 1

public:
Boolean toggle (int id, Boolean check);

Use this overload to set the option to the value check.

Overload 2

public:
Boolean toggle (int id);

This overload inverts the current status of the option.


ΓòÉΓòÉΓòÉ 6.2.4.4. KrBitfield::getFirstKey ΓòÉΓòÉΓòÉ

This function returns the id of the first option in the set.

public:
int getFirstKey ();

Note:   If you call this function when the set is empty, an IEmptyException is
        thrown.


ΓòÉΓòÉΓòÉ 6.2.4.5. KrBitfield::getNextKey ΓòÉΓòÉΓòÉ

This function returns the id of the next option in the set which comes after
the id passed as an argument.

public:
int getNextKey (int id);

Note:   If you pass an invalid id to this function, an ICursorInvalidException
        is thrown.

If the id passed to the function already belongs to the last option, this same
id is returned.


ΓòÉΓòÉΓòÉ 6.2.4.6. KrBitfield::getText ΓòÉΓòÉΓòÉ

This function returns the name of the option whose id is passed as an argument.

public:
IString & getText (int id);

Note:   If you pass an invalid id to this function, an INotContainsKeyException
        is thrown.


ΓòÉΓòÉΓòÉ 6.2.4.7. KrBitfield::numberOfEntries ΓòÉΓòÉΓòÉ

This function returns the number of options currently in the set.

public:
int numberOfEntries ();


ΓòÉΓòÉΓòÉ 6.3. KrBitfieldData ΓòÉΓòÉΓòÉ

This is a template class derived from IKeySortedSet, which contains the data of
the set of options included in a KrBitfield object.

Do not use this class in your programs, since it might change or even
altogether disappear in a future version of Kroni's Classes.


ΓòÉΓòÉΓòÉ 6.4. KrChoice ΓòÉΓòÉΓòÉ

Description

Derivation

Constructors

Public Functions


ΓòÉΓòÉΓòÉ 6.4.1. Class Description - KrChoice ΓòÉΓòÉΓòÉ

#include "krwc.hpp"

This class represents a set of choices, each of which has a name, and of which
exactly one is chosen at a time. Its main purpose is to be used as an input
data structure for  KrWinComm.


ΓòÉΓòÉΓòÉ 6.4.2. Derivation - KrChoice ΓòÉΓòÉΓòÉ

KrChoice inherits from IBase.


ΓòÉΓòÉΓòÉ 6.4.3. Constructors - KrChoice ΓòÉΓòÉΓòÉ

You can construct and destruct objects of this class.

The default constructor creates an empty set of choices. Before an object
created that way is actually used, add should have been called at least once.

Overload 1

public:
KrChoice ();

You may also construct a KrChoice object from an existing KrChoiceData object.

Overload 2

public:
KrChoice (const KrChoiceData & aData);


ΓòÉΓòÉΓòÉ 6.4.4. Public Functions - KrChoice ΓòÉΓòÉΓòÉ

Active choice
get
set

Adding new choices
add

Constructors
KrChoice

Queries
getFirstKey
getNextKey
getText
numberOfEntries


ΓòÉΓòÉΓòÉ 6.4.4.1. KrChoice::get ΓòÉΓòÉΓòÉ

This function returns the id of the currently active choice.

public:
int get();


ΓòÉΓòÉΓòÉ 6.4.4.2. KrChoice::set ΓòÉΓòÉΓòÉ

Pass a choice's id as an argument to this function to make the choice the
active one.

public:
void set (int id);


ΓòÉΓòÉΓòÉ 6.4.4.3. KrChoice::add ΓòÉΓòÉΓòÉ

There are to ways to add a new choice to the set.

Overload 1

public:
int add (const IString & newChoice);

Use this overload to add a choice and assign the next free id to it. This id is
returned by the function.

Overload 2

public:
int add (int id, const IString & newChoice);

Use this overload to add a choice and assign a predefined id to it. If this id
is not free anymore, the call fails, and zero is returned. Otherwise, the
predefined id itself is returned.


ΓòÉΓòÉΓòÉ 6.4.4.4. KrChoice::getFirstKey ΓòÉΓòÉΓòÉ

This function returns the id of the first choice in the set.

public:
int getFirstKey ();

Note:   If you call this function when the set is empty, an IEmptyException is
        thrown.


ΓòÉΓòÉΓòÉ 6.4.4.5. KrChoice::getNextKey ΓòÉΓòÉΓòÉ

This function returns the id of the next choice in the set which comes after
the id passed as an argument.

public:
int getNextKey (int id);

Note:   If you pass an invalid id to this function, an ICursorInvalidException
        is thrown.

If the id passed to the function already belongs to the last choice, this same
id is returned.


ΓòÉΓòÉΓòÉ 6.4.4.6. KrChoice::getText ΓòÉΓòÉΓòÉ

This function returns the name of the choice whose id is passed as an argument.

public:
IString & getText (int id);

Note:   If you pass an invalid id to this function, an INotContainsKeyException
        is thrown.


ΓòÉΓòÉΓòÉ 6.4.4.7. KrChoice::numberOfEntries ΓòÉΓòÉΓòÉ

This function returns the number of choices currently in the set.

public:
int numberOfEntries ();


ΓòÉΓòÉΓòÉ 6.5. KrChoiceData ΓòÉΓòÉΓòÉ

This is a template class derived from IKeySortedSet, which contains the data of
the set of choices included in a KrChoice object.

Do not use this class in your programs, since it might change or even
altogether disappear in a future version of Kroni's Classes.


ΓòÉΓòÉΓòÉ 6.6. KrUserDataField ΓòÉΓòÉΓòÉ

Description

Derivation

Constructors

Public Functions


ΓòÉΓòÉΓòÉ 6.6.1. Class Description - KrUserDataField ΓòÉΓòÉΓòÉ

#include "krwc.hpp"

This virtual class is used to provide KrWinComm support for variables of
arbitrary types. Refer to the user's guide and the demo programs dialog3.cpp
and demo.cpp for inforation on how to use it.


ΓòÉΓòÉΓòÉ 6.6.2. Derivation - KrUserDataField ΓòÉΓòÉΓòÉ

KrUserDataField inherits from IBase.


ΓòÉΓòÉΓòÉ 6.6.3. Constructors - KrUserDataField ΓòÉΓòÉΓòÉ

This is a virtual class. You cannot construct objects of this class. Instead,
use this class as a base to define new classes and overwrite all functions.

No constructor is defined for this class.


ΓòÉΓòÉΓòÉ 6.6.4. Public Functions - KrUserDataField ΓòÉΓòÉΓòÉ

Pure virtual functions
initialize
transform


ΓòÉΓòÉΓòÉ 6.6.4.1. KrUserDataField::initialize ΓòÉΓòÉΓòÉ

public:
virtual int initialize (IMultiCellCanvas & c, int start) = 0;

When this function is called, the drawing of the actual dialog window is
currently taking place, and this object must now create its own window objects
and place them in the IMultiCellCanvas c, starting at row start.

Only column 4 of c should be used. As many rows as desired may be used. The
number of the first unused row must be returned.

For further details, refer to the user's guide and the demo programs
dialog3.cpp and demo.cpp


ΓòÉΓòÉΓòÉ 6.6.4.2. KrUserDataField::transform ΓòÉΓòÉΓòÉ

public:
virtual Boolean transform (Boolean doIt) = 0;

To give the user the opportunity to do input, window elements like IEntryField
must be used. If doIt is true, this function must transform the data in the
window element to the actual user data.

If doIt is false, the function may only test whether such a transform is
possible with the data in the window element.

If successfull transformation is possible or has been performed, true is
returned. Otherwise, false is returned.


ΓòÉΓòÉΓòÉ 7. Graphics Classes ΓòÉΓòÉΓòÉ

Sorry, no information yet


ΓòÉΓòÉΓòÉ 8. Printing ΓòÉΓòÉΓòÉ

To easily print your graphics on any printer, use the KrPrinter class.


ΓòÉΓòÉΓòÉ 8.1. KrPrinter ΓòÉΓòÉΓòÉ

Description

Derivation

Constructors

Public Functions


ΓòÉΓòÉΓòÉ 8.1.1. Class Description - KrPrinter ΓòÉΓòÉΓòÉ

#include "krprint.hpp"

This class is used to output graphics to a printer. Its use is similar to that
of IDrawingCanvas.

In addition, KrPrinter provides methods to let the user choose the printer and
the settings he wants to use.


ΓòÉΓòÉΓòÉ 8.1.2. Derivation - KrPrinter ΓòÉΓòÉΓòÉ

KrPrinter inherits from IBase.


ΓòÉΓòÉΓòÉ 8.1.3. Constructors - KrPrinter ΓòÉΓòÉΓòÉ

You can construct and destruct objects of this class.

Overload 1

public:
KrPrinter ();

The default constructor does not set any graphics list. Use setList before
doing any printing.

The printer which is used when print is called is initially the system default
printer, using its default settings.


ΓòÉΓòÉΓòÉ 8.1.4. Public Functions - KrPrinter ΓòÉΓòÉΓòÉ

Constructors
KrPrinter

Graphic List
setList

Printing
print

Retrieving Information
getArea

User Interaction
printDialog


ΓòÉΓòÉΓòÉ 8.1.4.1. KrPrinter::setList ΓòÉΓòÉΓòÉ

Use this function to select an IGList into the KrPrinter object. The contents
of the IGList will be printed when print is called.

The function returns the previously used IGList. If no IGList has been selected
into the KrPronter object so far, 0 is returned.

public:
IGList* setList (IGList& list);


ΓòÉΓòÉΓòÉ 8.1.4.2. KrPrinter::print ΓòÉΓòÉΓòÉ

Use this function to print the contents of the IGList previously selected by
setList.

The string title is used as the job title which appears in the queue display of
the printer object.

public:
Boolean print (IString title);


ΓòÉΓòÉΓòÉ 8.1.4.3. KrPrinter::getArea ΓòÉΓòÉΓòÉ

This function returns the rectangular area in system coordinates on which
drawing on the printer takes place. p1 represents the lower left corner, p2 the
upper right corner.

public:
void getArea (IPoint & p1, IPoint & p2);


ΓòÉΓòÉΓòÉ 8.1.4.4. KrPrinter::printDialog ΓòÉΓòÉΓòÉ

This function pops up a dialog window in which the user can choose any printer
which is to be used on subsequent calls to print. The user is also prompted to
define his own printer settings for the print job. The printer and its settings
are stored for the lifetime of the KrPrinter object. The only way to change
them is to call printDialog again.

At the end of his input, the user may either press the OK button or the Cancel
button. If he chose the OK button, true is returned.

public:
Boolean printDialog ();


ΓòÉΓòÉΓòÉ 9. Ini file access ΓòÉΓòÉΓòÉ

To easily access data in OS/2 system ini files or in your own ini files, use
the KrProfile class.


ΓòÉΓòÉΓòÉ 9.1. KrProfile ΓòÉΓòÉΓòÉ

Description

Derivation

Constructors

Public Functions

Enumerations

Manipulators


ΓòÉΓòÉΓòÉ 9.1.1. Class Description - KrProfile ΓòÉΓòÉΓòÉ

#include "krprof.hpp"

Using this class, you can read and write data from/to os2.ini, os2sys.ini, or
any other OS/2 style ini file that you choose, using the common << and >>
operators.


ΓòÉΓòÉΓòÉ 9.1.2. Derivation - KrProfile ΓòÉΓòÉΓòÉ

KrProfile inherits from iostream. It also inherits from the non-public class
_KrProfileBase, but this is only for technical reasons.


ΓòÉΓòÉΓòÉ 9.1.3. Constructors - KrProfile ΓòÉΓòÉΓòÉ

You can construct and destruct objects of this class.

Overload 1

public:
KrProfile (const IString & aApp, profile aProfile = user,
      Boolean iBuffered = false);

Use this constructor to open the system ini file aProfile for reading and
writing data of the application which is identified by the name aApp in the ini
file.

By default, the object acts like a unit-buffered iostream, i.e. you can simply
do your input output using the operators << and >>. If you want to avoid the
slight overhead created by unit-buffering, and you want full buffering instead,
set iBuffered=true If you do so, however, don't forget that you are now
responsible for flushing the stream yourself using the manipulator flush.

Overload 2

public:
KrProfile (const IString & aApp, const IString & aProfile,
      Boolean iBuffered = false);

This is identical to overload 1, except that aProfile is now not neccessarily a
system ini file, but the file name of any ini file. If it doesn't already
exist, this constructor creates this ini file.


ΓòÉΓòÉΓòÉ 9.1.4. Public Functions - KrProfile ΓòÉΓòÉΓòÉ

Application control
exists
removeApp

Constructors
KrProfile
~KrProfile

I/O functions
clearBuffer
readData
writeData

Key control
existsKey
key
removeKey
setKey

Retrieving information
good
size


ΓòÉΓòÉΓòÉ 9.1.4.1. KrProfile::exists ΓòÉΓòÉΓòÉ

Returns true if any data of the application already exists in the ini file, and
false otherwise.

public:
Boolean exists ();


ΓòÉΓòÉΓòÉ 9.1.4.2. KrProfile::removeApp ΓòÉΓòÉΓòÉ

Removes all data of the application from the ini file.

public:
void removeApp ();


ΓòÉΓòÉΓòÉ 9.1.4.3. KrProfile::~KrProfile ΓòÉΓòÉΓòÉ

public:
~KrProfile ();


ΓòÉΓòÉΓòÉ 9.1.4.4. KrProfile::clearBuffer ΓòÉΓòÉΓòÉ

Do not use this function, since it might become private in a later version. Use
the manipulator clear instead.

public:
void clearBuffer ();


ΓòÉΓòÉΓòÉ 9.1.4.5. KrProfile::readData ΓòÉΓòÉΓòÉ

This function appends the contents of the ini file associated to the current
key to the stream. Its direct use may be confusing; it is recommended to use
the >> operator instead, which will call this function only when neccessary.
This function may become private in a later version.

public:
virtual void readData ();


ΓòÉΓòÉΓòÉ 9.1.4.6. KrProfile::writeData ΓòÉΓòÉΓòÉ

Do not use this function, since it might become private in a later version. Use
the manipulator flush instead.

public:
virtual void writeData (Boolean callFromBuff);


ΓòÉΓòÉΓòÉ 9.1.4.7. KrProfile::existsKey ΓòÉΓòÉΓòÉ

Returns true if any data associated to the current key already exists in the
ini file, and false otherwise.

public:
Boolean existsKey ();


ΓòÉΓòÉΓòÉ 9.1.4.8. KrProfile::key ΓòÉΓòÉΓòÉ

Returns the currently set key.

public:
IString & key ();


ΓòÉΓòÉΓòÉ 9.1.4.9. KrProfile::removeKey ΓòÉΓòÉΓòÉ

Removes all data associated to the currently set key from the ini file.

public:
void removeKey ();


ΓòÉΓòÉΓòÉ 9.1.4.10. KrProfile::setKey ΓòÉΓòÉΓòÉ

Clears the stream and sets a new key. Before setKey is called for the first
time, the key "Default" is set.

public:
void setKey (const IString & aKey = "Default");


ΓòÉΓòÉΓòÉ 9.1.4.11. KrProfile::good ΓòÉΓòÉΓòÉ

Returns true if the ini file was successfully opened, and false otherwise.

public:
Boolean good ();


ΓòÉΓòÉΓòÉ 9.1.4.12. KrProfile::size ΓòÉΓòÉΓòÉ

Returns the number of bytes currently stored in the ini file under the current
key.

public:
long size ();


ΓòÉΓòÉΓòÉ 9.1.5. Enumerations - KrProfile ΓòÉΓòÉΓòÉ

profile


ΓòÉΓòÉΓòÉ 9.1.5.1. KrProfile::profile ΓòÉΓòÉΓòÉ

public:
enum profile { system, user, both };

If a system ini file is to be opened, a member of this enumeration should be
passed to the constructor. These are their meanings:


 system     Read and write to the OS/2 system ini file
            (usually called os2sys.ini)

 user       Read and write to the OS/2 user ini file (usually
            called os2.ini)

 both       Read from both above ini files, write to the OS/2
            user ini file.


ΓòÉΓòÉΓòÉ 9.1.6. Manipulators - KrProfile ΓòÉΓòÉΓòÉ

Key control
clear
flush

Stream handling
remove


ΓòÉΓòÉΓòÉ 9.1.6.1. clear ΓòÉΓòÉΓòÉ

Use this manipulator to clear the stream. This is neccessary if you have
already read from or written to the stream, but want to discard that data and
write completely new data to that key instead of appending to the old data.

public:
KrProfile & clear (KrProfile & aProfile);


ΓòÉΓòÉΓòÉ 9.1.6.2. flush ΓòÉΓòÉΓòÉ

Use this manipulator to flush the stream. This is only neccessary if you have
constructed the KrProfile object as a fully buffered stream.

public:
KrProfile & flush (KrProfile & aProfile);


ΓòÉΓòÉΓòÉ 9.1.6.3. flush ΓòÉΓòÉΓòÉ

This manipulator is a convenient way to call removeKey.

public:
KrProfile & remove (KrProfile & aProfile);


ΓòÉΓòÉΓòÉ 10. Error handling ΓòÉΓòÉΓòÉ

The IBM open class library extensively uses exceptions both to inform the
programmer about the success of actions performed by classes of the library and
to provide comprehensive debugging information.

Unfortunately, however, the user of an application will not see any error
messages when the program is aborted due to an uncatched exception. Instead,
the program will just terminate. The KrTraceclass take care of this and other
error handling related issues.


ΓòÉΓòÉΓòÉ 10.1. KrTrace ΓòÉΓòÉΓòÉ

Description

Derivation

Constructors

Public Functions

Enumerations

Macros


ΓòÉΓòÉΓòÉ 10.1.1. Class Description - KrTrace ΓòÉΓòÉΓòÉ

#include "krtrace.hpp"

This class handles uncatched exceptions. Whenever an uncatched exception
occurres, the following is done:

   1. Optionally, the exception data is writen to some location

   2. Optionally, the user is informed that an error has occurred

   3. The program is terminated

 This class uses and enhances the functionality of ITrace.


ΓòÉΓòÉΓòÉ 10.1.2. Derivation - KrTrace ΓòÉΓòÉΓòÉ

KrTrace inherits from IBase.


ΓòÉΓòÉΓòÉ 10.1.3. Constructors - KrTrace ΓòÉΓòÉΓòÉ

You cannot construct objects of this class. Instead, make use of its
enumerations and of its static member functions.

Overload 1

private:
KrProfile ();


ΓòÉΓòÉΓòÉ 10.1.4. Public Functions - KrTrace ΓòÉΓòÉΓòÉ

Exception handling
tellUser
traceTo

Exception throwing
_throw


ΓòÉΓòÉΓòÉ 10.1.4.1. KrTrace::tellUser ΓòÉΓòÉΓòÉ

Use this function to determine how detailed (if at all) the user should be
informed about a program crash by a message box.

public:
static void tellUser (userInfo aInfo);


ΓòÉΓòÉΓòÉ 10.1.4.2. KrTrace::traceTo ΓòÉΓòÉΓòÉ

Use this function to determine whether trace and exception information should
be logged, and if yes, to which destination.

Overload 1

public:
static void traceTo (traceTarget aTarget);

Overload 1 traces to the destination aTarget.

Overload 2

public:
static void traceTo (const IString & s);

Overload 2 traces to a file. Its filename is given by s.

Overload 3

public:
static void traceTo ();

Overload 3 traces to the file progname.log in the current directory, where
progname is the name of the exe-file of the program (without the .exe suffix).

Note:   Overload 3 requires that the IBM open class library has been correctly
        initialized using IApplication::current().setArgs().


ΓòÉΓòÉΓòÉ 10.1.4.3. KrTrace::_throw ΓòÉΓòÉΓòÉ

You should not call this function directly, but use one of the macros instead.

Overload 1

public:
static void _throw (const IException & ex, const char* fileName,
          const char* functionName, unsigned long lineNumber);

Overload 2

public:
static void _throw (const IException & ex, const char* fileName,
          const char* functionName, unsigned long lineNumber,
          const IString & group);


ΓòÉΓòÉΓòÉ 10.1.5. Enumerations - KrTrace ΓòÉΓòÉΓòÉ

traceTarget

userInfo


ΓòÉΓòÉΓòÉ 10.1.5.1. KrTrace::traceTarget ΓòÉΓòÉΓòÉ

public:
enum traceTarget {stdout, stderr, file, queue, none};

This enumeration is used to identify the logging destination when calling
traceTo. These are the meanings of their members:


 stdout     Write all log information to stdout

 stderr     Write all log information to stderr

 file       Write all log information to a file. If a file
            name has already been set using traceTo, that name
            is used. If no file name has been set so far,
            traceTo is called without arguments to determine a
            filename. In this case, please note the remarks to
            traceTo.

 queue      Write all log information to the queue
            \\QUEUES\\PRINT32.

 none       Do not perform any logging. This is the default
            until traceTo is called.


ΓòÉΓòÉΓòÉ 10.1.5.2. KrTrace::userInfo ΓòÉΓòÉΓòÉ

public:
enum userInfo {noMsg, simple, logFile, full};

Use this enumeration with tellUser to tell the system whether the user of your
application should recieve information about crashes. The meanings of their
members are:


 noMsg      Do not give the user any message and just exit
            from the program. This is the default until
            tellUser is called. This is also what the IBM open
            class library does if Kroi's Classes are not used.

 simple     Just tell the user that an error was encountered
            and that the program cannot continue.

 logFile    Like "simple", but tell the user also the location
            of the log file (if any exists).

 full       Like "logFile", but also pop up full information
            about the exception which caused the crash.


ΓòÉΓòÉΓòÉ 10.1.6. Macros - KrTrace ΓòÉΓòÉΓòÉ

For use with the KrTrace class, the following macros are defined:

KRTHROW(exc)
KRNAMEDTHROW(exc,name)

KRTHROW works exactly like ITHROW, but accepts also temporaries as arguments
(if you try this with ITHROW, all position information will be lost).

KRNAMEDTHROW works like KRTHROW, but expects another parameter name, which
should be an IString object and contains the name of the group this exception
belongs to. Use this to identify the module the exception was thrown from.


ΓòÉΓòÉΓòÉ <hidden> Dummy ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Dummy ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Dummy ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Dummy ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Dummy ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Dummy ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Dummy ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Dummy ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Dummy ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Dummy ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Dummy ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Dummy ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Dummy ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Dummy ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Dummy ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Dummy ΓòÉΓòÉΓòÉ


ΓòÉΓòÉΓòÉ <hidden> Dummy ΓòÉΓòÉΓòÉ