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

vlk@amt.cmlink.de 

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