
Welcome to MAVERICK CLASS LIBRARY v1.00!

1. WHAT IS IT ?
MAVCL is a 32 bit class library written in IBM C++ providing support for those
typical business and general purpose application functions not
directly provided by IBM ICLUI class library. In particular MAVCL implements
formatted entry fields, quality printer support, regular expressions,
directory services and conversion functions
for date / time with national language support.

SOURCE CODE IS INCLUDED.

I've been using these classes for two years in my OS/2 applications
with high reliability and user satisfaction. I'm distributing the product
as freeware to promote OS/2 application development and to get
comments from other developers that could help me in improving
my final product quality.

Classes are documented in this file (README.TXT).

If I'll receive positive feedback from YOU I'll supply detailed design
in the versions to come. The source code is commented everywhere.

The sample program SAMPLE.EXE prints a typical business report
with data arranged in columns, text break within a column and
a bitmap printed. It also allows the user to enter text, date and numbers in
sample formatted entry fields.

2. INSTALLATION

2.1 Development environment
unzip MAVCLnnn.ZIP in a directory which is in named your LIBPATH, INCLUDE, LIB
environment variables.
This directory will contain all relevant source and include files,
the DLL (MAVCL.DLL) and the sample program SAMPLE.EXE.
The subdirectory SAMPLE contains the source code for the sample program.
This release is compiled with IBM C SET++ at level CT00010 and ICLUI
classes at level CT00010. I'll release a Visualage for C++ version as soon
as IBM ships me a copy, I did not have problems with the beta version
of Visualage for C++.

2.2 Runtime environment
Your compiled program only needs MAVCL.DLL in a directory named in LIBPATH.
MAVCL.DLL cannot be renamed.

3. FEATURES
In this section a short description is given of the classes and their main methods.

3.1 Formatted entry fields

you must include: MAVFRENT.HPP
source code: MAVFRENT.CPP

3.1.1 Description

The class FormEntryField inherits from IEntryField. Do not create instances
of this class. It is only used as a base class for:
AlphaEntryField: entry fields for alphanumeric (IString) variables
NumEntryField: entry fields for numeric (double) variables
DateEntryField: entry fields for date (IDate) variables
TimeEntryField: entry fields for time (ITime) variables

NumEntryField and DateEntryField take into account national settings of OS/2
to format and check variables.

All classes have a constructor for use with a resource field and a
constructor to specify also coordinates in a window, overriding
corresponding contrustors of IEntryField.

Depending on legal characters for each field and field configuration
illegal keys are inhibited (for example during numeric entry only
numbers, +, -, e characters are allowed).

For fields requiring a separator all of  " ,/-.=*_:" characters are valid
separators. When leaving the field the separator required by national
settings is used to format the string in the field.

When leaving the field with an invalid entry (for example and invalid date
for DateEntryField or a number out of the user-given range for NumEntryField),
the field background turns red to alert the operator.

3.1.2 Main methods

3.1.2.1 AlphaEntryField

Constructors:

AlphaEntryField::AlphaEntryField(unsigned long l,
IWindow * iw, IWindow * iw1, const IRectangle & r, 
Boolean b1, Boolean b2, IString s, IString s1)

AlphaEntryField::AlphaEntryField(unsigned long l, IWindow * iw, 
Boolean b1, Boolean b2, IString s, IString s1)

where l is the field id, iw and iw1 are parent and owner, r is the
framing rectangle (for these first four variables refer to IEntryField).
b1=true if all capital characters required
b2=true if no numeric characters are allowed
s is a string containing all allowed characters, if empty (default)
no check is made.
s1 is a regular expression that entry field must match, if empty (default)
no check is made.

Main methods:

setText() to set text.
text() to get text().

3.1.2.2 NumEntryField


Constructors:

NumEntryField::NumEntryField(unsigned long l,
IWindow * iw, IWindow * iw1, const IRectangle & r, Boolean b1, Boolean b2,
double dblMin1, double dblMax1)

NumEntryField::NumEntryField(unsigned long l, IWindow * iw,
Boolean b1, Boolean b2,
double dblMin1, double dblMax1)

where l is the field id, iw and iw1 are parent and owner, r is the
framing rectangle (for these first four variables refer to IEntryField).
b1=true thousands separator are to be shown when the field is left
b2=true if "0" is to be shown when the fields is 0, b2=false means 
the field is left empty when the content is 0.
if dblMin1 and dblMax1 are indicated a check is made when leaving
the field that the content is in the given range

Main methods:

setDouble(double) to set the field content.
double getDouble() to get the field content.

3.1.2.3 DateEntryField

Constructors:

DateEntryField::DateEntryField(unsigned long l, 
IWindow * iw, IWindow * iw1, const IRectangle & r, Boolean b1)

DateEntryField::DateEntryField(unsigned long l, IWindow * iw, Boolean b1)

where l is the field id, iw and iw1 are parent and owner, r is the
framing rectangle (for these first four variables refer to IEntryField).
b1=true means do not display year (only month/day)

Main methods:

setDate(IDate &) to set the field content.
IDate getDate() to get the field content.


3.1.2.4 TimeEntryField


TimeEntryField::TimeEntryField(unsigned long l, IWindow * iw, 
IWindow * iw1, const IRectangle & r)

TimeEntryField::TimeEntryField(unsigned long l, IWindow * iw)

where l is the field id, iw and iw1 are parent and owner, r is the
framing rectangle (for these first four variables refer to IEntryField).

Main methods:

setTime(ITime &) to set the field content.
ITime getTime() to get the field content.



3.2 Printer support

you must include: MAVPRINT.HPP
source code: MAVPRINT.CPP MPSETUP.CPP

3.2.1 Description

The MavPrint class supplies support to the activities of printer
selection, printer selection dialog, font selection and retrieving,
basic string printing in a presentation space, text printing in a
defined rectangle in a presentation space with line wrap and
bitmap printing in a defined rectangle in a presentation space with
or without maintaining aspect ratio.
The page is divided in header (space above margins),
 margined page (space inside margins)
and footer (space below margins).
An handle is given to the presentation space
and one to the device context so that the programmer can use all Gpi
OS/2 functions directly.
The printer selection method is taken from the article "One Call Does It All"
by Monte Copeland in Developer Connection 6. I only rewrote the dialog 
functions using IBM classes and changed few things for C++ recompilation.

3.2.2 Main methods

All Bollean functions return true on successfull completion,
false on error.

void MavPrint::setHAB(HAB h1)
void MavPrint::setWorldCoords(LONG l1)

You MUST call these two function before calling setupPrinter to
set the anchor block and the World Coordinates unit of measure (for
ex. PU_TWIPS or PU_LOMETRIC)

Boolean MavPrint::setupPrinter(PSZ pszUserQueueName,
PSZ pszUserPrintFileName,
IWindow *)

Boolean MavPrint::setupPrinter(IWindow *)

setupPrinter is the printer selection function.
It fills the private structure PRINTERSETUP with the selected printer 
relevant data.

call with pszUserQueueName if you want a specific queue you know in advance,
in this case you can also use pszUserPrintFileName for file printing.
call with a valid owner (IWindow*) if you want the print queue dialog
to be shown. These classes have been written in Italy, so if country code is
039 the printer selection dialog is shown in italian, otherwise in english.
Always call with PSZs allocated for the maximum queue name length, they will
be filled on successfull completion with queue/file names.
Call w/o the string parameters if you are not interested in getting
queue/file names.
Call with strings allocated but empty to select the default queue and
getting its name.

void MavPrint::cleanupPrinter()
frees all resources allocated by setupPrinter.

After you have selected a printer you must open a print job before drawing.
This is done by
Boolean MavPrint::openPrinterJob(PSZ pszJobTitle)
that creates a suitable HPS and HDC you'll be able to retrieve using
HDC MavPrint::getHDC()
HPS MavPrint::getHPS()


Remember to call 
void MavPrint::closePrinterJob()
to close HPS and HDC, free resources and send job content to the printer.

Then define margins using
Boolean MavPrint::setMargins(LONG lxLeft, LONG lxRight, 
LONG lyTop, LONG lyBottom)
This will set data needed by the conversion functions

PPOINTL MavPrint::coordsInHeader(PPOINTL p1, PPOINTL p2);
PPOINTL MavPrint::coordsInFooter(PPOINTL p1, PPOINTL p2);
PPOINTL MavPrint::coordsInMargins(PPOINTL p1, PPOINTL p2);
PRECTL MavPrint::rectlInMargins(PRECTL r1, PRECTL r2);

You will use these functions as all the MavPrint drawing functions work in
world coordinates (as if no margin was defined). You probably like more
to think to points in the header/margin/footer frame, so conversions are
required. For example imagine you want to print a string at the lower-left
corner of your header. You store the coords (0,0) in a POINTL p2, declare
a buffer POINTL p1 and call

if(! printer.printStringAt( printer.coordsInHeader(&p2, &p1), string ) ) { Error(); }

In the same way you can call the other conversion functions for Footer and
margins and the rectangle conversion function for margins.

Other useful function for page size and margins handling are the following:

RECTL * MavPrint::getMargins()
SIZEL * MavPrint::getMarginedPageSize()
SIZEL * MavPrint::getPageSize()
SIZEL * MavPrint::getHeaderSize()
SIZEL * MavPrint::getFooterSize()

which simply return the sizes of the various ereas in the logical page.

We're now ready for drawing text and graphics without being concerned with
frames and physical printers. All relevant data have been encapsulated in
the previously defined functions.

If, for special needs, you want to access to the actual printer data you can
retrieve the DEVOPENDATA struct using

PDEVOPENDATA MavPrint::getDevOpenData()

For example I needed this function programming for Workplace Shell, where
the wpPrintPrinterSpecificFile function requires a structure containing data
I retrieved from DEVOPENDATA.

All graphic drawing function can now be done calling the PM Gpi APIs,
supplying as a parameter the HPS you can get calling MavPrint::getHPS().

MAVCL provides methods for drawing text and handle fonts.

LONG MavPrint::createFontMatching(PSZ pszFacename, LONG lPointSize,
ULONG fl, PBOOL pfScalable, PSIZEF psizfxBox)

is used to create a font. An image font
is first searched for and if one is not found that matches the
font face and size, a scalable font is then searched.
When calling this function MavPrint returns a non-zero LONG (zero is returned
on error) that you can store in a local variable for the following font
selection (by the way this LONG corresponds to the PM lLcId). So the
typical use of this function is, as in the SAMPLE program, to build a set of
fonts after job start. Each font can then be selected for actual drawing calling
MavPrint::selectLogFont. When you create a font it is also selected, 
so you can use it without calling MavPrint::selectLogFont.
pszFacename is a string containing face name (for ex. "Helvetica");
lPointSize is the required nominal size of the font (for ex. 12). It is
always expressed in points, independent from the world coordinates
unit of measure selected for the presentation space.
The optional parameter fl can be used to ask for font attributes, as italic
or bold, refer to FATTRS structure fsSelection field for allowed values.
The optional parameter pfScalable is a pointer to a boolean that is
returned as TRUE if the created font is scalable or false.
The optional parameter psizfxBox is a pointer to a SIZEF structure
that is filled with the size of the selected font.

Boolean MavPrint::selectLogFont(LONG lLcId, PSIZEF psizfxBox)

This function selects a font previously created with 
MavPrint::createFontMatching.
lLcId is the id of the font returned by MavPrint::createFontMatching.
The optional parameter psizfxBox is a pointer to a SIZEF structure
that is filled with the size of the selected font.

Boolean MavPrint::printStringAt(PPOINTL pnt, PSZ string, LONG len)
Boolean MavPrint::printStringAt(PPOINTL pnt, IString & string, LONG len)

These functions print string (either PSZ or IString) at the point
pnt in the selected font. If the optional parameter len is supplied
the string is clipped to the specified len.
Both pnt and len are expressed in world coords units of measure.
pnt is in page coords. Use conversion functions to use 
margins/header/footer coordinates as shown above.


Boolean MavPrint::printTextInBox(PRECTL prct,
PSZ string, LONG & lWordsNotWritten, USHORT usShrink,
LONG lControl, LONG lRound)

Boolean MavPrint::printTextInBox(PRECTL prct,
IString & string, LONG & lWordsNotWritten, USHORT usShrink,
LONG lControl, LONG lRound)

These functions print a text inside the rectangle area pointed by prct.
in the selected font. prct is expressed in world coords units of measure.
prct is in page coords. Use conversion functions to use 
margins coordinates as shown above.
CRs (\n) are taken into account to split lines.
if text does not fit lWordsNotWritten returns the number of words left out.
On exit prct contains the rectangle actually used 
that may be less than maximum allowed in the passed prct rectangle
depending on text length and on usShrink.
In fact  in this case rectangle is lowered.
lControl is the parameter of GpiBox (default 0)
lRound is the corner rounding axis of an ellipse as in GpiBox  (default 0)
usShrink = 0: do not shrink rectangle round text
usShrink = 1: shrink rectangle round text  (default)
usShrink = 2: shrink rectangle round text only vertically
These are the most flexible text print functions of MAVCL, as they allow
to print in a fixed page region, handle text split, can show the rectangular
area if lControl = DRO_OUTLINE.
If the area if too small to fit passed string text the functions return the
number of worlds that did not fit, so that the programmer can perform
the relative actions (as change page and call the function again with the
remaining text).

Boolean MavPrint::printBitmapInBox(RECTL * rectl, PSZ pszFileName, 
Boolean booMaintainAspectRatio)

These functions print a text inside the rectangle area pointed by prct.
prct is expressed in world coords units of measure.
prct is in page coords. Use conversion functions to use 
margins coordinates as shown above.
The bitmap is idetintified by its file name.
The function can shrink or expand the bitmap to fill the passed rectangular
region.
if booMaintainAspectRatio is set to true the bitmap is sshrinked or expanded
to fit the supplied area, but if the area horizontal/vertical size ratio is
not equal to the bitmap ratio the bitmap is drawn at the lower-left corner
of prct and its apect ratio maintained.

Boolean MavPrint::newPage()
Changes page.


3.3 Date/Number conversions to/from string

you must include: MAVCONV.HPP
source code: MAVCONV.CPP

3.3.1 Description

This is not a class, it is a collection of functions you can use to convert
date/numbers to/from strings taking into account national settings of OS/2
to format and check variables.

For dates all of  " ,/-.=*_:" characters are valid
separators.

3.3.2 Main methods

IDate StringToDate(const IString & temps1)

IString DateToString(const IDate & d, const Boolean booNoYear)
booNoYear = true makes year digits not to be swown.

double StringToDouble(IString & temps)

IString DoubleToString(const double d, const Boolean booTh)
booTh = true makes thousands separators to be swown.


3.4 regular expressions

you must include: MAVREGEX.HPP
source code: MAVREGEX.CPP

3.4.1 Description

3.4.2 Main methods

Constructor:

RegEx::RegEx(istream & s1, ostream & s2, IString& strFlags);
s1 and s2 are input and output streams.
s2 will be filled after process() call.
for strFlags see MAVREGEX.CPP.

void RegEx::process(IString & strRegex);
fills the output stream with the matching line.

3.5 directory services

you must include: MAVDRSR.HPP
source code: MAVDRSR.CPP

3.5.1 Description

This is a very simple class that returns the files in a directory.

3.5.2 Main methods

Constructor:

DirServ::DirServ(IString & str1)
str1 is the directory name.

IString DirServ::getNext()
returns the next file in the directory.

INT DirServ::errorCode()
read error code.

4. REGISTRATION

Please read REGISTER.DOC and LICENSE.TXT

5. CONTACTING THE AUTHOR

If you use MAVCL in your program(s) please send your comments to the
address below using the form in REGISTER.DOC.

Your help and encouragement will ensure future versions of MAVCL.

Fabrizio AVERSA
Via Tangorra 1
Rome 00191
Italy
Tel/Fax +39-6-3297747
internet: mc2500@mclink.it

